Getting Started

Web Component Base (WCB) is a zero-dependency, tiny JS base class for creating reactive custom elements.

When you extend the WebComponent class for your custom element, you only have to define the template and properties. Any change in an observed property’s value will automatically cause the component UI to render.

Quick start

Prerequisites: Node.js (current LTS), which includes npm.

The fastest way to try wcb is to scaffold a new component:

npm create wcb@latest
# or name it directly: npm create wcb@latest my-button

It sets up a publishable custom element, ready to develop:

A starter component in TypeScript using the static props convention. The class, tag, and file names are derived from your project name (my-button → MyButton / <my-button>), so there are no rename-me TODOs
A Vite setup: a dev server with a demo page, plus a library build (npm run build:lib) that emits ESM + UMD bundles and .d.ts types, with web-component-base as a peerDependency
custom-elements.json generation: the CEM analyzer configured with wcb’s plugin, an npm run analyze script, the customElements field in package.json, and a prepack hook so the manifest ships inside the published package

Run the demo page to see the starter component render:

cd my-button
npm install
npm run dev

Vite prints a local URL. Open it to see <my-button> rendered on the demo page. Edit src/MyButton.ts and the page updates as you save.

See the CEM Analyzer Plugin guide for more details on the manifest and how to use it with Storybook and code editors.

Prefer starting on GitHub? The ayo-run/web-component template repository serves the same purpose via “Use this template”.

Install via npm

To add wcb to an existing project instead of scaffolding a new one, install it from npm:

npm i web-component-base

The package ships standard ECMAScript Modules (ESM), so it works with bundlers as well as import maps pointing into node_modules/web-component-base.

Then import the base class with the bare package name:

import { WebComponent } from 'web-component-base'

Continue with Usage to define your first component.

Getting help

Open a GitHub issue or discussion for problems or requests. You can also submit a ticket on SourceHut or via Email.