components.json

Overview

The components.json file allows you to configure how the CLI handles import paths and file locations when adding components to your project. This is particularly useful for:

• Monorepos with custom workspace aliases
• Projects with non-standard directory structures
• Teams that want consistent component installation paths

Note: The components.json file is optional. If you don't have one, the CLI will auto-detect your project structure from tsconfig.json and prompt you for paths as needed.

Creating components.json

Create a components.json file in the root of your project (or the folder where you run the CLI):

{
    "aliases": {
        "components": "@/components/",
        "utils": "@/utils/",
        "hooks": "@/hooks/",
        "styles": "@/styles/"
    },
    "examples": "app"
}

Configuration options

aliases

The aliases object defines the import path prefixes used in your component files. These must match your tsconfig.json path mappings.

{
    "aliases": {
        "components": "@/components/",
        "utils": "@/utils/",
        "hooks": "@/hooks/",
        "styles": "@/styles/"
    }
}

Important: Aliases must be valid tsconfig path aliases, not relative paths. The CLI uses your tsconfig.json to resolve these aliases to actual filesystem locations.

examples

The examples property specifies where example page files should be installed. This is useful when working in a monorepo where your web app is in a different directory.

{
    "examples": "../../apps/web"
}

How aliases work

When you add a component, the CLI performs two key operations using your aliases:

1. Import statement transformation

The CLI rewrites import statements in component code to match your aliases:

// Original component code
import { Button } from "@/components/base/buttons/button";
import { cx } from "@/utils/cx";
 
// After transformation (if your alias is @workspace/ui/)
import { Button } from "@workspace/ui/components/base/buttons/button";
import { cx } from "@workspace/ui/utils/cx";

2. File path resolution

The CLI uses your tsconfig.json paths to determine where to place files on disk:

// tsconfig.json
{
    "compilerOptions": {
        "paths": {
            "@workspace/ui/*": ["./packages/ui/src/*"]
        }
    }
}

With the above config, a component with path components/base/button.tsx would be installed to ./packages/ui/src/components/base/button.tsx.

Alias requirements

Critical: Aliases in components.json must be valid tsconfig path aliases. Relative paths like ../../components will not work correctly.

Why relative paths don't work

The CLI uses the tsconfig-paths library to resolve aliases to filesystem locations. This library only understands aliases defined in your tsconfig.json paths configuration.

Correct setup

To use custom aliases, you must configure both your tsconfig.json and components.json:

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

{
    "aliases": {
        "components": "@workspace/ui/components/",
        "utils": "@workspace/ui/utils/",
        "hooks": "@workspace/ui/hooks/",
        "styles": "@workspace/ui/styles/"
    }
}

npx untitledui@latest add button

Example configurations

Standard Next.js project

{
    "aliases": {
        "components": "@/components/",
        "utils": "@/utils/",
        "hooks": "@/hooks/",
        "styles": "@/styles/"
    },
    "framework": "next-app"
}

With corresponding tsconfig.json:

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

Monorepo with shared UI package

{
    "aliases": {
        "components": "@workspace/ui/components/",
        "utils": "@workspace/ui/utils/",
        "hooks": "@workspace/ui/hooks/",
        "styles": "@workspace/ui/styles/"
    },
    "examples": "../../apps/web"
}

With corresponding tsconfig.json:

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

Vite project with custom alias

{
    "aliases": {
        "components": "~/components/",
        "utils": "~/lib/",
        "hooks": "~/hooks/",
        "styles": "~/styles/"
    },
    "framework": "vite"
}

With corresponding tsconfig.json:

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