Packaging
Dependencies
Dependencies should be carefully considered as they impose the cost onto all consumers. Before adding dependencies, consider the following:
- Can the Web Platform do this today?
- Can something on the Web Platform standards track + polyfill do this?
- Is this dependency tree-shakable and has minimal performance impact?
- Does this dependency avoid polluting globals and prototypes?
List dependencies within the published package.json and do not bundle them with the library. The host application handles bundling dependencies, enabling its build pipeline to tree-shake and de-duplicate dependencies.
{
"dependencies": {
"@floating-ui/dom": "^1.0.3",
"lit": "^3.2.0",
"lit-html": "^3.2.0"
},
"optionalDependencies": {
"@lit-labs/scoped-registry-mixin": "^1.0.1",
"@webcomponents/scoped-custom-element-registry": "^0.0.9",
"construct-style-sheets-polyfill": "^3.1.0",
"element-internals-polyfill": "^1.3.10"
}
}
If a dependency is a feature or optional, list it under the optional dependencies.
Build Output
Element libraries should not bundle elements or dependencies. This prevents the host application build from being able to tree-shake or construct an accurate representation of the dependency tree. But you can still apply minification to each module independently.
Build outputs should target the latest ES2020+. Build outputs should not compile to ES5 and only ship standard ESM modules. Host applications can always compile dependencies down to an older version of ES.
Entrypoints
Each element should provide a standalone entrypoint for consumption. This enables consumers to choose which elements to load/import, improving performance and API stability.
import { Button } from '@nvidia-elements/core/button';
import { Dialog } from '@nvidia-elements/core/dialog';
Side Effects & Registration
Elements should not automatically register themselves to the customElementsRegistry. Export the class from index.ts and isolate registration in define.ts.
// dialog/define.ts
import { define } from '@nvidia-elements/core/internal';
import { Dialog, DialogHeader, DialogFooter } from '@nvidia-elements/core/dialog';
define(Dialog);
define(DialogHeader);
define(DialogFooter);
If an element depends on other elements then you should include those elements in the registration file as well to ensure the build constructs a proper dependency tree.
import '@nvidia-elements/core/button/define.js';
import '@nvidia-elements/core/dialog/define.js';
Isolated registration allows the consumer to control when to load an element. This future proofs the API to allow scoped element registries.
The package.json should use a sideEffects array that lists registration and bundle outputs. Do not set sideEffects to false when define.js files ship side effects.
{
"sideEffects": [
"./dist/bundles/*.js",
"./**/define.js",
"./**/server.js"
]
}
This enables tools like Webpack and Rollup to preserve explicit registration entrypoints while still tree-shaking side-effect-free component modules.