From 5ec990a4749aa32cb1c412290898e8c82d03f338 Mon Sep 17 00:00:00 2001 From: shadcn Date: Tue, 14 Jan 2025 21:56:45 +0400 Subject: [PATCH] docs(www): add blocks contribution docs (#6354) * docs(www): add blocks contrib docs * docs(www): update intro * feat: update banner * docs: add link * docs: update block types --- apps/www/app/(app)/blocks/layout.tsx | 8 +- apps/www/components/announcement.tsx | 4 +- apps/www/config/docs.ts | 6 + apps/www/content/docs/blocks.mdx | 223 +++++++++++++++++++++++++++ 4 files changed, 233 insertions(+), 8 deletions(-) create mode 100644 apps/www/content/docs/blocks.mdx diff --git a/apps/www/app/(app)/blocks/layout.tsx b/apps/www/app/(app)/blocks/layout.tsx index e600d75475b..1819a60e6a1 100644 --- a/apps/www/app/(app)/blocks/layout.tsx +++ b/apps/www/app/(app)/blocks/layout.tsx @@ -11,6 +11,7 @@ import { import { Button } from "@/registry/new-york/ui/button" import "@/styles/mdx.css" +import Link from "next/link" export const metadata: Metadata = { title: "Building Blocks.", @@ -37,12 +38,7 @@ export default function BlocksLayout({ Browse Blocks diff --git a/apps/www/components/announcement.tsx b/apps/www/components/announcement.tsx index e4406fffe5b..5e69fa13a25 100644 --- a/apps/www/components/announcement.tsx +++ b/apps/www/components/announcement.tsx @@ -4,11 +4,11 @@ import { ArrowRight } from "lucide-react" export function Announcement() { return ( - Monorepo support + Blocks are open for contributions diff --git a/apps/www/config/docs.ts b/apps/www/config/docs.ts index 92d4ac8075d..907bedcc38d 100644 --- a/apps/www/config/docs.ts +++ b/apps/www/config/docs.ts @@ -92,6 +92,12 @@ export const docsConfig: DocsConfig = { href: "/docs/v0", items: [], }, + { + title: "Blocks", + href: "/docs/blocks", + items: [], + label: "New", + }, { title: "Figma", href: "/docs/figma", diff --git a/apps/www/content/docs/blocks.mdx b/apps/www/content/docs/blocks.mdx new file mode 100644 index 00000000000..a3ee31a6ce8 --- /dev/null +++ b/apps/www/content/docs/blocks.mdx @@ -0,0 +1,223 @@ +--- +title: Add a block +description: Contribute components to the blocks library. +--- + +We are inviting the community to contribute to the [blocks library](/blocks). Share your components and blocks with other developers and help build a library of high-quality, reusable components. + +We'd love to see all types of blocks: applications, marketing, products, and more. + +## Setup your workspace + + + +### Fork the repository + +```bash +git clone https://github.com/shadcn-ui/ui.git +``` + +### Create a new branch + +```bash +git checkout -b username/my-new-block +``` + +### Install dependencies + +```bash +pnpm install +``` + +### Start the dev server + +```bash +pnpm www:dev +``` + + + +## Add a block + +A block can be a single component (eg. a variation of a ui component) or a complex component (eg. a dashboard) with multiple components, hooks, and utils. + + + +### Create a new block + +Create a new folder in the `apps/www/registry/new-york/blocks` directory. Make sure the folder is named in kebab-case and under `new-york`. + +```txt +apps +└── www + └── registry + └── new-york + └── blocks + └── dashboard-01 +``` + + + +**Note:** The build script will take care of building the block for the `default` style. + + + +### Add your block files + +Add your files to the block folder. Here is an example of a block with a page, components, hooks, and utils. + +```txt +dashboard-01 +└── page.tsx +└── components + └── hello-world.tsx + └── example-card.tsx +└── hooks + └── use-hello-world.ts +└── lib + └── format-date.ts +``` + + + +**Note:** You can start with one file and add more files later. + + + + + +## Add your block to the registry + + + +### Add your block definition to `registry-blocks.tsx` + +To add your block to the registry, you need to add your block definition to `registry-blocks.tsx`. + +This follows the registry schema at [https://ui.shadcn.com/schema/registry-item.json](https://ui.shadcn.com/schema/registry-item.json). + +```tsx title="apps/www/registry/registry-blocks.tsx" +export const blocks = [ + // ... + { + name: "dashboard-01", + author: "shadcn (https://ui.shadcn.com)", + title: "Dashboard", + description: "A simple dashboard with a hello world component.", + type: "registry:block", + registryDependencies: ["input", "button", "card"], + dependencies: ["zod"], + files: [ + { + path: "blocks/dashboard-01/page.tsx", + type: "registry:page", + target: "app/dashboard/page.tsx", + }, + { + path: "blocks/dashboard-01/components/hello-world.tsx", + type: "registry:component", + }, + { + path: "blocks/dashboard-01/components/example-card.tsx", + type: "registry:component", + }, + { + path: "blocks/dashboard-01/hooks/use-hello-world.ts", + type: "registry:hook", + }, + { + path: "blocks/dashboard-01/lib/format-date.ts", + type: "registry:lib", + }, + ], + categories: ["dashboard"], + }, +] +``` + +Make sure you add a name, description, type, registryDependencies, dependencies, files, and categories. We'll go over each of these in more detail in the schema docs (coming soon). + +### Run the build script + +```bash +pnpm registry:build +``` + + + +**Note:** you do not need to run this script for every change. You only need to run it when you update the block definition. + + + +### View your block + +Once the build script is finished, you can view your block at `http://localhost:3333/blocks/[CATEGORY]` or a full screen preview at `http://localhost:3333/view/styles/new-york/dashboard-01`. + +### Build your block + +You can now build your block by editing the files in the block folder and viewing the changes in the browser. + +If you add more files, make sure to add them to the `files` array in the block definition. + + + +## Publish your block + +Once you're ready to publish your block, you can submit a pull request to the main repository. + + + +### Run the build script + +```bash +pnpm registry:build +``` + +### Capture a screenshot + +```bash +pnpm registry:capture +``` + + + +**Note:** If you've run the capture script before, you might need to delete the existing screenshots (both light and dark) at `apps/www/public/r/styles/new-york` and run the script again. + + + +### Submit a pull request + +Commit your changes and submit a pull request to the main repository. + +Your block will be reviewed and merged. Once merged it will be published to the website and available to be installed via the CLI. + + + +## Categories + +The `categories` property is used to organize your block in the registry. + +### Add a category + +If you need to add a new category, you can do so by adding it to the `registryCategories` array in `apps/www/registry/registry-categories.ts`. + +```tsx title="apps/www/registry/registry-categories.ts" +export const registryCategories = [ + // ... + { + name: "Input", + slug: "input", + hidden: false, + }, +] +``` + +## Guidelines + +Here are some guidelines to follow when contributing to the blocks library. + +- The following properties are required for the block definition: `name`, `description`, `type`, `files`, and `categories`. +- 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. +- Make sure to list all dependencies in `dependencies`. A dependency is the name of the package in the registry eg. `zod`, `sonner`, etc. +- If your block has a page (optional), it should be the first entry in the `files` array and it should have a `target` property. This helps the CLI place the page in the correct location for file-based routing. +- **Imports should always use the `@/registry` path.** eg. `import { Input } from "@/registry/new-york/input"`