Install a ready-made view, then make it yours. Or contribute one to the blocks library.
A block is a ready-made view you install and then edit: a login or signup page, an app sidebar shell, a dashboard, a chart. Its files land in your app as code you own, so you spend your time on the app instead of rebuilding a page shell. Browse them on the blocks page.
On the wire a block is a registry:block item. A chart is a block whose categories include chart.
Find a block
List the blocks with their one-line descriptions:
Narrow the list to one category, or print it as JSON for a script or an agent:
The JSON form is one compact array of { name, type, categories, description }. --type chart lists the charts the same way. An agent with the WebJs MCP server can ask the ui tool instead: with no arguments it returns the block and chart names grouped by category, and { type: "block" } or { category: "login" } adds the descriptions. See Skills.
Preview a block
Before installing, see what a block writes and where:
# login-03 (block)
A login page with a muted background color.
categories: authentication, login
registry deps: lib-utils, button, card, field, input
npm: @webjsdev/core
Install: npx @webjsdev/ui add login-03
Files:
app/login/page.ts
components/login-form.ts
Without --files-only, view prints the sources after the file list, baked with your project's style. --json prints the same projection as one document.
Install a block
Run the add command
The command installs the components the block uses, writes each of the block's files to its target and prints the list of files it wrote.
Open the page
The page lands at its route under app/, so login-03 is served at /login as soon as npm run dev picks it up.
A block page renders inside your root layout, like every page. The root layout webjs create writes puts every page in a centered max-w-5xl column under a navbar, and a full-screen block (the login, signup, sidebar and dashboard blocks) needs the whole viewport. Let the root layout render ${children} bare, and move the column into a route group's layout, such as app/(site)/layout.ts, for the pages that want it.
Wire the form
A block ships no server action, so its <form> has no action yet. Bind your own 'use server' action to it:
import { signIn } from '#modules/auth/actions/sign-in.server.ts';
export function loginForm(opts: { class?: string } = {}) {
return html`
<form action=${signIn} class=${cn('flex flex-col gap-6', opts.class)}>
...
</form>
`;
}
The framework then supplies method="post", and the form submits with JavaScript off, re-renders with fieldErrors and values on a failure, and follows the redirect on success. See Forms.
Make it yours
Rename the route, change the copy, swap the logo and the cover image. The files are yours, and nothing upstream changes them again.
What add does
A block installs through the same add command as a component, with a few differences that follow from its files being app code.
- Every file has a target. Each one lands at its own path under the app (
app/...,components/...,modules/...,public/...) rather than in yourcomponents/uifolder. - Imports are rewritten. A block's files import with registry-relative paths.
addrewrites every one to where the imported file landed: a kit component to youruialias, thecn()helper to yourutilsalias, another file of the same block to its own target. - Existing files are kept. A file that already exists is never replaced without
--overwrite, not even under--yes. Blocks of one family share targets (every login block writesapp/login/page.ts), so installing a second one keeps the first one's files unless you ask. Families can overlap too: every sidebar block anddashboard-01writeapp/dashboard/page.ts,components/app-sidebar.ts,components/nav-main.tsandcomponents/nav-user.ts, so addingdashboard-01aftersidebar-07keeps the sidebar block's page and parts and leaves the dashboard's other files unused. Install one app shell per app, or pass--overwriteto switch. - Missing tokens are added. A block that needs design tokens your theme may lack carries them, and
addadds only the ones your stylesheet's:root,.darkor@theme inlineblock does not define. A token you already set is left alone. - Nothing is stripped. A block's files are written whole, with no example removed.
diff includes installed blocks, so npx @webjsdev/ui diff login-03 shows how your copy has moved from the registry's.
Charts
A chart installs the same way and writes one file, components/charts/<name>.ts, plus the chart and card components it uses. Its default export renders the chart's card, so render it from any page:
import { html } from '@webjsdev/core';
import ChartBarInteractive from '#components/charts/chart-bar-interactive.ts';
export default function Page() {
return html`<main class="p-8">${ChartBarInteractive()}</main>`;
}
Browse every chart in the Charts Library.
Add a block to the kit
We'd love to see all types of blocks: applications, marketing, products, and more. A block is contributed to the kit's registry in the WebJs repository.
Fork the repository
git clone https://github.com/webjsdev/webjs.git
Create a new branch
git checkout -b username/my-new-block
Create the block folder
Create a folder named in kebab-case under packages/ui/packages/registry/blocks, and add the block's files to it. A block can be one file or a page with its own parts.
packages
└── ui
└── packages
└── registry
└── blocks
└── login-01
├── page.ts
└── components
└── login-form.ts
Add the block to registry.json
Add an item to packages/ui/packages/registry/registry.json. It follows the same item schema as a component, with a target on every file.
{
"name": "login-01",
"type": "registry:block",
"title": "Login 01",
"description": "A simple login form.",
"categories": ["authentication", "login"],
"registryDependencies": ["lib-utils", "button", "card", "field", "input"],
"dependencies": ["@webjsdev/core"],
"files": [
{
"path": "blocks/login-01/page.ts",
"type": "registry:page",
"target": "app/login/page.ts"
},
{
"path": "blocks/login-01/components/login-form.ts",
"type": "registry:component",
"target": "components/login-form.ts"
}
]
}
Run the tests
npm test --workspace=@webjsdev/ui
The block tests check that every file has a target under the app, exists and is not empty, that every relative import resolves to a file the install also writes, and they install the block into a scratch app and render its page on the server.
Submit a pull request
Commit your changes and open a pull request. Once it is merged and released, the block is listed by list and installs with add.
Categories
The categories property organizes blocks in the registry, broad to specific: ["authentication", "login"], ["chart", "area"]. list --category and the MCP ui tool group and filter by them, and a block whose categories include chart is listed as a chart.
Guidelines
Here are some guidelines to follow when contributing to the blocks library.
- The following properties are required for the block definition:
name,description,type,files, andcategories. - Every file needs a
targetunder the app. A page goes underapp/so the file router serves it. - List every component the block imports in
registryDependencies, pluslib-utilswhen it usescn(). - Imports are registry-relative, for example
'../../../components/card.ts'or'./components/login-form.ts'.addrewrites them to the app's aliases. - A page is a server-rendered page module: a default-exported function, plus a
metadataexport. - A part that is not interactive is a fragment helper, a function returning an
htmltemplate, not a custom element. Two blocks can share a part's name, and a tag can be defined only once per page session. - A form is a real
<form>with named controls and noaction. Its header comment says to bind one. - Draw icons and brand marks as inline SVG.
- Compose the kit's helpers rather than writing their classes by hand, so the block takes the app's style when it is installed.
Do not reach for a third-party runtime dependency in a block. The kit takes none, and a block is held to the same rule.