components.json

The components.json file holds configuration for your project.

We use it to understand how your project is set up and how to generate components customized for your project.

You can create a components.json file in your project by running the following command:

pnpmnpmyarnbun
bunx --bun fabricator-ui@latest init
Copy

See the CLI section for more information.

$schema#

The JSON Schema for components.json is hosted at https://fabricator-ui.vercel.app/schema.json.

Copy{
  "$schema": "https://fabricator-ui.vercel.app/schema.json"
}

style#

The base and style for your components, written as <base>-<style>. This cannot be changed after initialization.

Copy{
  "style": "base-nova"
}

The base is one of base, radix or aria. The style is one of vega, nova, maia, lyra, mira, luma, sera or rhea.

The style field always holds one of these style ids, even in a project that uses the Fabricator design. The Fabricator look comes from the @fabricator registry URL, not from this field, so third-party registry items keep resolving correctly. See Registry.

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#

Path to where your tailwind.config.js file is located. For Tailwind CSS v4, leave this blank.

Copy{
  "tailwind": {
    "config": "tailwind.config.js" | "tailwind.config.ts"
  }
}

tailwind.css#

Path to the CSS file that imports Tailwind CSS into your project.

Copy{
  "tailwind": {
    "css": "styles/global.css"
  }
}

tailwind.baseColor#

This is used to generate the default theme tokens for your components. This cannot be changed after initialization.

Copy{
  "tailwind": {
    "baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe"
  }
}

tailwind.cssVariables#

We use and recommend CSS variables for theming.

Set tailwind.cssVariables to true to generate semantic theme tokens like background, foreground, and primary. Set it to false to generate inline Tailwind color utilities instead.

Copy{
  "tailwind": {
    "cssVariables": `true` | `false`
  }
}

For more information, see the theming docs.

This cannot be changed after initialization. To switch between CSS variables and utility classes, you'll have to delete and re-install your components.

tailwind.prefix#

The prefix to use for your Tailwind CSS utility classes. Components will be added with this prefix.

Copy{
  "tailwind": {
    "prefix": "tw-"
  }
}

rsc#

Whether or not to enable support for React Server Components.

The CLI automatically adds a use client directive to client components when set to true.

Copy{
  "rsc": `true` | `false`
}

tsx#

Choose between TypeScript or JavaScript components.

Setting this option to false allows components to be added as JavaScript with the .jsx file extension.

Copy{
  "tsx": `true` | `false`
}

aliases#

The CLI uses these values to place generated components in the correct location and rewrite imports.

You can back these aliases with either:

1. compilerOptions.paths in your tsconfig.json or jsconfig.json
2. package.json#imports with TypeScript package import resolution enabled

The aliases in components.json are still required when using the CLI. They tell the CLI which import roots map to components, ui, lib, hooks, and utils.

Using tsconfig or jsconfig paths#

Copy{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Using package.json#imports#

Recommended setup for a single-package app:

Copy{
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  }
}

Copy{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonImports": true
  }
}

Copy{
  "aliases": {
    "components": "#components",
    "ui": "#components/ui",
    "lib": "#lib",
    "hooks": "#hooks",
    "utils": "#lib/utils"
  }
}

The aliases in components.json still tell the CLI where to place components, ui, lib, hooks, and utils. package.json#imports provides the runtime and TypeScript resolution for those #... specifiers.

The matched imports target also controls whether generated #... imports keep file extensions:

• "#components/*": "./src/components/*" preserves source extensions and can generate imports like #components/button.tsx
• "#components/*": "./src/components/*.tsx" strips source extensions and generates imports like #components/button

For monorepos, see the monorepo docs. Local workspace aliases can use package.json#imports, while shared workspace imports such as @workspace/ui/components are resolved from the target package's exports.

For framework-specific setup, see the package imports guide.

aliases.utils#

Import alias for your utility functions.

Copy{
  "aliases": {
    "utils": "@/lib/utils"
  }
}

aliases.components#

Import alias for your components.

Copy{
  "aliases": {
    "components": "@/components"
  }
}

aliases.ui#

Import alias for ui components.

The CLI will use 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.

Copy{
  "aliases": {
    "ui": "@/app/ui"
  }
}

aliases.lib#

Import alias for lib functions such as format-date or generate-id.

Copy{
  "aliases": {
    "lib": "@/lib"
  }
}

aliases.hooks#

Import alias for hooks such as use-media-query or use-toast.

Copy{
  "aliases": {
    "hooks": "@/hooks"
  }
}

registries#

Configure the registries the CLI can install from. Each key is a namespace, and each value is a URL template. Items are then installed with @namespace/name.

The @fabricator registry#

npx fabricator-ui@latest init adds the @fabricator registry for you. To add it by hand, add this entry. Components are compiled in the Fabricator design for your base:

Copy{
  "registries": {
    "@fabricator": "https://fabricator-ui.vercel.app/r/fabricator/{style}/{name}.json"
  }
}

The CLI replaces {style} with the style field of your components.json and {name} with the item name. Then install components:

pnpmnpmyarnbun
bunx --bun fabricator-ui@latest add button
Copy

See Registry for how the URL resolves.

Other registries#

You can configure any number of registries next to @fabricator:

Copy{
  "registries": {
    "@fabricator": "https://fabricator-ui.vercel.app/r/fabricator/{style}/{name}.json",
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": "https://internal.company.com/{name}.json"
  }
}

Private registries#

For private registries that require authentication, use an object with url, headers and params:

Copy{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}",
        "X-API-Key": "${API_KEY}"
      },
      "params": {
        "version": "latest"
      }
    }
  }
}

Environment variables in the format ${VAR_NAME} are expanded from your environment.

Using namespaced registries#

Once configured, install resources using the namespace syntax:

pnpmnpmyarnbun
bunx --bun fabricator-ui@latest add button @acme/header @internal/auth-utils
Copy

With the Fabricator CLI, bare names such as button resolve to @fabricator.