Document which dependencies must be installed, and which must not - #2234
Document which dependencies must be installed, and which must not#2234NullVoxPopuli wants to merge 1 commit into
Conversation
✅ Deploy Preview for ember-guides ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| ### `@glimmer/*` | ||
|
|
||
| - `@glimmer/tracking` |
There was a problem hiding this comment.
I swear we were chasing down a few other @\glimmer/* ones before.. maybe runtime?
There was a problem hiding this comment.
there are a bunch more glimmer packages provided from build-plugins + ember-source, but I haven't listed them here because they aren't public
There was a problem hiding this comment.
ember-source/package.json#ember-addon.renamed-modules is the source of truth tho
There was a problem hiding this comment.
the latest release has this:
"@glimmer/destroyable/index.js": "ember-source/@glimmer/destroyable/index.js",
"@glimmer/encoder/index.js": "ember-source/@glimmer/encoder/index.js",
"@glimmer/env/index.js": "ember-source/@glimmer/env/index.js",
"@glimmer/global-context/index.js": "ember-source/@glimmer/global-context/index.js",
"@glimmer/manager/index.js": "ember-source/@glimmer/manager/index.js",
"@glimmer/node/index.js": "ember-source/@glimmer/node/index.js",
"@glimmer/opcode-compiler/index.js": "ember-source/@glimmer/opcode-compiler/index.js",
"@glimmer/owner/index.js": "ember-source/@glimmer/owner/index.js",
"@glimmer/program/index.js": "ember-source/@glimmer/program/index.js",
"@glimmer/reference/index.js": "ember-source/@glimmer/reference/index.js",
"@glimmer/runtime/index.js": "ember-source/@glimmer/runtime/index.js",
"@glimmer/tracking/index.js": "ember-source/@glimmer/tracking/index.js",
"@glimmer/tracking/primitives/cache/index.js": "ember-source/@glimmer/tracking/primitives/cache/index.js",
"@glimmer/util/index.js": "ember-source/@glimmer/util/index.js",
"@glimmer/validator/index.js": "ember-source/@glimmer/validator/index.js",
"@glimmer/vm/index.js": "ember-source/@glimmer/vm/index.js",
"@glimmer/wire-format/index.js": "ember-source/@glimmer/wire-format/index.js",
claude just tried to tell me I needed to install @glimmer/validator due to type compilation issue, we should at least make sure the full list (including private) is included somewhere like a skill we can have things pick it up easily
There was a problem hiding this comment.
No normal person should be concerned with thase packages tho. Experts, such as yourself, can have expert knowledge, like how to solve the issue you described.
However, the types for all glimmer packages are provided by ember-source, provided your default ember-source is new enough.
My fear is that including everything will mislead AI and it'll try to 'be clever', and lead users astray
|
The lint is complaining about the Important text here > [!important]
> text herewhich is valid -- so... maybe the linter is wrong? or the renderer for the markdown syntax is out of date? |
|
Also needs an entry here @NullVoxPopuli. |
|
|
||
| ## Must be present in package.json | ||
|
|
||
| These packages are not provided automatic by any build tooling, and exist as standalone packages on npm. |
There was a problem hiding this comment.
| These packages are not provided automatic by any build tooling, and exist as standalone packages on npm. | |
| These packages are not provided automatically by any build tooling, and exist as standalone packages on npm. |
|
|
||
|
|
||
|
|
||
| ## Must be present in package.json |
There was a problem hiding this comment.
must be present where? as deps or devdeps?
There was a problem hiding this comment.
Additionally, I think this section should clarify it is re-emphasizing the base rule of "if import -> must declare"
The previous section were the exceptions, and here we're extra-clarifying certain packages that look similar to the exceptions do need to be declared.
So something like:
"These packages, despite looking very similar to some of the packages that are provided by the build tooling, do need to be declared, just like any other module import that is not in the list above."
There was a problem hiding this comment.
must be present where? as deps or devdeps?
Doesn't matter for apps,
Dependencies for libraries
| > If you import it, you must declare it (in `dependencies` or `peerDependencies` in your package.json) | ||
|
|
||
|
|
||
| ## Available via build tools |
There was a problem hiding this comment.
This section should explicitly clarify that these dependencies do not need to be declared in the deps. "Available via build tools" does not mean much to a new user.
| Not all modules need to be declared in the package.json, but for the most part | ||
|
|
||
| > [!important] | ||
| > If you import it, you must declare it (in `dependencies` or `peerDependencies` in your package.json) |
There was a problem hiding this comment.
Needs clarification, cause otherwise this contradicts the previous sentence. The "for the most part" isn't really cutting it.
something along the lines of:
"As a ground rule, every module that's imported needs to be declared either in dependencies or peerDependencies. However, there are some exceptions, where the imported modules are provided by the ember build tooling instead of the normal package resolution.
This document describes those exceptions."
|
|
||
| ### Other / Supporting | ||
|
|
||
| - `@embroider/macros` (requires babel) |
There was a problem hiding this comment.
the "requires babel" is a bit out of left field - does that mean babel needs to be a dep? devDep? Isn't babel always required anyway?
There was a problem hiding this comment.
Some libraries don't seed babel, is all
|
While it may not have been the initial intention, I feel like this doc would also be the place to explain what to do with the EDIT: I mention this cause I thought the document targeted addon devs, but it actually doesn't mention who it's for, which usually means it's meant for app devs. |
4 participants
This hasn't been described anywhere, and has been a major point of confusion in the community