Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Testing and Tooling

Building and Publishing Lit Components

Turn a Lit component into a reusable package: project layout, TypeScript and bundling, package.json exports, the Custom Elements Manifest, naming rules and release checks.

A component that works on your page is a prototype. A component other teams can install is a product: it has a stable name, a clean package layout, type declarations, documentation and a release process. The good news is that web components make distribution simple, because every framework (and no framework) can use a custom element.

This lesson covers the package side. The build commands are read-only here, because they need Node and npm on your machine, but the two small examples (name rules and a manifest generator) run on this page.

Name your elements carefully

A custom element name must contain a hyphen, start with a lowercase letter, and cannot be one of a few reserved names such as font-face or annotation-xml. Because all names share one global registry, library authors add a prefix: acme-button, acme-dialog. Two packages that define the same tag name clash, and the second customElements.define call throws.

JS Check element names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real rule uses a longer character list (it allows some non-ASCII characters), so treat this checker as the 95 percent version, and let the browser have the final say.

Project layout

A tidy library looks like this:

TEXT
acme-ui/
  package.json
  tsconfig.json
  custom-elements.json        <- generated manifest
  src/
    acme-button.ts            <- one component per file
    acme-dialog.ts
    index.ts                  <- re-exports everything
  test/
    acme-button.test.ts
  dist/                       <- build output (not committed)

Each component file should define and register its element, so that import "acme-ui/acme-button.js" is all a user needs. Also export the class, so people can extend it.

TypeScript and decorators

Lit works in plain JavaScript, but most libraries ship TypeScript. Lit's decorators (@customElement, @property, @state) are optional sugar over the static properties block you already know. Prefer the standard decorator syntax of recent TypeScript versions, and set target to a modern level so classes are not downleveled (downleveled classes break native custom elements).

TypeScript
import { LitElement, html, css } from "lit";
import { customElement, property } from "lit/decorators.js";

@customElement("acme-badge")
export class AcmeBadge extends LitElement {
  static styles = css`:host { display: inline-block; }`;

  @property() label = "";

  render() {
    return html`<span>${this.label}</span>`;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    "acme-badge": AcmeBadge;
  }
}

That declare global block gives editors the right type for document.querySelector("acme-badge").

package.json: the contract

JSON
{
  "name": "@acme/ui",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./acme-button.js": { "types": "./dist/acme-button.d.ts", "default": "./dist/acme-button.js" }
  },
  "files": ["dist", "custom-elements.json"],
  "customElements": "custom-elements.json",
  "sideEffects": ["./dist/acme-*.js"],
  "peerDependencies": { "lit": "^3.0.0" }
}

Points that matter:

  • lit is a peer dependency, not a dependency. If every library bundles its own Lit, the page downloads it many times and Lit prints a "multiple versions" warning.
  • exports limits what users can import, so you can reorganize internals without a breaking change.
  • sideEffects tells bundlers that files which only call customElements.define must not be dropped as "unused".
  • files keeps tests and sources out of the published tarball.

Ship plain modules, bundle only the demo

Publish unbundled ES modules (just the compiler output). Application bundlers can then share one copy of Lit and tree-shake. Bundle only for a single-file CDN build or your docs site. A common tool chain: tsc for modules, Vite or Rollup for the optional bundle.

JSON
{
  "scripts": {
    "build": "tsc",
    "analyze": "cem analyze --litelement",
    "test": "wtr",
    "prepublishOnly": "npm run build && npm run analyze && npm test"
  }
}

The Custom Elements Manifest

custom-elements.json describes your components as data: tag names, properties, attributes, events, slots, CSS parts and custom properties. The @custom-elements-manifest/analyzer command (cem analyze) generates it by reading your source and its JSDoc tags. Editors use it for autocomplete, and documentation tools build API tables from it.

Your JSDoc comments become documentation:

JavaScript
/**
 * A small status badge.
 * @element acme-badge
 * @slot - Optional icon placed before the label
 * @fires badge-click - Fired when the badge is activated
 * @csspart label - The text wrapper
 * @cssprop [--acme-badge-color=#333] - Text color
 */

You can see the idea without the tool: the script below reads a component class's properties and produces a tiny manifest entry.

A hand-made manifest

elementProperties is the real map Lit builds from static properties, so the output is accurate; the official analyzer additionally reads types, defaults and JSDoc from source.

Release checklist

  1. npm run build is clean and dist contains only what you expect (npm pack --dry-run lists the files).
  2. Tests pass in all target browsers.
  3. The version follows semantic versioning: a renamed attribute or tag is a breaking change.
  4. The manifest and the README examples match the current API.
  5. Publish with npm publish --access public (scoped packages are private by default).

Test the published package in a blank page before you announce it: npm pack produces a tarball you can install locally to see exactly what users get. After that, you are ready to apply everything in the project lessons.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should lit be a peerDependency of a component library?

    Multiple copies of Lit waste bandwidth and trigger a multiple-versions warning. A peer dependency lets the application decide the one version.
  2. 2. What is a valid custom element name?

    Names need a hyphen, must be lowercase and start with a letter. Prefixes prevent clashes in the global registry.
  3. 3. What does the sideEffects field in package.json protect?

    Bundlers drop modules whose exports are unused. A component file is imported for its registration side effect, so it must be listed.
  4. 4. What is custom-elements.json for?

    The Custom Elements Manifest lists tags, attributes, events, slots and parts for editors and documentation generators.

Summary

  • Prefix tag names; the registry is global.
  • Publish unbundled modules with lit as a peer dependency.
  • Use exports, files and sideEffects deliberately.
  • Generate a Custom Elements Manifest from JSDoc.
  • Check npm pack --dry-run and test the tarball before publishing.

Next: Project: A Todo List Component