Frequently asked questions
What does a complex component look like?
Here's an example of a complex component that installs a page, two components, a helper and a config file.
{
"name": "hello-world",
"title": "Hello World",
"type": "registry:block",
"description": "A complex hello world component",
"files": [
{
"path": "blocks/hello-world/page.ts",
"type": "registry:page",
"target": "app/hello/page.ts"
},
{
"path": "blocks/hello-world/components/hello-world.ts",
"type": "registry:component"
},
{
"path": "blocks/hello-world/components/formatted-message.ts",
"type": "registry:component"
},
{
"path": "blocks/hello-world/lib/format-date.ts",
"type": "registry:lib"
},
{
"path": "blocks/hello-world/hello.config.ts",
"type": "registry:file",
"target": "hello.config.ts"
}
]
}
The page lands at its target, the two components in the project's components folder, the helper in its lib folder, and the config file at the project root. A target is a path from the project root, written as is.
How do I add a new Tailwind color?
To add a new color you need to add it to cssVars under light and dark keys, and map it to a Tailwind color under theme.
{
"name": "hello-world",
"title": "Hello World",
"type": "registry:block",
"description": "A complex hello world component",
"files": [
// ...
],
"cssVars": {
"theme": {
"color-brand": "var(--brand)",
"color-brand-accent": "var(--brand-accent)"
},
"light": {
"brand": "oklch(0.205 0.015 18)",
"brand-accent": "oklch(0.205 0.015 18)"
},
"dark": {
"brand": "oklch(0.205 0.015 18)",
"brand-accent": "oklch(0.205 0.015 18)"
}
}
}
The CLI will update the project CSS file: light goes in the :root block, dark in .dark, and theme in @theme inline, the way the WebJs UI theme is laid out. Once updated, the new colors will be available to be used as utility classes: bg-brand and text-brand-accent. The theme entries are what make the utilities exist, since the CLI does not generate them from light and dark.
Why does button in registryDependencies not resolve to the WebJs UI button?
A registry dependency is a name, and the CLI fetches it from the same registry as the item that lists it. In an item served from https://acme.com/r, button means https://acme.com/r/button.json.
Every dependency comes from the item's own registry. If your item builds on a WebJs UI component, tell users to install it first, or ship your own copy in your registry.
How do I pin a registry item?
Put the version in the base URL. The CLI appends /<name>.json to whatever base it is given, so a versioned folder or a git ref in a raw URL pins every item and every dependency fetched with it.
For published registries, prefer tags or full commit SHAs. See GitHub Registries.
Can a registry be private?
Only by where it can be reached or by what its URL contains. The CLI sends no credentials, no custom headers and no cookies. See Authentication.
How do I add or override a Tailwind theme variable?
To add a theme variable you add it to cssVars.theme under the key you want to add.
{
"name": "hello-world",
"title": "Hello World",
"type": "registry:block",
"description": "A complex hello world component",
"files": [
// ...
],
"cssVars": {
"theme": {
"text-base": "3rem",
"ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
"font-heading": "Poppins, sans-serif"
}
}
}
The CLI adds only the variables the project does not define yet, each in its own block, and leaves every existing one as it is. To change a value the project already sets, such as --primary, tell users to edit their stylesheet, or ship a registry:file they import after the theme.
Why is @webjsdev/core installed when my item lists no dependencies?
add always installs @webjsdev/core along with an item's dependencies, since every kit file builds on it. Pass --no-deps to skip installing packages altogether.