docs(www): add monorepo docs

apps/www/config/docs.ts

@@ -71,6 +71,12 @@ export const docsConfig: DocsConfig = {
           href: "/docs/cli",
           items: [],
         },
+        {
+          title: "Monorepo",
+          href: "/docs/monorepo",
+          items: [],
+          label: "New",
+        },
         {
           title: "Next.js 15 + React 19",
           href: "/docs/react-19",
@@ -141,12 +147,6 @@ export const docsConfig: DocsConfig = {
     {
       title: "Components",
       items: [
-        {
-          title: "Sidebar",
-          href: "/docs/components/sidebar",
-          items: [],
-          label: "New",
-        },
         {
           title: "Accordion",
           href: "/docs/components/accordion",
@@ -337,6 +337,11 @@ export const docsConfig: DocsConfig = {
           href: "/docs/components/sheet",
           items: [],
         },
+        {
+          title: "Sidebar",
+          href: "/docs/components/sidebar",
+          items: [],
+        },
         {
           title: "Skeleton",
           href: "/docs/components/skeleton",

apps/www/content/docs/monorepo.mdx

@@ -0,0 +1,163 @@
+---
+title: Monorepo
+description: Using shadcn/ui components and CLI in a monorepo.
+---
+
+<Callout>
+  **Note:** We're releasing monorepo support in the CLI as __experimental__.
+  Help us improve it by testing it out and sending feedback.
+</Callout>
+
+Until now, using shadcn/ui in a monorepo was a bit of a pain. You could add
+components using the CLI, but you had to manually manage where the components
+were installed and import paths.
+
+With the new monorepo support in the CLI, we've made it a lot easier to use
+shadcn/ui in a monorepo.
+
+The CLI now understands the monorepo structure and will install the components,
+dependencies and registry dependencies to the correct paths and handle imports
+for you.
+
+## Getting started
+
+<Steps>
+
+### Create a new monorepo project
+
+To create a new monorepo project, run the `init` command. You will be prompted
+to select the type of project you are creating.
+
+```bash
+npx shadcn@latest init
+```
+
+Select the `Next.js (Monorepo)` option.
+
+```bash
+? Would you like to start a new project?
+    Next.js
+❯   Next.js (Monorepo)
+```
+
+This will create a new monorepo project with two workspaces: `web` and `ui`,
+and [Turborepo](https://turbo.build/repo/docs) as the build system.
+
+Everything is set up for you, so you can start adding components to your project.
+
+### Add components to your project
+
+To add components to your project, run the `add` command **in the path of your app**.
+
+```bash
+cd apps/web
+```
+
+```bash
+npx shadcn@latest add [COMPONENT]
+```
+
+The CLI will figure out what type of component you are adding and install the
+correct files to the correct path. eg. if you run `npx shadcn@latest add button`, the CLI will install the button component under `packages/ui` and update the import path for components in `apps/web`.
+
+### Importing components
+
+You can now import components from the `@workspace/ui` package.
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+```
+
+You can also import hooks and utilities from the `@workspace/ui` package.
+
+```tsx
+import { useTheme } from "@workspace/ui/hooks/use-theme"
+import { cn } from "@workspace/ui/lib/utils"
+```
+
+</Steps>
+
+## File Structure
+
+When you create a new monorepo project, the CLI will create the following file structure:
+
+```txt
+apps
+└── web         # Your app goes here.
+    ├── app
+    │   └── page.tsx
+    ├── components
+    │   └── login-form.tsx
+    ├── components.json
+    └── package.json
+packages
+└── ui          # Your components and dependencies are installed here.
+    ├── src
+    │   ├── components
+    │   │   └── button.tsx
+    │   ├── hooks
+    │   ├── lib
+    │   │   └── utils.ts
+    │   └── styles
+    │       └── globals.css
+    ├── components.json
+    └── package.json
+package.json
+turbo.json
+```
+
+## Requirements
+
+1. Every workspace must have a `components.json` file. A `package.json` file tells npm how to install the dependencies. A `components.json` file tells the CLI how and where to install components.
+
+2. The `components.json` file must properly define aliases for the workspace. This tells the CLI how to import components, hooks, utilities, etc.
+
+```json title="apps/web/components.json"
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "../../packages/ui/tailwind.config.ts",
+    "css": "../../packages/ui/src/styles/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "hooks": "@/hooks",
+    "lib": "@/lib",
+    "utils": "@workspace/ui/lib/utils",
+    "ui": "@workspace/ui/components"
+  }
+}
+```
+
+```json title="packages/ui/components.json"
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/styles/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@workspace/ui/components",
+    "utils": "@workspace/ui/lib/utils",
+    "hooks": "@workspace/ui/hooks",
+    "lib": "@workspace/ui/lib",
+    "ui": "@workspace/ui/components"
+  }
+}
+```
+
+3. Ensure you have the same `style`, `iconLibrary` and `baseColor` in both `components.json` files.
+
+By following these requirements, the CLI will be able to install ui components, blocks, libs and hooks to the correct paths and handle imports for you.