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.

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:

Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.

See the

CLI section

for more information.

$schema

You can see the JSON Schema for components.json here.

Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.

style

The style for your components. This cannot be changed after initialization.

{
  "style": "new-york"
}

The default style has been deprecated. Use the new-york style instead.

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.

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

tailwind.css

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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

Important: If you're using package imports, enable resolvePackageJsonImports and use moduleResolution: "bundler" in your tsconfig.json. If you're using paths, make sure your aliases include the src directory when applicable.

Using ,[object Object], or ,[object Object], paths

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

Using ,[object Object]

Recommended setup for a single-package app:

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

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

{
  "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.

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

aliases.components

Import alias for your components.

{
  "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.

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

aliases.lib

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

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

aliases.hooks

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

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

registries

Configure multiple resource registries for your project. This allows you to install components, libraries, utilities, and other resources from various sources including private registries.

See the

Namespaced Registries

documentation for detailed information.

Basic Configuration

Configure registries with URL templates:

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": "https://internal.company.com/{name}.json"
  }
}

The {name} placeholder is replaced with the resource name when installing.

Advanced Configuration with Authentication

For private registries that require authentication:

{
  "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 automatically expanded from your environment.

Using Namespaced Registries

Once configured, install resources using the namespace syntax:

Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.

Example: Multiple Registry Setup

Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.

This configuration allows you to:

• Install public components from JGuang UI
• Access private company UI components with authentication
• Use team-specific resources with versioning

For more information about authentication, see the

Authentication

documentation.