The components.json file holds configuration for your project.
The CLI uses it to understand how your project is set up and how to write components customized for your project.
It is only required if you're using the CLI to add components to your project. If you're using the copy and paste method, you don't need this file.
You can create a components.json file in your project by running the following command:
Inside a WebJs app the same command is webjs ui init, and an app made with webjs create already has the file. See the CLI section for more information.
$schema
init writes the following $schema value. The CLI does not fetch it: it validates the file against its own schema, which is strict, so a key it does not know is an error rather than a silent no-op.
{
"$schema": "https://ui.webjs.dev/schema.json"
}
style
The style for your components. The kit authors every component once, with semantic cn-* class names, and add bakes the chosen style into the file it writes, so the copy in your project holds plain Tailwind classes.
{
"style": "new-york"
}
The styles are new-york, vega, nova, maia, lyra, mira, luma, sera and rhea. init writes "default", which means new-york, and so does a name the kit does not ship. init --style <name>, or a preset from Create (init --preset <code>), writes another.
The style is read each time you run add, so changing it later affects only the components you add afterwards. The ones already in your project keep the classes they were baked with until you add them again with --overwrite, and diff reports them as out of date in the meantime.
tailwind
Configuration to help the CLI understand how Tailwind CSS is set up in your project.
See the installation section for how to set up Tailwind CSS.
tailwind.config
The kit targets Tailwind CSS v4, which is configured in CSS. The key is accepted so an older config still parses. Leave it out.
tailwind.css
Path to the CSS file that imports Tailwind CSS into your project. init appends the theme tokens to it, and add writes the tokens back if they go missing and merges in the CSS variables a component or block carries.
{
"tailwind": {
"css": "styles/globals.css"
}
}
The default is styles/globals.css, not app/globals.css, because in a WebJs app the app/ directory holds routes only. init --css <path> points it somewhere else.
tailwind.baseColor
This is used to generate the default theme tokens for your components.
{
"tailwind": {
"baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe"
}
}
The tokens are written once. init marks where the theme block it appends starts and ends, and a later plain run, or an add, leaves the block as it is. Changing baseColor in this file therefore does not repaint an existing project. To repaint it, run init --base-color <name> --overwrite or init --preset <code>, which replace the marked block in place (--overwrite also resets the aliases and the helper files), or edit the variables by hand. A block written before the end marker existed is never replaced, only reported. See the theming docs.
tailwind.cssVariables
The kit uses CSS variables for theming, and only CSS variables. Every component is written against semantic tokens like background, foreground and primary.
{
"tailwind": {
"cssVariables": true
}
}
init writes true, which the components are built for: their classes name the theme tokens. For more information, see the theming docs.
tailwind.prefix
A component lands with Tailwind's unprefixed utilities, so leave the prefix empty.
rsc
A page renders on the server, and a component that needs JavaScript ships it on its own, with nothing to mark. Leave rsc out of components.json: the config schema is strict, so an unknown key is an error.
tsx
The kit ships TypeScript sources, so leave tsx out of components.json. WebJs strips the types when it serves a file, with no build step, so a JavaScript app imports the .ts files as they are. See JavaScript.
aliases
The CLI uses these values to place the files it writes. Each one is a directory path relative to the project root, not an import specifier. A leading @/ is accepted and dropped.
Inside the files it writes, the CLI rewrites every registry import to a relative path that resolves from where the file landed, so components/ui/dialog.ts imports ../../lib/utils/cn.ts and ./button.ts. Relative imports need no alias configuration at all, which is why the aliases here are plain paths.
Your own code imports the installed files through the app's # package import, for example #components/ui/button.ts. That comes from package.json, not from components.json. Do not write #components as an alias value here: it is read as a directory named #components. See Package Imports.
{
"aliases": {
"components": "components",
"utils": "lib/utils/cn",
"ui": "components/ui",
"lib": "lib"
}
}
These are the values init and webjs create both write, so a scaffolded app and an app that ran init share one layout.
For monorepos, see the monorepo docs.
aliases.utils
The path of your cn() helper, without the extension. lib/utils/cn is the file lib/utils/cn.ts. The client-only onBeforeCache() helper is written beside it, as lib/utils/dom.ts.
{
"aliases": {
"utils": "lib/utils/cn"
}
}
Both helpers are yours once they exist: init and add leave an existing copy alone, and only --overwrite replaces it.
aliases.components
The directory for your components.
{
"aliases": {
"components": "components"
}
}
aliases.ui
The directory for ui components.
The CLI uses the aliases.ui value to determine where to place your ui components. Use this config if you want to customize the installation directory for your ui components.
{
"aliases": {
"ui": "modules/design/ui"
}
}
aliases.lib
The directory for lib files that a registry item installs.
{
"aliases": {
"lib": "lib"
}
}
aliases.hooks
WebJs components keep state in signals and reactive properties. Reusable component logic, such as a reactive controller, ships as a registry:hook file and lands in hooks/.
iconLibrary
The icon library the components and blocks draw with: lucide (the default), tabler, hugeicons, phosphor or remixicon. The icons are inline SVG, so no icon package is installed. An item that draws icons depends on the kit's icon module, and add installs the one for this library at lib/utils/icons.ts, beside cn.ts. init --icons <library>, or a preset, sets the key and writes that file.
{
"iconLibrary": "lucide"
}
lint
The opt-in design-system linter, webjs ui lint, reads its configuration from here. With no lint block it reports nothing and exits 0.
{
"lint": {
"ignore": ["app/legacy/**"],
"rules": {
"no-raw-colors": "warn",
"no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
"no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
}
}
}
A rule is a bare severity ("off", "warn" or "error") or an object adding allow, which takes a category name or a class group. A rule left out is off. See the CLI for the command.
registries
To install from a registry other than the kit's own, pass its base URL with --registry:
See the Registry documentation for building and hosting one.