Repository navigation
Ember Data is a secret dependency breaking consumers of ec-addon-docs #818
Description
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:
- Update the documentation for ec-addon-docs to explicitly ask users to install ember-data as part of the setup guide.
- Add ember-data to the blueprint so that installing ec-addon-docs ensures ember-data is also installed, when using
ember install - 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.
Reacted by Shane Martin, Nathanaël Dekeister, Charles Fries, Camille TJHOA, Oleg Larkin, Robbie Wagner, Andrew Ball, Jason Barry and Kyle Boyd
Reacted by Oleg Larkin and Kyle Boyd
Activity
build: add missing peer deps for `ember-cli-addon-docs`
Reinstall ember-data
Reinstall ember-data
Add ember-cli-addon-docs dependency so does not error
Add ember-cli-addon-docs dependency so does not error
Add ember-cli-addon-docs dependency so does not error
Add ember-cli-addon-docs dependency so does not error
barryofguilder commentedon Nov 17, 2022
I just ran into this issue when trying to upgrade my addon to Ember 4.x. I didn't realize that
ember-datawas added as a devDependency years ago forember-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 commentedon Dec 4, 2024
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 commentedon Dec 4, 2024
Because I'm using
pnpmnow, 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 installember-data, that would be enough. I've seen plenty other libraries mention that multiple things need to be installed for it to work.elwayman02 commentedon Dec 4, 2024
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 commentedon Dec 4, 2024
I think adding to the docs is reasonable. Anyone interested in opening a PR?
barryofguilder commentedon Dec 5, 2024
I've just created this PR for it. I'm not great at wording this, so would love feedback on it.
#1616