export const title = "Monorepo integration";
export const description = "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.";

<Divider />

## Installation

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

<Steps>
    <Step title="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:

        ```bash
        cd apps/web
        # or
        cd packages/ui
        # or wherever you want to initialize
        ```
    </Step>

    <Step title="Initialize with CLI">
        Use the CLI to initialize Untitled UI in your existing monorepo `web` or `ui` package:

        <CodeTabs>
            <CodeTabList items={[
                { id: "npm", label: "npm" },
                { id: "yarn", label: "yarn" },
                { id: "bun", label: "bun" },
            ]}/>

            <CodeTabPanel id="npm">
                ```bash
                npx untitledui@latest init
                ```
            </CodeTabPanel>
            <CodeTabPanel id="yarn">
                ```bash
                yarn dlx untitledui@latest init
                ```
            </CodeTabPanel>
            <CodeTabPanel id="bun">
                ```bash
                bunx untitledui@latest init
                ```
            </CodeTabPanel>
        </CodeTabs>
    </Step>

    <Step title="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](/components) pages.

        **Need help?** Check our [GitHub repository](https://github.com/untitleduico/react/) for examples, or [open an issue](https://github.com/untitleduico/react/issues/) if you run into any problems. Our community is here to help!
    </Step>

</Steps>

<Divider />

## 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:

<Steps>
    <Step title="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:

        ```json
        {
          "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.
    </Step>

    <Step title="Update your tsconfig.json">
        Ensure your TypeScript configuration includes the corresponding path mappings that match your aliases:

        ```json
        {
            "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.
    </Step>

    <Step title="Configure Tailwind CSS source">
        Update your `styles/globals.css` to include component paths using `@source`:

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

    <Step title="Add components with the CLI">
        Now you can add components using the CLI from your components directory:

        ```bash
        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
    </Step>

</Steps>

<Divider />

**Need help?** Check our [GitHub repository](https://github.com/untitleduico/react/) for examples, or [open an issue](https://github.com/untitleduico/react/issues/) if you run into any problems. Our community is here to help!