registry:style
Note: The look of the WebJs UI components is chosen by the style field of components.json, which the CLI bakes into every file it writes. A registry:style item does not change that. It installs like any other item: its files, its dependencies and its CSS variables.
Custom style that builds on the kit
The following registry item bundles a starting point for Acme apps. On add, it will:
- Install
date-fnsas a dependency. - Add the
login-01andcalendaritems from the same registry. - Set the
font-sansvariable toInter, sans-serif, if the stylesheet does not set it. - Install a
brandcolor in light and dark mode.
{
"name": "example-style",
"type": "registry:style",
"dependencies": ["date-fns"],
"registryDependencies": ["login-01", "calendar"],
"cssVars": {
"theme": {
"font-sans": "Inter, sans-serif",
"color-brand": "var(--brand)"
},
"light": {
"brand": "oklch(0.205 0.015 18)"
},
"dark": {
"brand": "oklch(0.985 0 0)"
}
}
}
Custom style from scratch
A style from scratch is a style item whose registryDependencies are all your own items, and whose CSS variables are new names. The CLI installs exactly what an item lists.
{
"name": "new-style",
"type": "registry:style",
"registryDependencies": ["button", "input", "label", "select"],
"cssVars": {
"theme": {
"color-main": "var(--main)",
"color-bg": "var(--bg)"
},
"light": {
"main": "#88aaee",
"bg": "#dfe5f2"
},
"dark": {
"main": "#88aaee",
"bg": "#272933"
}
}
}
Here button, input, label and select are fetched from your registry. Each lands in the user's components/ui folder, and add asks before replacing a file of the same name that is already there.
registry:theme
Custom theme
A theme item's cssVars add the variables a project does not define. A project that ran webjs ui init already defines --background, --primary and the rest, so to change those values, ship the theme as a CSS file and tell users to import it after their theme.
{
"name": "custom-theme",
"type": "registry:theme",
"files": [
{
"path": "themes/blue.css",
"type": "registry:file",
"target": "styles/theme-blue.css"
}
]
}
:root {
--primary: oklch(0.546 0.245 262.881);
--primary-foreground: oklch(0.97 0.014 254.604);
--ring: oklch(0.746 0.16 232.661);
}
.dark {
--primary: oklch(0.707 0.165 254.624);
--primary-foreground: oklch(0.97 0.014 254.604);
--ring: oklch(0.707 0.165 254.624);
}
Custom colors
The following item adds a custom brand color to a project that has the default theme.
{
"name": "custom-colors",
"type": "registry:theme",
"cssVars": {
"theme": {
"color-brand": "var(--brand)"
},
"light": {
"brand": "oklch(0.99 0.00 0)"
},
"dark": {
"brand": "oklch(0.14 0.00 286)"
}
}
}
registry:block
Custom block
This block installs a login page and the form component it renders.
{
"name": "login-01",
"type": "registry:block",
"description": "A simple login form.",
"categories": ["authentication", "login"],
"registryDependencies": ["button", "card", "input", "label"],
"files": [
{
"path": "blocks/login-01/page.ts",
"content": "import { html } from '@webjsdev/core'; ...",
"type": "registry:page",
"target": "app/login/page.ts"
},
{
"path": "blocks/login-01/components/login-form.ts",
"content": "...",
"type": "registry:block",
"target": "components/login-form.ts"
}
]
}
Every file of a block names its target, so the page lands at its route. An existing block file is kept unless add is run with --overwrite, since it is app code the user owns.
Install a block with your own primitives
A block's registry dependencies come from the block's own registry. So a block that depends on button, input and label installs your versions of them, not the WebJs UI ones, and the user is asked before an existing file is replaced.
{
"name": "custom-login",
"type": "registry:block",
"registryDependencies": ["login-01", "button", "input", "label"]
}
registry:ui
UI component
A registry:ui item is a reusable UI component. It can have dependencies, registry dependencies, and CSS variables. A Tier-1 component is a set of class helpers, a Tier-2 component a custom element built on @webjsdev/core.
{
"name": "button",
"type": "registry:ui",
"files": [
{
"path": "components/button.ts",
"content": "...",
"type": "registry:ui"
}
]
}
UI component with CSS variables
{
"name": "sidebar",
"type": "registry:ui",
"registryDependencies": ["button", "separator", "sheet", "tooltip"],
"files": [
{
"path": "components/sidebar.ts",
"content": "...",
"type": "registry:ui"
}
],
"cssVars": {
"light": {
"sidebar": "oklch(0.985 0 0)",
"sidebar-foreground": "oklch(0.141 0.005 285.823)",
"sidebar-border": "oklch(0.92 0.004 286.32)"
},
"dark": {
"sidebar": "oklch(0.141 0.005 285.823)",
"sidebar-foreground": "oklch(0.985 0 0)",
"sidebar-border": "oklch(0.274 0.006 286.033)"
}
}
}
On add, each variable the user's stylesheet lacks is added to its :root or .dark block, so the component renders in an app whose theme predates it.
registry:lib
Utility library
A registry:lib item is a utility library. Use it to share helper functions, constants, or other non-component code. Its files land in the lib folder components.json names.
{
"name": "format",
"type": "registry:lib",
"dependencies": ["date-fns"],
"files": [
{
"path": "lib/format.ts",
"content": "export { format } from 'date-fns';",
"type": "registry:lib"
}
]
}
registry:hook
Custom controller
A registry:hook file lands in hooks/, which suits reusable component logic such as a reactive controller.
{
"name": "media-query",
"type": "registry:hook",
"files": [
{
"path": "hooks/media-query.ts",
"content": "...",
"type": "registry:hook"
}
]
}
Targets
A target is a path from the project root, written as is, and it decides where the file lands even when it differs from the file type.
{
"name": "type-mismatch",
"type": "registry:item",
"files": [
{
"path": "lib/format-date.ts",
"type": "registry:ui",
"target": "lib/format-date.ts",
"content": "..."
}
]
}
To land a file in the user's configured folder instead, leave out target and let the file type pick it: registry:ui for aliases.ui, registry:component for aliases.components, registry:lib for aliases.lib.
registry:font
Ship the font family as a theme variable, and the font files, if any, as registry:file entries.
{
"name": "font-inter",
"type": "registry:font",
"cssVars": {
"theme": {
"font-sans": "'Inter Variable', sans-serif"
}
}
}
registry:base
A registry:base item gets no special handling either. A whole design system ships as a style item whose registryDependencies list its components, as in Custom style from scratch.
Common Fields
Author
Use the author field to add attribution to your registry items. It is kept in the item, and the CLI does not print it.
{
"name": "custom-component",
"type": "registry:ui",
"author": "Acme",
"files": [
{
"path": "components/custom-component.ts",
"content": "...",
"type": "registry:ui"
}
]
}
Dev dependencies
Use the devDependencies field to install packages as dev dependencies.
{
"name": "custom-item",
"type": "registry:item",
"devDependencies": ["@types/node"],
"files": [
{
"path": "lib/paths.ts",
"content": "...",
"type": "registry:lib"
}
]
}
Metadata
Use the meta field to attach arbitrary metadata to your registry items. This can be used to store custom data that your tools or scripts can use.
{
"name": "custom-component",
"type": "registry:ui",
"meta": {
"category": "forms",
"version": "2.0.0"
},
"files": [
{
"path": "components/custom-component.ts",
"content": "...",
"type": "registry:ui"
}
]
}
CSS Variables
Custom Theme Variables
Add custom theme variables to the theme object. They land in the stylesheet's @theme inline block.
{
"name": "custom-theme",
"type": "registry:theme",
"cssVars": {
"theme": {
"font-heading": "Inter, sans-serif",
"shadow-card": "0 0 0 1px rgba(0, 0, 0, 0.1)"
}
}
}
Override Tailwind CSS variables
A theme entry for one of Tailwind's own variables overrides Tailwind's default, because the default lives in Tailwind and not in the project's stylesheet. A variable the stylesheet already defines is left alone.
{
"name": "custom-theme",
"type": "registry:theme",
"cssVars": {
"theme": {
"spacing": "0.2rem",
"breakpoint-sm": "640px",
"breakpoint-md": "768px",
"breakpoint-lg": "1024px",
"breakpoint-xl": "1280px",
"breakpoint-2xl": "1536px"
}
}
}
Add custom CSS
Base styles, component styles, @utility rules, @import, @plugin and @keyframes all ship the same way: as a CSS file the user imports.
{
"name": "acme-css",
"type": "registry:style",
"files": [
{
"path": "styles/acme.css",
"type": "registry:file",
"target": "styles/acme.css"
}
]
}
@layer base {
h1 {
font-size: var(--text-2xl);
}
}
@utility content-auto {
content-visibility: auto;
}
@keyframes wiggle {
0%, 100% { transform: rotate(-3deg); }
50% { transform: rotate(3deg); }
}
Users then import it after Tailwind in their stylesheet:
@import "tailwindcss";
@import "./acme.css";
Add environment variables
Ship example variables as a file.
{
"name": "custom-item",
"type": "registry:item",
"files": [
{
"path": "env/.env.example",
"type": "registry:file",
"target": ".env.example"
}
]
}
IMPORTANT: Ship development or example variables only. Do NOT put production values or secrets in a registry item.
Universal Items
An item whose files all name a target installs the same way in any project, whatever its components.json aliases say. The project still needs a components.json, since add stops without one.
Here's an example of a registry item that installs agent rules:
{
"name": "acme-rules",
"type": "registry:item",
"files": [
{
"path": "rules/acme.md",
"type": "registry:file",
"target": ".agents/rules/acme.md",
"content": "..."
}
]
}
You can also have a universal item that installs multiple files:
{
"name": "my-custom-starter-template",
"type": "registry:item",
"dependencies": ["zod"],
"files": [
{
"path": "starter/app/page.ts",
"type": "registry:file",
"target": "app/page.ts",
"content": "..."
},
{
"path": "starter/modules/home/queries/get-home.server.ts",
"type": "registry:file",
"target": "modules/home/queries/get-home.server.ts",
"content": "..."
}
]
}