Ember Data is a secret dependency breaking consumers of ec-addon-docs

[elwayman02]

It's marked as a peerDependency, but it is required for ec-addon-docs to run properly. If the consuming project does not have ember-data in its package.json, ec-addon-docs breaks and throws an error, and the docs will not render. However, we can't specify it as a dependency within ec-addon-docs, either.

Addons do not ship with ember-data by default, as it is not part of the addon blueprint. Most addons don't have a need to install it either, as most addons won't be doing any data fetching. So, we cannot count on ember-data to be present in order to ship a working experience to users of this project.

There are three possible solutions which could be used in conjunction with one another:

1. Update the documentation for ec-addon-docs to explicitly ask users to install ember-data as part of the setup guide.
2. Add ember-data to the blueprint so that installing ec-addon-docs ensures ember-data is also installed, when using ember install
3. Use version checker to have addon-docs throw an error if a valid version of ember-data (currently 3.0+) is not present in the consuming addon.

[barryofguilder]

I just ran into this issue when trying to upgrade my addon to Ember 4.x. I didn't realize that ember-data was added as a devDependency years ago for ember-cli-addon-docs. I removed it since it was pointing to 3.x, then I spent a while trying to figure out why I was getting this error in my dev console:

[RobbieTheWagner]

I realize this thread is old, but how do we feel about this today? A peerDependency does mean it is required to run. I think the problem is some folks use things that magically install peers automatically, and they do not get the warnings something like pnpm would give when the peerDep is not installed.

[barryofguilder]

Because I'm using pnpm now, it's not as big of a deal. But, I lost a lot of time in the past with this. I think if the docs mention that you also need to install ember-data, that would be enough. I've seen plenty other libraries mention that multiple things need to be installed for it to work.

[elwayman02]

I think option 1 is a must, and very low effort. Option 3 would still be pretty reasonable if it's going to break without that dependency, and I think that's fairly standard practice for peerDeps that are critical (as opposed to, say, testing-only peerDeps that are somewhat optional).

[RobbieTheWagner]

I think adding to the docs is reasonable. Anyone interested in opening a PR?

[barryofguilder]

I've just created this PR for it. I'm not great at wording this, so would love feedback on it.

#1616