65 lines
2.9 KiB
Text
65 lines
2.9 KiB
Text
---
|
|
title: Getting Started
|
|
slug: getting-started
|
|
---
|
|
|
|
**Web Component Base (WCB)** is a zero-dependency, tiny JS base class for creating reactive [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components/Using_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](https://nodejs.org) (current LTS), which includes npm.
|
|
|
|
The fastest way to try wcb is to scaffold a new component:
|
|
|
|
```bash
|
|
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`](/prop-access/) 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:
|
|
|
|
```bash
|
|
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](/cem-plugin/) 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`](https://github.com/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](https://www.npmjs.com/package/web-component-base):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```js
|
|
import { WebComponent } from 'web-component-base'
|
|
```
|
|
|
|
Continue with [Usage](/usage) to define your first component.
|
|
|
|
:::tip[Prefer a CDN?]
|
|
You can also import wcb straight from a CDN in vanilla JS or HTML files — see the [CodePen examples](/examples/#codepen-examples) for working setups.
|
|
:::
|
|
|
|
## Getting help
|
|
|
|
Open a [GitHub issue](https://github.com/ayo-run/wcb/issues/new) or [discussion](https://github.com/ayo-run/wcb/discussions) for problems or requests. You can also submit a ticket on [SourceHut](https://todo.sr.ht/~ayoayco/wcb).
|