|
| 1 | +<a href="https://registry-starter.vercel.app/"> |
| 2 | + <h1 align="center">Registry Starter</h1> |
| 3 | +</a> |
| 4 | + |
| 5 | +<p align="center"> |
| 6 | + Registry Starter is a free, open-source template built with Next.js and Shadcn/ui Registry to accelerate your AI-Native Design System. |
| 7 | +</p> |
| 8 | + |
| 9 | +<p align="center"> |
| 10 | + <a href="#deploy-your-own"><strong>Deploy Your Own</strong></a> · |
| 11 | + <a href="#open-in-v0"><strong>Open in v0</strong></a> · |
| 12 | + <a href="#theming"><strong>Theming</strong></a> · |
| 13 | + <a href="#mcp"><strong>MCP</strong></a> · |
| 14 | + <a href="#authentication"><strong>Authentication</strong></a> · |
| 15 | + <a href="#running-locally"><strong>Running Locally</strong></a> · |
| 16 | + <a href="#file-structure"><strong>File Structure</strong></a> · |
| 17 | + <a href="https://ui.shadcn.com/docs/registry"><strong>Read Docs</strong></a> |
| 18 | +</p> |
| 19 | +<br/> |
| 20 | + |
| 21 | +## Deploy Your Own |
| 22 | + |
| 23 | +You can deploy your own version of the Next.js Registry Starter to Vercel with one click: |
| 24 | + |
| 25 | +[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fregistry-starter&project-name=my-registry&repository-name=my-registry&demo-title=Registry%20Starter&demo-description=Registry%20Starter%20is%20a%20free%2C%20open-source%20template%20built%20with%20Next.js%20and%20Shadcn%2Fui%20Registry%20to%20accelerate%20your%20AI-Native%20Design%20System.&demo-url=https%3A%2F%2Fregistry-starter.vercel.app&demo-image=%2F%2Fregistry-starter.vercel.app%2Fpreview.png) |
| 26 | + |
| 27 | +## Open in v0 |
| 28 | + |
| 29 | +[](https://v0.dev/chat/api/open?title=Dashboard+Kit&prompt=These+are+existing+design+system+styles+and+files.+Please+utilize+them+alongside+base+components+to+build.&url=https%3A%2F%2Fregistry-starter.vercel.app%2Fr%2Fdashboard.json) |
| 30 | + |
| 31 | +This registry application also exposes `Open in v0` buttons for each component. Once this application is deployed, the |
| 32 | +`Open in v0` button redirects to [`v0.dev`](https://v0.dev) with a prepopulated prompt and a URL pointing back to this |
| 33 | +registry's `/r/${component_name}.json` endpoint. This endpoint will provide v0 the necessary file information, content, |
| 34 | +and metadata to start your v0 chat with your component, theme, and other related code. |
| 35 | + |
| 36 | +These `/r/${component_name}.json` files are generated using `shadcn/ui` during the `build` and `dev` based on the |
| 37 | +repository's [`registry.json`](./registry.json). For more information, refer to the |
| 38 | +[documentation](https://ui.shadcn.com/docs/registry/registry-json). |
| 39 | + |
| 40 | +## Theming |
| 41 | + |
| 42 | +To use a custom theme for all the components, all you need to do is modify the CSS tokens in |
| 43 | +[`globals.css`](./src/app/globals.css). More information on these practices can be found |
| 44 | +on [ui.shadcn.com/docs](https://ui.shadcn.com/docs). |
| 45 | + |
| 46 | +#### Fonts |
| 47 | + |
| 48 | +To use custom fonts, you can either use [ |
| 49 | +`next/font/google`](https://nextjs.org/docs/pages/getting-started/fonts#google-fonts) or the |
| 50 | +[`@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) CSS rule in your |
| 51 | +[`globals.css`](./src/app/globals.css). |
| 52 | + |
| 53 | +```css |
| 54 | +@font-face { |
| 55 | + font-family: 'Montserrat'; |
| 56 | + font-style: normal; |
| 57 | + font-weight: 400; |
| 58 | + src: url('https://fonts.gstatic.com/s/montserrat/v15/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.woff2') format('woff2'), |
| 59 | + url('https://fonts.gstatic.com/s/montserrat/v15/JTUSjIg1_i6t8kCHKm45xW5rygbj49c.woff') format('woff'); |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +If you use `@font-face`, ensure you modify [`globals.css`](src/app/globals.css) tailwind configuration to map |
| 64 | +your custom font variables to Tailwind fonts. Refer to this |
| 65 | +[Tailwind documentation](https://tailwindcss.com/docs/font-family#customizing-your-theme) |
| 66 | + |
| 67 | +## MCP |
| 68 | + |
| 69 | +To use this registry with MCP, you must also edit [`registry.json`](./registry.json)'s first |
| 70 | +`registry-item` named `theme`. This `registry:theme` item not only contains the tailwind configuration, but it also |
| 71 | +contains your design tokens / CSS variables. |
| 72 | + |
| 73 | +The `shadcn/ui` CLI's MCP command will use the entire `registy.json` file, so it must be put in the `/public` folder |
| 74 | +with all of your `registry:item`s. This will enable you to use your registry in tools like Cursor & Windsurf. |
| 75 | + |
| 76 | +## Authentication |
| 77 | + |
| 78 | +To protect your registry, you must first protect your `registry.json` and all `registry:item` JSON files. |
| 79 | +This is made possible with an environment variable and basic Next.js Middleware. |
| 80 | + |
| 81 | +1. Create new `REGISTRY_AUTH_TOKEN`. For example, you can generate one: |
| 82 | + |
| 83 | + ```bash |
| 84 | + node -e "console.log(crypto.randomBytes(32).toString('base64url'))" |
| 85 | + ``` |
| 86 | + |
| 87 | +2. Add new `middleware.ts` file to protect `/r/:path` routes |
| 88 | + |
| 89 | + ```ts |
| 90 | + // src/middleware.ts |
| 91 | + import { NextResponse } from "next/server"; |
| 92 | + import type { NextRequest } from "next/server"; |
| 93 | + |
| 94 | + export const config = { matcher: "/r/:path*" }; |
| 95 | + |
| 96 | + export function middleware(request: NextRequest) { |
| 97 | + const token = request.nextUrl.searchParams.get("token"); |
| 98 | + |
| 99 | + if (token == null || token !== process.env.REGISTRY_AUTH_TOKEN) { |
| 100 | + return new NextResponse("Unauthorized", { status: 401 }); |
| 101 | + } |
| 102 | + |
| 103 | + return NextResponse.next(); |
| 104 | + } |
| 105 | + |
| 106 | + ``` |
| 107 | +
|
| 108 | +When using `Open in v0`, the v0 platform will use the `token` search parameter to authenticate with your Registry: |
| 109 | +
|
| 110 | +```ts |
| 111 | +const v0Url = `https://v0.dev/chat/api/open?url=https%3A%2F%2Fregistry-starter.vercel.app%2Fr%2Faccordion.json&token=${process.env.REGISTRY_AUTH_TOKEN}` |
| 112 | +``` |
| 113 | +
|
| 114 | +> [!NOTE] |
| 115 | +> This method only protects the `/r/:path` routes, this does NOT protect the Registry's UI / component previews. If you |
| 116 | +> choose to protect the UI / component preview, you must ensure the `registry.json` and all `registry:item`s are |
| 117 | +> publicly accessible or protected using the `token` search parameter. This ensures v0 and other AI Tools have access to |
| 118 | +> use the registry |
| 119 | + |
| 120 | +
|
| 121 | +## Running locally |
| 122 | +
|
| 123 | +```bash |
| 124 | +pnpm install |
| 125 | +pnpm dev |
| 126 | +``` |
| 127 | +
|
| 128 | +Your app should now be running on [localhost:3000](http://localhost:3000). |
| 129 | +
|
| 130 | +## File Structure |
| 131 | +
|
| 132 | +`app/(registry)` routes contains the registry pages. |
| 133 | +
|
| 134 | +`app/demo` routes contains various UI primitives, Components, or Blocks (based on `registry.json`) |
| 135 | +
|
| 136 | +`@/components` contains all components used in the registry |
| 137 | +
|
| 138 | +`@/components/ui` contains all `shadcn/ui` UI Primitives used in the registry |
| 139 | +
|
| 140 | +`@/components/registry` contains all components for this Registry Starter application |
| 141 | +
|
| 142 | +`@/hooks` contains all React hooks |
| 143 | +
|
| 144 | +`@/lib` contains all business logic & utils |
| 145 | +
|
| 146 | +`@/layouts` contains all v0 layouts used in `registry.json` |
0 commit comments