diff --git a/apps/www/components/docs-nav.tsx b/apps/www/components/docs-nav.tsx index 753ba897587..b98eb32f9ee 100644 --- a/apps/www/components/docs-nav.tsx +++ b/apps/www/components/docs-nav.tsx @@ -17,7 +17,12 @@ export function DocsNav({ config }: { config: DocsConfig }) { {items.map((item, index) => (

- {item.title} + {item.title}{" "} + {item.label && ( + + {item.label} + + )}

{item?.items?.length && ( diff --git a/apps/www/config/docs.ts b/apps/www/config/docs.ts index 907bedcc38d..ba6854f578a 100644 --- a/apps/www/config/docs.ts +++ b/apps/www/config/docs.ts @@ -405,6 +405,42 @@ export const docsConfig: DocsConfig = { }, ], }, + { + title: "Registry", + label: "New", + items: [ + { + title: "Introduction", + href: "/docs/registry", + items: [], + }, + { + title: "Getting Started", + href: "/docs/registry/getting-started", + items: [], + }, + { + title: "Open in v0", + href: "/docs/registry/open-in-v0", + items: [], + }, + { + title: "FAQ", + href: "/docs/registry/faq", + items: [], + }, + { + title: "registry.json", + href: "/docs/registry/registry-json", + items: [], + }, + { + title: "registry-item.json", + href: "/docs/registry/registry-item-json", + items: [], + }, + ], + }, ], chartsNav: [ { diff --git a/apps/www/content/docs/cli.mdx b/apps/www/content/docs/cli.mdx index 0de7dbcdb5a..04ae6a9687b 100644 --- a/apps/www/content/docs/cli.mdx +++ b/apps/www/content/docs/cli.mdx @@ -90,16 +90,33 @@ Options: -h, --help display help for command ``` -## Monorepo +## build -In a monorepo, you can specify the path to your workspace with the `-c` or `--cwd` option. +Use the `build` command to generate the registry JSON files. ```bash -npx shadcn@latest init -c ./apps/www +npx shadcn@latest build ``` -or +This command reads the `registry.json` file and generates the registry JSON files in the `public/r` directory. + +```txt +Usage: shadcn build [options] [registry] + +build components for a shadcn registry + +Arguments: + registry path to registry.json file (default: "./registry.json") + +Options: + -o, --output destination directory for json files (default: "./public/r") + -c, --cwd the working directory. defaults to the current directory. (default: + "/Users/shadcn/Code/shadcn/ui/packages/shadcn") + -h, --help display help for command +``` + +To customize the output directory, use the `--output` option. ```bash -npx shadcn@latest add alert-dialog -c ./apps/www +npx shadcn@latest build --output ./public/registry ``` diff --git a/apps/www/content/docs/registry/faq.mdx b/apps/www/content/docs/registry/faq.mdx new file mode 100644 index 00000000000..d1359ec09ce --- /dev/null +++ b/apps/www/content/docs/registry/faq.mdx @@ -0,0 +1,125 @@ +--- +title: FAQ +description: Frequently asked questions about running a registry. +--- + +## Frequently asked questions + +### What does a complex component look like? + +Here's an example of a complex component that installs a page, two components, a hook, a format-date utils and a config file. + +```json showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry-item.json", + "name": "hello-world", + "title": "Hello World", + "type": "registry:block", + "description": "A complex hello world component", + "files": [ + { + "path": "registry/hello-world/page.tsx", + "type": "registry:page", + "target": "app/hello/page.tsx" + }, + { + "path": "registry/hello-world/components/hello-world.tsx", + "type": "registry:component" + }, + { + "path": "registry/hello-world/components/formatted-message.tsx", + "type": "registry:component" + }, + { + "path": "registry/hello-world/hooks/use-hello.ts", + "type": "registry:hook" + }, + { + "path": "registry/hello-world/lib/format-date.ts", + "type": "registry:utils" + }, + { + "path": "registry/hello-world/hello.config.ts", + "type": "registry:file", + "target": "~/hello.config.ts" + } + ] +} +``` + +### How do I add a new Tailwind color? + +To add a new color you need to add it to `cssVars` and `tailwind.config.theme.extend.colors`. + +```json showLineNumbers {10-19} {24-29} +{ + "$schema": "https://ui.shadcn.com/schema/registry-item.json", + "name": "hello-world", + "title": "Hello World", + "type": "registry:block", + "description": "A complex hello world component", + "files": [ + // ... + ], + "cssVars": { + "light": { + "brand-background": "20 14.3% 4.1%", + "brand-accent": "20 14.3% 4.1%" + }, + "dark": { + "brand-background": "20 14.3% 4.1%", + "brand-accent": "20 14.3% 4.1%" + } + }, + "tailwind": { + "config": { + "theme": { + "extend": { + "colors": { + "brand": { + "DEFAULT": "hsl(var(--brand-background))", + "accent": "hsl(var(--brand-accent))" + } + } + } + } + } + } +} +``` + +The CLI will update the project CSS file and tailwind.config.js file. Once updated, the new colors will be available to be used as utility classes: `bg-brand` and `text-brand-accent`. + +### How do I add a Tailwind animation? + +To add a new animation you add it to `tailwind.config.theme.extend.animation` and `tailwind.config.theme.extend.keyframes`. + +```json showLineNumbers {14-22} +{ + "$schema": "https://ui.shadcn.com/schema/registry-item.json", + "name": "hello-world", + "title": "Hello World", + "type": "registry:block", + "description": "A complex hello world component", + "files": [ + // ... + ], + "tailwind": { + "config": { + "theme": { + "extend": { + "keyframes": { + "wiggle": { + "0%, 100%": { "transform": "rotate(-3deg)" }, + "50%": { "transform": "rotate(3deg)" } + } + }, + "animation": { + "wiggle": "wiggle 1s ease-in-out infinite" + } + } + } + } + } +} +``` diff --git a/apps/www/content/docs/registry/getting-started.mdx b/apps/www/content/docs/registry/getting-started.mdx new file mode 100644 index 00000000000..87ca7458d99 --- /dev/null +++ b/apps/www/content/docs/registry/getting-started.mdx @@ -0,0 +1,186 @@ +--- +title: Getting Started +description: Learn how to get setup and run your own component registry. +--- + +This guide will walk you through the process of setting up your own component registry. + +It assumes you already have a project with components and would like to turn it into a registry. + +If you're starting a new registry project, you can use the [registry template](https://github.com/shadcn-ui/registry-template) as a starting point. We have already configured it for you. + +## registry.json + +The `registry.json` file is only required if you're using the `shadcn` CLI to build your registry. + +If you're using a different build system, you can skip this step as long as your build system produces valid JSON files that conform to the [registry-item schema specification](/docs/registry/registry-item-json). + + + +### Add a registry.json file + +Create a `registry.json` file in the root of your project. Your project can be a Next.js, Remix, Vite, or any other project that supports React. + +```json title="registry.json" showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry.json", + "name": "acme", + "homepage": "https://acme.com", + "items": [ + // ... + ] +} +``` + +This `registry.json` file must conform to the [registry schema specification](/docs/registry/registry-json). + + + +## Add a registry item + + + +### Create your component + +Add your first component. Here's an example of a simple `` component: + +```tsx title="registry/hello-world/hello-world.tsx" showLineNumbers +import { Button } from "@/components/ui/button" + +export function HelloWorld() { + return +} +``` + + + **Note:** This example places the component in the `registry` directory. You + can place it anywhere in your project as long as you set the correct path in + the `registry.json` file. + + +```txt +registry +└── hello-world + └── hello-world.tsx +``` + + + **Important:** If you're placing your component in a custom directory, make + sure it is configured in your `tailwind.config.ts` file. + +```ts showLineNumbers +// tailwind.config.ts +export default { + content: ["./registry/**/*.{js,ts,jsx,tsx}"], +} +``` + + + +### Add your component to the registry + +To add your component to the registry, you need to add your component definition to `registry.json`. + +```json title="registry.json" showLineNumbers {6-17} +{ + "$schema": "https://ui.shadcn.com/schema/registry.json", + "name": "acme", + "homepage": "https://acme.com", + "items": [ + { + "name": "hello-world", + "type": "registry:block", + "title": "Hello World", + "description": "A simple hello world component.", + "files": [ + { + "path": "registry/hello-world/hello-world.tsx", + "type": "registry:component" + } + ] + } + ] +} +``` + +You define your registry item by adding a `name`, `type`, `title`, `description` and `files`. + +For every file you add, you must specify the `path` and `type` of the file. The `path` is the relative path to the file from the root of your project. The `type` is the type of the file. + +You can read more about the registry item schema and file types in the [registry item schema docs](/docs/registry/registry-item-json). + + + +## Build your registry + + + +### Install the shadcn CLI + +Note: the `build` command is currently only available in the `shadcn@canary` version of the CLI. + +```bash +npm install shadcn@canary +``` + +### Add a build script + +Add a `registry:build` script to your `package.json` file. + +```json title="package.json" showLineNumbers +{ + "scripts": { + "registry:build": "shadcn build" + } +} +``` + +### Run the build script + +Run the build script to generate the registry JSON files. + +```bash +npm run registry:build +``` + + + **Note:** By default, the build script will generate the registry JSON files + in `public/r` e.g `public/r/hello-world.json`. + +You can change the output directory by passing the `--output` option. See the [shadcn build command](/docs/cli#build) for more information. + + + + + +## Serve your registry + +If you're running your registry on Next.js, you can now serve your registry by running the `next` server. The command might differ for other frameworks. + +```bash +npm run dev +``` + +Your files will now be served at `http://localhost:3000/r/[NAME].json` eg. `http://localhost:3000/r/hello-world.json`. + +## Publish your registry + +To make your registry available to other developers, you can publish it by deploying your project to a public URL. + +## Guidelines + +Here are some guidelines to follow when building components for a registry. + +- The following properties are required for the block definition: `name`, `description`, `type` and `files`. +- Make sure to list all registry dependencies in `registryDependencies`. A registry dependency is the name of the component in the registry eg. `input`, `button`, `card`, etc or a URL to a registry item eg. `http://localhost:3000/r/editor.json`. +- Make sure to list all dependencies in `dependencies`. A dependency is the name of the package in the registry eg. `zod`, `sonner`, etc. To set a version, you can use the `name@version` format eg. `zod@^3.20.0`. +- **Imports should always use the `@/registry` path.** eg. `import { HelloWorld } from "@/registry/hello-world/hello-world"` +- Ideally, place your files within a registry item in `components`, `hooks`, `lib` directories. + +## Install using the CLI + +To install a registry item using the `shadcn` CLI, use the `add` command followed by the URL of the registry item. + +```bash +npx shadcn@latest add http://localhost:3000/r/hello-world.json +``` diff --git a/apps/www/content/docs/registry/index.mdx b/apps/www/content/docs/registry/index.mdx new file mode 100644 index 00000000000..7a681499c8b --- /dev/null +++ b/apps/www/content/docs/registry/index.mdx @@ -0,0 +1,40 @@ +--- +title: Registry +description: Run your own component registry. +--- + + + **Note:** This feature is currently experimental. Help us improve it by + testing it out and sending feedback. If you have any questions, please [reach + out to us](https://github.com/shadcn-ui/ui/discussions). + + +You can use the `shadcn` CLI to run your own component registry. Running your own registry allows you to distribute your custom components, hooks, pages, and other files to any React project. + +
+ Registry + Registry +
+ Distribute code to any React project. +
+
+ +Registry items are automatically compatible with the `shadcn` CLI and `Open in v0`. + +## Requirements + +You are free to design and host your custom registry as you see fit. The only requirement is that your registry items must be valid JSON files that conform to the [registry-item schema specification](/docs/registry/registry-item-json). + +If you'd like to see an example of a registry, we have a [template project](https://github.com/shadcn-ui/registry-template) for you to use as a starting point. diff --git a/apps/www/content/docs/registry/open-in-v0.mdx b/apps/www/content/docs/registry/open-in-v0.mdx new file mode 100644 index 00000000000..4b4fab78626 --- /dev/null +++ b/apps/www/content/docs/registry/open-in-v0.mdx @@ -0,0 +1,59 @@ +--- +title: Open in v0 +description: Integrate your registry with Open in v0. +--- + +If your registry is hosted and publicly accessible via a URL, you can open a registry item in v0 by using the `https://v0.dev/chat/api/open?url=[URL]` endpoint. + +eg. [https://v0.dev/chat/api/open?url=https://example.com/r/hello-world.json](https://v0.dev/chat/api/open?url=https://example.com/r/hello-world.json) + +## Button + +You can copy and paste the following code to add a `Open in v0` button to your site. + +```jsx +import { Button } from "@/components/ui/button" + +export function OpenInV0Button({ url }: { url: string }) { + return ( + + ) +} +``` + +## Usage + +```jsx + +``` + +## Known issues + +- The `Open in v0` button does not support `cssVars` and `tailwind` properties. diff --git a/apps/www/content/docs/registry/registry-item-json.mdx b/apps/www/content/docs/registry/registry-item-json.mdx new file mode 100644 index 00000000000..4dd3e9d4ccf --- /dev/null +++ b/apps/www/content/docs/registry/registry-item-json.mdx @@ -0,0 +1,272 @@ +--- +title: registry-item.json +description: Specification for registry items. +--- + +The `registry-item.json` schema is used to define your custom registry items. + +```json title="registry-item.json" showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry-item.json", + "name": "hello-world", + "type": "registry:block", + "title": "Hello World", + "description": "A simple hello world component.", + "files": [ + { + "path": "registry/hello-world/hello-world.tsx", + "type": "registry:component" + }, + { + "path": "registry/hello-world/use-hello-world.ts", + "type": "registry:hook" + } + ] +} +``` + +## Definitions + +You can see the JSON Schema for `registry-item.json` [here](https://ui.shadcn.com/schema/registry-item.json). + +### $schema + +The `$schema` property is used to specify the schema for the `registry-item.json` file. + +```json title="registry-item.json" showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry-item.json" +} +``` + +### name + +The `name` property is used to specify the name of your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "name": "hello-world" +} +``` + +### title + +A human-readable title for your registry item. Keep it short and descriptive. + +```json title="registry-item.json" showLineNumbers +{ + "title": "Hello World" +} +``` + +### description + +A description of your registry item. This can be longer and more detailed than the `title`. + +```json title="registry-item.json" showLineNumbers +{ + "description": "A simple hello world component." +} +``` + +### type + +The `type` property is used to specify the type of your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "type": "registry:block" +} +``` + +The following types are supported: + +| Type | Description | +| -------------------- | ------------------------------------------------ | +| `registry:block` | Use for complex components with multiple files. | +| `registry:component` | Use for simple components. | +| `registry:lib` | Use for lib and utils. | +| `registry:hook` | Use for hooks. | +| `registry:ui` | Use for UI components and single-file primitives | +| `registry:page` | Use for page or file-based routes. | +| `registry:file` | Use for miscellaneous files. | + +### author + +The `author` property is used to specify the author of the registry item. + +It can be unique to the registry item or the same as the author of the registry. + +```json title="registry-item.json" showLineNumbers +{ + "author": "John Doe " +} +``` + +### dependencies + +The `dependencies` property is used to specify the dependencies of your registry item. This is for `npm` packages. + +Use `@version` to specify the version of your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "dependencies": [ + "@radix-ui/react-accordion", + "zod", + "lucide-react", + "name@1.0.2" + ] +} +``` + +### registryDependencies + +Used for registry dependencies. Can be names or URLs. + +- For `shadcn/ui` registry items such as `button`, `input`, `select`, etc use the name eg. `['button', 'input', 'select']`. +- For custom registry items use the URL of the registry item eg. `['https://example.com/r/hello-world.json']`. + +```json title="registry-item.json" showLineNumbers +{ + "registryDependencies": [ + "button", + "input", + "select", + "https://example.com/r/editor.json" + ] +} +``` + +Note: The CLI will automatically resolve remote registry dependencies. + +### files + +The `files` property is used to specify the files of your registry item. Each file has a `path`, `type` and `target` (optional) property. + +**The `target` property is required for `registry:page` and `registry:file` types.** + +```json title="registry-item.json" showLineNumbers +{ + "files": [ + { + "path": "registry/hello-world/page.tsx", + "type": "registry:page", + "target": "app/hello/page.tsx" + }, + { + "path": "registry/hello-world/hello-world.tsx", + "type": "registry:component" + }, + { + "path": "registry/hello-world/use-hello-world.ts", + "type": "registry:hook" + }, + { + "path": "registry/hello-world/.env", + "type": "registry:file", + "target": "~/.env" + } + ] +} +``` + +#### path + +The `path` property is used to specify the path to the file in your registry. This path is used by the build script to parse, transform and build the registry JSON payload. + +#### type + +The `type` property is used to specify the type of the file. See the [type](#type) section for more information. + +#### target + +The `target` property is used to indicate where the file should be placed in a project. This is optional and only required for `registry:page` and `registry:file` types. + +By default, the `shadcn` cli will read a project's `components.json` file to determine the target path. For some files, such as routes or config you can specify the target path manually. + +Use `~` to refer to the root of the project e.g `~/foo.config.js`. + +### tailwind + +The `tailwind` property is used for tailwind configuration such as `theme`, `plugins` and `content`. + +You can use the `tailwind.config` property to add colors, animations and plugins to your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "tailwind": { + "config": { + "theme": { + "extend": { + "colors": { + "brand": "hsl(var(--brand))" + }, + "keyframes": { + "wiggle": { + "0%, 100%": { "transform": "rotate(-3deg)" }, + "50%": { "transform": "rotate(3deg)" } + } + }, + "animation": { + "wiggle": "wiggle 1s ease-in-out infinite" + } + } + } + } + } +} +``` + +### cssVars + +Use to define CSS variables for your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "cssVars": { + "light": { + "brand": "20 14.3% 4.1%", + "radius": "0.5rem" + }, + "dark": { + "brand": "20 14.3% 4.1%" + } + } +} +``` + + + **Note:** When adding colors, make sure to also add them to the + `tailwind.config.theme.extend.colors` property. + + +### docs + +Use `docs` to show custom documentation or message when installing your registry item via the CLI. + +```json title="registry-item.json" showLineNumbers +{ + "docs": "Remember to add the FOO_BAR environment variable to your .env file." +} +``` + +### categories + +Use `categories` to organize your registry item. + +```json title="registry-item.json" showLineNumbers +{ + "categories": ["sidebar", "dashboard"] +} +``` + +### meta + +Use `meta` to add additional metadata to your registry item. You can add any key/value pair that you want to be available to the registry item. + +```json title="registry-item.json" showLineNumbers +{ + "meta": { "foo": "bar" } +} +``` diff --git a/apps/www/content/docs/registry/registry-json.mdx b/apps/www/content/docs/registry/registry-json.mdx new file mode 100644 index 00000000000..57ccb943fea --- /dev/null +++ b/apps/www/content/docs/registry/registry-json.mdx @@ -0,0 +1,87 @@ +--- +title: registry.json +description: Schema for running your own component registry. +--- + +The `registry.json` schema is used to define your custom component registry. + +```json title="registry.json" showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry.json", + "name": "shadcn", + "homepage": "https://ui.shadcn.com", + "items": [ + { + "name": "hello-world", + "type": "registry:block", + "title": "Hello World", + "description": "A simple hello world component.", + "files": [ + { + "path": "registry/hello-world/hello-world.tsx", + "type": "registry:component" + } + ] + } + ] +} +``` + +## Definitions + +You can see the JSON Schema for `registry.json` [here](https://ui.shadcn.com/schema/registry.json). + +### $schema + +The `$schema` property is used to specify the schema for the `registry.json` file. + +```json title="registry.json" showLineNumbers +{ + "$schema": "https://ui.shadcn.com/schema/registry.json" +} +``` + +### name + +The `name` property is used to specify the name of your registry. This is used for data attributes and other metadata. + +```json title="registry.json" showLineNumbers +{ + "name": "acme" +} +``` + +### homepage + +The homepage of your registry. This is used for data attributes and other metadata. + +```json title="registry.json" showLineNumbers +{ + "homepage": "https://acme.com" +} +``` + +### items + +The `items` in your registry. Each item must implement the [registry-item schema specification](https://ui.shadcn.com/schema/registry-item.json). + +```json title="registry.json" showLineNumbers +{ + "items": [ + { + "name": "hello-world", + "type": "registry:block", + "title": "Hello World", + "description": "A simple hello world component.", + "files": [ + { + "path": "registry/hello-world/hello-world.tsx", + "type": "registry:component" + } + ] + } + ] +} +``` + +See the [registry-item schema documentation](/docs/registry/registry-item) for more information. diff --git a/apps/www/lib/rehype-npm-command.ts b/apps/www/lib/rehype-npm-command.ts index e0dd764da00..ee163bc5669 100644 --- a/apps/www/lib/rehype-npm-command.ts +++ b/apps/www/lib/rehype-npm-command.ts @@ -79,6 +79,21 @@ export function rehypeNpmCommand() { "bunx --bun" ) } + + // npm run. + if (node.properties?.["__rawString__"]?.startsWith("npm run")) { + const npmCommand = node.properties?.["__rawString__"] + node.properties["__npmCommand__"] = npmCommand + node.properties["__yarnCommand__"] = npmCommand.replace( + "npm run", + "yarn" + ) + node.properties["__pnpmCommand__"] = npmCommand.replace( + "npm run", + "pnpm" + ) + node.properties["__bunCommand__"] = npmCommand.replace("npm run", "bun") + } }) } } diff --git a/apps/www/package.json b/apps/www/package.json index e05530eef8f..aadd0c393b0 100644 --- a/apps/www/package.json +++ b/apps/www/package.json @@ -80,7 +80,7 @@ "react-resizable-panels": "^2.0.22", "react-wrap-balancer": "^0.4.1", "recharts": "2.12.7", - "shadcn": "2.1.8", + "shadcn": "2.2.0-canary.2", "sharp": "^0.31.3", "sonner": "^1.2.3", "swr": "2.2.6-beta.3", diff --git a/apps/www/public/images/registry-dark.png b/apps/www/public/images/registry-dark.png new file mode 100644 index 00000000000..6028eaee140 Binary files /dev/null and b/apps/www/public/images/registry-dark.png differ diff --git a/apps/www/public/images/registry-light.png b/apps/www/public/images/registry-light.png new file mode 100644 index 00000000000..6d41e915017 Binary files /dev/null and b/apps/www/public/images/registry-light.png differ diff --git a/packages/shadcn/package.json b/packages/shadcn/package.json index ed4c4fb2ded..b05acbffc69 100644 --- a/packages/shadcn/package.json +++ b/packages/shadcn/package.json @@ -1,6 +1,6 @@ { "name": "shadcn", - "version": "2.1.8", + "version": "2.2.0-canary.2", "description": "Add components to your apps.", "publishConfig": { "access": "public" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 402b98dd022..5a6e654edc6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -292,7 +292,7 @@ importers: specifier: 2.12.7 version: 2.12.7(react-dom@18.2.0(react@18.2.0))(react@18.2.0) shadcn: - specifier: 2.1.8 + specifier: 2.2.0-canary.2 version: link:../../packages/shadcn sharp: specifier: ^0.31.3