NV Elements Catalog Starters Repo System Themes About Getting Started Changelog Metrics Support Accessibility Contributions Requests Migration Deprecations Integrations Installation MCP CLI Lint Angular Bundles Extensions Go Hugo Import Maps Lit NextJS Nuxt Preact React SolidJS Svelte TypeScript Vue Foundations Typography Iconography Themes Design Tokens Size & Space Objects Interactions Support Status Color Animation Fonts Layers Custom Layout Horizontal Vertical Grid Popovers i18n Visualization View Transitions Elements Accordion Alert Avatar Badge Breadcrumb Button Button Group Card Chat Message Checkbox Color Combobox Copy Button Datagrid Integrations Column Action Column Alignment Column Fixed Column width Container Card Display Settings Footer Heatmap Keynav Multi Select Pagination Panel Detail Panel Grid Performance Placeholder Row Action Row Groups Row Sort Scroll Height Single Select Stripe Date Datetime Dialog Divider Dot Drawer Dropdown Dropdown Group Dropzone File Forms Validation Actions Control Icon Icon Button Input Input Group Logo Menu Month Notification Page Page Header Page Loader Pagination Panel Progressive Filter Chip Progress Bar Progress Ring Password Preferences Input Pulse Radio Range Resize Handle Search Select Skeleton Sort Button Sparkline Star Rating Steps Switch Tabs Tag Textarea Time Toast Toggletip Toolbar Tooltip Tree Week Patterns Authentication Browse Dashboard Editor Empty States Heatmap Keyboard Shortcut Logging Media Onboarding Panel Responsive Search Subheader Trend Code Codeblock Monaco Input Diff Input Editor Diff Editor Problems Markdown Markdown CSS Utility Labs Responsive Layout Viewport Container Patterns Forms API Design Properties & Attributes Slots Registration CustomEvents Stateless Composition Styles Packaging Glossary Logs Internal Guidelines Agent Harness Documentation Examples TypeScript Testing Unit Testing Accessibility Testing Lighthouse Testing SSR Testing Visual Testing Troubleshooting Component Creation Internal Examples All Examples

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.

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.

Warning: avoid alternate build targets as it increases complexity and is unnecessary with modern build tools and browsers.

🎓 Learn: publishing Web Components

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.

Side Effects & Registration

Elements should not automatically register themselves to the customElementsRegistry. Rather you should isolate side effects like registration to a single file.

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.

Isolated registration allows the consumer to control when to load an element. This future proofs the API to allow scoped element registries.

Warning: isolated side-effects are critical for certain micro-frontend use cases.

The package.json should have the sideEffects entry set to false and list any element registrations to the explicit sideEffects entry. This enables tools like Webpack and Rollup to properly define dependency graphs and tree-shake.

🎓 Learn: elements documentation

🎓 Learn: scoped element registry

🎓 Learn: case study