Monorepo integration

Set up Untitled UI React in a monorepo with Next.js or Vite. Learn how to share components across multiple apps and configure workspaces for optimal development.

Installation

The easiest way to get started with Untitled UI in a monorepo is to use our CLI to initialize in an existing project:

Navigate to your target directory

First, navigate to the directory where you want to set up Untitled UI. This could be your app directory or a shared components package:

cd apps/web
# or
cd packages/ui
# or wherever you want to initialize

Initialize with CLI

Use the CLI to initialize Untitled UI in your existing monorepo web or ui package:

npx untitledui@latest init

Ready to go!

Great! You're all set to start using Untitled UI components in your monorepo.

If something is missing, you can copy/paste what you need into your project directly from individual components pages.

Need help? Check our GitHub repository for examples, or open an issue if you run into any problems. Our community is here to help!

Custom alias paths

When working in a monorepo, you'll often need custom import paths. The CLI reads your components.json file to understand and use your custom alias paths:

Configure alias paths

Create or update a components.json file in your components directory. The CLI will read this file to understand your custom alias paths:

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

Working with example pages: Add "examples" key to specify where your web project is located in the monorepo. This allows the CLI to correctly resolve paths when adding example page files to your project.

Update your tsconfig.json

Ensure your TypeScript configuration includes the corresponding path mappings that match your aliases:

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

The CLI uses these mappings to resolve import paths and generate the correct file locations in your project.

Configure Tailwind CSS source

Update your styles/globals.css to include component paths using @source:

@import "tailwindcss";
...
/* Adjust paths based on your monorepo structure */
@source "../**/*.{ts,tsx}";

Add components with the CLI

Now you can add components using the CLI from your components directory:

npx untitledui@latest add button

The CLI will:

  • Read your components.json configuration
  • Use your custom alias paths in the generated components
  • Install components in the correct directory structure
  • Update imports to match your monorepo setup

Need help? Check our GitHub repository for examples, or open an issue if you run into any problems. Our community is here to help!

FAQs

Please refer to our frequently asked questions page for more.

Run npx untitledui@latest init from the package that should hold the components, such as your app (apps/web) or a shared UI package (packages/ui).

It reads the aliases in your components.json (components, utils, styles and hooks) and writes those paths into the imports of every component it adds. Add matching paths to your tsconfig.json, for example @workspace/ui/* mapped to ./packages/ui/src/*.

It points to your web app relative to the components package, for example "../../apps/web". It lets the CLI resolve paths correctly when npx untitledui@latest example adds example page files to that app.

When components live in a different package from your app, add an @source line to your globals.css that points at them, for example @source "../**/*.{ts,tsx}";. Adjust the path to match your monorepo structure.

In a shadcn/ui project, components.json belongs to shadcn/ui, so the CLI reads and writes its aliases and examples in untitledui.json instead. If an untitledui.json exists, it always takes priority over components.json.

LovableMCP