Shadcnblocks

https://www.shadcnblocks.com/docs
Admin
Shadcnblocks provides an expanded collection of ready-to-use block components built on shadcn/ui,...
Tokens:19,173
Snippets:304
Trust Score:9.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install project dependencies

Source: https://www.shadcnblocks.com/docs/sanity/getting-started

Navigate to the project directory and install dependencies for both frontend and studio.

```bash
cd sanityblockspnpm install
```

--------------------------------

### Install Pro Blocks via CLI

Source: https://www.shadcnblocks.com/docs/blocks/getting-started

Use the npx command to install specific Pro blocks after completing the authentication setup.

```bash
npx shadcn add @shadcnblocks/hero-125
```

--------------------------------

### Install Dependencies

Source: https://www.shadcnblocks.com/docs/payload/getting-started

Install all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Start Development Server

Source: https://www.shadcnblocks.com/docs/payload/getting-started

Launch the local development server.

```bash
pnpm dev
```

--------------------------------

### Install Components via CLI

Source: https://www.shadcnblocks.com/docs/blocks/styles

Use the shadcn CLI to install components based on the configured style.

```bash
npx shadcn@latest add button card dialog
```

```bash
npx shadcn@latest add button card dialog
```

--------------------------------

### Install Sanity CLI and login

Source: https://www.shadcnblocks.com/docs/sanity/getting-started

Install the Sanity CLI tool and authenticate the session.

```bash
pnpm install --global sanity@latest
```

```bash
sanity login
```

--------------------------------

### Install Project Dependencies

Source: https://www.shadcnblocks.com/docs/templates/getting-started

Install all required packages defined in the project's package.json file.

```bash
npm install
```

--------------------------------

### Install Blocks

Source: https://www.shadcnblocks.com/docs/blocks/styles

Install blocks that automatically respect the configured style setting.

```bash
npx shadcn@latest add @shadcnblocks/hero1
```

--------------------------------

### Copy Environment Variables

Source: https://www.shadcnblocks.com/docs/payload/getting-started

Initialize the .env file from the provided example.

```bash
cp .env.example .env
```

--------------------------------

### Install a block

Source: https://www.shadcnblocks.com/docs/blocks/base-ui

Add a specific block to your project using the shadcn CLI.

```bash
npx shadcn@latest add @shadcnblocks/hero1
```

```bash
npx shadcn@latest add @shadcnblocks/hero1
```

--------------------------------

### Install the shadcnblocks theme

Source: https://www.shadcnblocks.com/docs/blocks/getting-started

Apply the default theme to add necessary CSS variables and container styling.

```bash
npx shadcn@latest add @shadcnblocks/theme/shadcnblocks
```

--------------------------------

### Import Tailwind 4 Plugins

Source: https://www.shadcnblocks.com/docs/blocks/theming

Example of importing plugins within the CSS-first configuration.

```css
@plugin "@tailwindcss/typography";@import "tw-animate-css";
```

--------------------------------

### Start MongoDB Service on macOS

Source: https://www.shadcnblocks.com/docs/payload/database-setup

Command to start the MongoDB service using Homebrew services.

```bash
brew services start mongodb-community@8.0
```

--------------------------------

### Install MongoDB via Homebrew

Source: https://www.shadcnblocks.com/docs/payload/database-setup

Commands to prepare and install the MongoDB community edition on macOS.

```bash
brew tap mongodb/brew
```

```bash
brew update
```

```bash
brew install mongodb-community@8.0
```

--------------------------------

### Install pnpm globally

Source: https://www.shadcnblocks.com/docs/sanity/getting-started

Install the pnpm package manager globally if not already present.

```bash
npm install -g pnpm
```

--------------------------------

### Block Preview Directory Structure

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Example directory structure for storing block preview images in the Sanity Studio static folder.

```text
studio/static/images/preview/├── hero-12-custom.jpg├── feature-custom.jpg└── testimonial-1.jpg
```

--------------------------------

### Adding Shopping Cart Icon Example

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Complete example of adding a shopping cart icon to both the frontend component and the Sanity schema.

```typescript
import { ShoppingCart } from "lucide-react";const iconComponents: Record<string, LucideIcon> = {  // ... existing icons  "shopping-cart": ShoppingCart,};
```

```typescript
export const ICON_VARIANTS = [  // ... existing variants  { title: "ShoppingCart", value: "shopping-cart" },];
```

--------------------------------

### Configure components.json for Pro Blocks

Source: https://www.shadcnblocks.com/docs/extension/getting-started

Add the Shadcnblocks registry to your project's components.json file to enable Pro block installation via the CLI.

```json
{
  "registries": {
    "@shadcnblocks": {
      "url": "https://www.shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Convert asChild to render prop pattern

Source: https://www.shadcnblocks.com/docs/blocks/base-ui

Comparison of the Radix UI asChild pattern and the equivalent Base UI render prop pattern required for manual installations.

```javascript
// Radix UI pattern (what our blocks use)
<Button asChild>
  <a href="/about">About</a>
</Button>

// Base UI pattern (what the CLI transforms it to)
<Button render={<a href="/about" />}>
  About
</Button>
```

--------------------------------

### Import sample data

Source: https://www.shadcnblocks.com/docs/sanity/getting-started

Import the demo dataset into the production environment.

```bash
cd studiosanity dataset import sample-data.tar.gz production --replace
```

--------------------------------

### Initialize a new Next.js project

Source: https://www.shadcnblocks.com/docs/blocks/getting-started

Use the official shadcn create tool to scaffold a new project with pre-configured settings.

```bash
npx shadcn@latest init --preset b0 --template next
```

--------------------------------

### Reinstall components with Base UI

Source: https://www.shadcnblocks.com/docs/blocks/base-ui

Overwrite existing components with Base UI versions using the shadcn CLI.

```bash
npx shadcn@latest add --all --overwrite
```

```bash
npx shadcn@latest add --all --overwrite
```

--------------------------------

### Re-install Components with New Style

Source: https://www.shadcnblocks.com/docs/blocks/styles

Overwrite existing components to apply the updated style configuration.

```bash
npx shadcn@latest add --all --overwrite
```

```bash
npx shadcn@latest add button card input --overwrite
```

--------------------------------

### Configure Development Server URLs

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set the server and public URLs for local development environments.

```text
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000    # Local development URLNEXT_PUBLIC_SERVER_URL=http://localhost:3000       # Next.js public URL
```

--------------------------------

### Configure Production Server URLs

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set the server and public URLs for production deployment.

```text
PAYLOAD_PUBLIC_SERVER_URL=https://your-domain.com  # Production URLNEXT_PUBLIC_SERVER_URL=https://your-domain.com     # Production Next.js URL
```

--------------------------------

### Navigate to Template Directory

Source: https://www.shadcnblocks.com/docs/templates/getting-started

Change the current working directory to the unzipped template folder.

```bash
cd [template-name]
```

--------------------------------

### Configure Environment Variable

Source: https://www.shadcnblocks.com/docs/blocks/getting-started

Add your API key to your environment file to enable authentication for Pro blocks.

```bash
# .env
SHADCNBLOCKS_API_KEY=sk_live_your_api_key_here
```

--------------------------------

### Configure components.json for Base UI

Source: https://www.shadcnblocks.com/docs/blocks/base-ui

A complete configuration file for integrating Base UI with the Vega style.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@shadcnblocks": "https://www.shadcnblocks.com/r/{name}.json"
  }
}
```

--------------------------------

### Clone the Forked Repository

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Initial step to download your forked version of the repository to your local machine.

```bash
git clone https://github.com/YOUR_USERNAME/sanityblocks.gitcd sanityblocks
```

--------------------------------

### Initialize Shadcn MCP for Cursor

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Use the CLI to automatically initialize the MCP server for Cursor or add the configuration manually to the .cursor/mcp.json file.

```bash
pnpm dlx shadcn@latest mcp init --client cursor
```

```json
{  "mcpServers": {    "shadcn": {      "command": "npx",      "args": ["shadcn@latest", "mcp"]    }  }}
```

--------------------------------

### Initialize Shadcn MCP for Codex

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Use the CLI to automatically initialize the MCP server for Codex or add the configuration manually to the ~/.codex/config.toml file.

```bash
pnpm dlx shadcn@latest mcp init --client codex
```

```toml
[mcp_servers.shadcn]command = "npx"args = ["shadcn@latest", "mcp"]
```

--------------------------------

### Enable Corepack

Source: https://www.shadcnblocks.com/docs/payload/getting-started

Configure the package manager version by enabling corepack.

```bash
npm install corepackcorepack enablepnpm -v
```

--------------------------------

### Configure Storage Environment Variable

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set the Vercel Blob storage token for file storage.

```text
# For Vercel Blob Storage (Default)BLOB_READ_WRITE_TOKEN= # Vercel Blob storage token
```

--------------------------------

### Initialize Shadcn MCP for VS Code

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Use the CLI to automatically initialize the MCP server for VS Code or add the configuration manually to the .vscode/mcp.json file.

```bash
pnpm dlx shadcn@latest mcp init --client vscode
```

```json
{  "servers": {    "shadcn": {      "command": "npx",      "args": ["shadcn@latest", "mcp"]    }  }}
```

--------------------------------

### Configure Authentication Environment Variables

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set Google OAuth credentials and the JWT secret for authentication.

```text
# Google OAuth (optional)GOOGLE_CLIENT_ID=       # Google OAuth Client IDGOOGLE_CLIENT_SECRET=   # Google OAuth Client SecretGOOGLE_CALLBACK_URL=    # OAuth callback URL (e.g., http://localhost:3000/api/auth/google/callback)# JWTPAYLOAD_SECRET=         # Random string for JWT encryption
```

--------------------------------

### Configure Google Authentication Environment Variables

Source: https://www.shadcnblocks.com/docs/payload/authentication

Set these variables in your environment to enable Google OAuth integration.

```text
GOOGLE_CLIENT_ID=your_client_idGOOGLE_CLIENT_SECRET=your_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback
```

--------------------------------

### Visualize Block System Architecture

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

A directory structure overview showing the organization of frontend components and Sanity Studio schemas.

```text
frontend/components/blocks/├── index.tsx              # Main block renderer with componentMap├── section-header.tsx     # Reusable section header component├── hero/│   ├── hero12.tsx        # Hero block variant 12│   ├── hero13.tsx        # Hero block variant 13│   └── hero-custom.tsx   # Your custom hero variant├── feature/│   ├── feature1.tsx      # Feature block variant 1│   └── feature-custom.tsx # Your custom feature variant└── your-category/        # Your completely new block category    ├── your-block1.tsx    └── your-block2.tsxstudio/schemas/blocks/├── hero/│   ├── hero12.ts         # Schema for hero12 block│   ├── hero13.ts         # Schema for hero13 block│   └── hero-custom.ts    # Schema for your custom hero├── feature/│   ├── feature1.ts       # Schema for feature1 block│   └── feature-custom.ts # Schema for your custom feature└── your-category/        # Schemas for your new category    ├── your-block1.ts    └── your-block2.ts
```

--------------------------------

### Define Component Path

Source: https://www.shadcnblocks.com/docs/templates/adding-blocks

The standard directory structure for new block components.

```text
src/components/sections/your-block.tsx
```

--------------------------------

### View project directory structure

Source: https://www.shadcnblocks.com/docs/templates/project-structure

Visual representation of the file system hierarchy for a shadcnblocks template.

```text
├── src/│   ├── app/                       # Next.js 16 App Router and pages│   │   ├── ...                    # Pages based on the template│   │   ├── globals.css            # Tailwind 4 CSS and config│   │   ├── layout.tsx             # Root layout│   │   └── page.tsx               # Home page│   ├── components/                # React components│   │   ├── ui/                    # shadcn/ui components│   │   ├── sections/              # section blocks from Shadcnblocks.com│   │   └── layout/                # global blocks like header and footer│   └── lib/                       # Utility functions├── public/                        # Static assets├── .gitignore                     # Git ignore rules├── .prettierrc                    # Prettier configuration├── components.json                # shadcn/ui components config├── eslint.config.mjs              # ESLint configuration├── next.config.ts                 # Next.js configuration├── package.json                   # Dependencies and scripts├── postcss.config.mjs             # PostCSS configuration├── README.md                      # Project documentation└── tsconfig.json                  # TypeScript configuration
```

--------------------------------

### Configure components.json

Source: https://www.shadcnblocks.com/docs/blocks/styles

Set the style property to define the visual treatment for your components.

```json
{  "$schema": "https://ui.shadcn.com/schema.json",  "style": "radix-maia",  "rsc": true,  "tsx": true,  "tailwind": {    "config": "",    "css": "app/globals.css",    "baseColor": "neutral",    "cssVariables": true  },  "aliases": {    "components": "@/components",    "utils": "@/lib/utils",    "ui": "@/components/ui"  }}
```

--------------------------------

### Initialize Shadcn MCP for Claude Code

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Use the CLI to automatically initialize the MCP server for Claude Code or add the configuration manually to the .mcp.json file.

```bash
pnpm dlx shadcn@latest mcp init --client claude
```

```json
{  "mcpServers": {    "shadcn": {      "command": "npx",      "args": ["shadcn@latest", "mcp"]    }  }}
```

--------------------------------

### Run linting manually

Source: https://www.shadcnblocks.com/docs/templates/linting

Executes the linting process via npm.

```bash
npm run lint
```

--------------------------------

### Configure MongoDB URI

Source: https://www.shadcnblocks.com/docs/payload/getting-started

Set the MongoDB connection string in the .env file.

```text
MONGODB_URI=your_connection_string
```

--------------------------------

### Configure Database Environment Variable

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set the MongoDB connection string required for database connectivity.

```text
MONGODB_URI=            # Your MongoDB connection string
```

--------------------------------

### Run MongoDB in Docker

Source: https://www.shadcnblocks.com/docs/payload/database-setup

Command to launch a MongoDB container with persistent storage and port mapping.

```bash
docker run --name payblocks-mongodb -p 27017:27017 -v mongo-volume:/data/db -d mongo:8
```

--------------------------------

### Configure S3 Storage Adapter

Source: https://www.shadcnblocks.com/docs/payload/deployment

Replace the default Vercel Blob storage adapter with an S3-compatible adapter for alternative hosting platforms.

```typescript
import { s3Adapter } from '@payloadcms/plugin-cloud-storage/s3'const storageAdapter = s3Adapter({  config: {    credentials: {      accessKeyId: process.env.S3_ACCESS_KEY_ID,      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,    },    region: process.env.S3_REGION,    bucket: process.env.S3_BUCKET,  },})
```

--------------------------------

### Troubleshoot Authentication with Hardcoded Key

Source: https://www.shadcnblocks.com/docs/shadcn-cli/overview

Temporarily replace the environment variable with a raw key to verify if the issue is related to environment variable loading.

```json
{
  "registries": {
    "@shadcnblocks": {
      "url": "https://www.shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer sk_live_your_actual_key_here"
      }
    }
  }
}
```

--------------------------------

### Configure components.json for Private Registry

Source: https://www.shadcnblocks.com/docs/shadcn-cli/overview

Add the registry configuration to your components.json file to enable authentication via environment variables.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "radix-vega",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
    "@shadcnblocks": {
      "url": "https://www.shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Visualize Architecture Data Flow

Source: https://www.shadcnblocks.com/docs/figma/theme-system

The hierarchy of the theme system from primitives to components.

```text
Tailwind Primitives / Hex
        ↓Theme Collection (Brand Values)
        ↓Theme Mode Collection (Light/Dark Mapping)
        ↓Components + 500 Pro Blocks
```

--------------------------------

### Configure Email Environment Variables

Source: https://www.shadcnblocks.com/docs/payload/environment-variables

Set the Resend API key and default sender email address.

```text
RESEND_API_KEY=re_xxxx...   # Resend API keyEMAIL_FROM_ADDRESS=info@example.com   # Email address from which emails are sent by default
```

--------------------------------

### Clone the repository

Source: https://www.shadcnblocks.com/docs/sanity/getting-started

Clone the Sanityblocks repository from GitHub.

```bash
git clone https://github.com/serge-0v/sanityblocks.git
```

--------------------------------

### Configure components.json for Base UI

Source: https://www.shadcnblocks.com/docs/blocks/base-ui

Set the style property to a base-prefixed value to enable Base UI primitives.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega"
}
```

--------------------------------

### Create Testimonial Frontend Component

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Implement the React component in the frontend directory, using the generated Sanity types to ensure data consistency.

```typescript
import { PAGE_QUERYResult } from "@/sanity.types";type Testimonial1Props = Extract<  NonNullable<NonNullable<PAGE_QUERYResult>["blocks"]>[number],  { _type: "testimonial-1" }>;const Testimonial1 = ({ quote, author }: Testimonial1Props) => {  return (    <section className="py-16">      <div className="container">        <blockquote className="text-xl italic">"{quote}"</blockquote>        <cite className="mt-4 block">          — {author.name}          {author.title && `, ${author.title}`}        </cite>      </div>    </section>  );};export default Testimonial1;
```

--------------------------------

### Configure SendGrid via Nodemailer

Source: https://www.shadcnblocks.com/docs/payload/email

Integrate SendGrid by passing a Nodemailer transport configuration to the adapter.

```javascript
import nodemailer from 'nodemailer'import { nodemailerAdapter } from '@payloadcms/email-nodemailer'export default buildConfig({  email: nodemailerAdapter({    transport: nodemailer.createTransport({      service: 'SendGrid',      auth: {        user: 'apikey',        pass: 'YOUR_SENDGRID_API_KEY'      }    })  }),})
```

--------------------------------

### Import and Use Block

Source: https://www.shadcnblocks.com/docs/templates/adding-blocks

How to import and render the custom block within a Next.js page file.

```tsx
// app/page.tsximport { YourBlock } from "@/components/sections/your-block"export default function Page() {  return (    <main>      <YourBlock />    </main>  )}
```

--------------------------------

### Configure Authenticated Shadcnblocks Registry

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Include an authorization header with your API key in components.json to access pro blocks.

```json
{  "registries": {    "@shadcnblocks": {      "url": "https://www.shadcnblocks.com/r/{name}",      "headers": {        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"      }    }  }}
```

--------------------------------

### Configure Prettier settings

Source: https://www.shadcnblocks.com/docs/templates/linting

Defines formatting rules and plugins in the .prettierrc file.

```json
{  "trailingComma": "all",  "tabWidth": 2,  "semi": true,  "useTabs": false,  "singleQuote": true,  "printWidth": 80,  "jsxSingleQuote": false,  "plugins": ["prettier-plugin-tailwindcss"],}
```

--------------------------------

### Configure Default Metadata in Next.js

Source: https://www.shadcnblocks.com/docs/templates/seo

Define global SEO settings in the root layout file using the Next.js Metadata object.

```typescript
// app/layout.tsximport { Metadata } from 'next'export const metadata: Metadata = {  title: {    default: 'Charter - Modern Next.js Template',    template: '%s | Charter',  },  description:    'A modern, fully featured Next.js template built with Shadcn/UI, TailwindCSS and TypeScript, perfect for your next web application.',  keywords: [    'Next.js',    'React',    'JavaScript',    'TypeScript',    'TailwindCSS',    'Template',    'Shadcn/UI',    'Web Development',  ],  authors: [{ name: 'Charter - Shadcnblckos.com' }],  creator: 'Charter - Shadcnblckos.com',  publisher: 'Charter',  robots: {    index: true,    follow: true,  },  icons: {    icon: [      { url: '/favicon/favicon.ico', sizes: '48x48' },      { url: '/favicon/favicon.svg', type: 'image/svg+xml' },      { url: '/favicon/favicon-96x96.png', sizes: '96x96', type: 'image/png' },      { url: '/favicon/favicon.svg', type: 'image/svg+xml' },      { url: '/favicon/favicon.ico' },    ],    apple: [{ url: '/favicon/apple-touch-icon.png', sizes: '180x180' }],    shortcut: [{ url: '/favicon/favicon.ico' }],  },  openGraph: {    title: 'Charter - Modern Next.js Template',    description:      'A modern, fully featured Next.js template built with Shadcn/UI, TailwindCSS and TypeScript, perfect for your next web application.',    siteName: 'Charter',    images: [      {        url: '/og-image.jpg',        width: 1200,        height: 630,        alt: 'Charter - Modern Next.js Template',      },    ],  },  twitter: {    card: 'summary_large_image',    title: 'Charter - Modern Next.js Template',    description:      'A modern, fully featured Next.js template built with Shadcn/UI, TailwindCSS and TypeScript, perfect for your next web application.',    images: ['/og-image.jpg'],    creator: '@charter',  },};
```

--------------------------------

### Configure Upstream Remote

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Commands to link the original repository as an upstream remote and verify the configuration.

```bash
git remote add upstream https://github.com/serge-0v/sanityblocks.git
```

```bash
git remote -v
```

```bash
origin    https://github.com/YOUR_USERNAME/sanityblocks.git (fetch)origin    https://github.com/YOUR_USERNAME/sanityblocks.git (push)upstream  https://github.com/serge-0v/sanityblocks.git (fetch)upstream  https://github.com/serge-0v/sanityblocks.git (push)
```

--------------------------------

### Configure Resend API Key

Source: https://www.shadcnblocks.com/docs/payload/email

Add your Resend API key and sender address to the environment variables.

```text
RESEND_API_KEY=re_xxxx...EMAIL_FROM_ADDRESS=info@example.com
```

--------------------------------

### Configure Shadcnblocks Registry

Source: https://www.shadcnblocks.com/docs/shadcn-mcp/overview

Add the Shadcnblocks registry URL to your components.json file to enable automatic discovery.

```json
{  "registries": {    "@shadcnblocks": "https://www.shadcnblocks.com/r/{name}"  }}
```

--------------------------------

### Using Update Branches

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Workflow for testing updates in a dedicated branch before merging into the main branch.

```bash
git checkout -b test-updatesgit merge upstream/master# Test everything worksgit checkout mastergit merge test-updates
```

--------------------------------

### Configure Fonts in Layout

Source: https://www.shadcnblocks.com/docs/payload/editing-pages

Update the font configuration in the root layout file by importing new fonts from next/font/google and defining the CSS variables.

```typescript
import { Roboto, Fira_Mono } from 'next/font/google'...const mono = Fira_Mono({ subsets: ['latin'], variable: '--font-mono', weight: ['400', '500', '700'] })const sans = Roboto({ subsets: ['latin'], variable: '--font-sans', weight: ['400', '500', '700'] })
```

--------------------------------

### Block Components Directory Structure

Source: https://www.shadcnblocks.com/docs/payload/custom-blocks

Visual representation of the file structure for block components within the src/blocks directory.

```text
src/blocks/├── CustomBlock/           # Prepared CustomBlock category│   ├── config.ts            # Config for all CustomBlocks│   ├── index.tsx            # Main rendering component for the custom block category│   ├── customService1.tsx│   └── customService2.tsx│    ├── Cta/                  # Example existing block│   ├── Component.tsx     # Main component│   ├── config.ts        # Block configuration│   ├── cta1.tsx         # Variant 1│   ├── cta2.tsx         # Variant 2│   └── cta-custom.tsx   # Your custom variant└── RenderBlocks.tsx     # Main rendering component. All block category rendering components are imported here
```

--------------------------------

### Register Custom Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Add the newly created custom schema to the main studio schema configuration.

```typescript
// Import your custom schemaimport hero12Custom from "./schemas/blocks/hero/hero12-custom";export const schema: { types: SchemaTypeDefinition[] } = {  types: [    // ... existing schemas    hero12Custom,    // ... rest of schemas  ],};
```

--------------------------------

### Configure VS Code editor settings

Source: https://www.shadcnblocks.com/docs/templates/linting

Enables format on save and ESLint auto-fix in .vscode/settings.json.

```json
{  "editor.formatOnSave": true,  "editor.codeActionsOnSave": {    "source.fixAll.eslint": "explicit"  },  "editor.defaultFormatter": "esbenp.prettier-vscode"}
```

--------------------------------

### Implement Custom Hero Component

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Create the React component for the custom block, ensuring proper type extraction from the Sanity query result.

```typescript
import { PAGE_QUERYResult } from "@/sanity.types";// ... other importstype Hero12CustomProps = Extract<  NonNullable<NonNullable<PAGE_QUERYResult>["blocks"]>[number],  { _type: "hero-12-custom" }>;const Hero12Custom = ({  title,  customField,}: // ... other propsHero12CustomProps) => {  return (    <section className="py-32">      {/* Your custom implementation */}      <h1>{title}</h1>      <p>{customField}</p>    </section>  );};export default Hero12Custom;
```

--------------------------------

### Represent Layout Ordering

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Visual representation of how sub-blocks can be reordered within the array.

```text
[feature-content] [feature-image]
```

```text
[feature-image] [feature-content]
```

--------------------------------

### Define Custom Hero Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Create a new schema file by duplicating an existing one and adding custom fields.

```typescript
import { defineField, defineType } from "sanity";import { LayoutTemplate } from "lucide-react";export default defineType({  name: "hero-12-custom",  title: "Hero 12 Custom",  type: "object",  icon: LayoutTemplate,  fields: [    // Copy existing fields from hero12.ts    defineField({      name: "title",      type: "string",      validation: (Rule) => Rule.required(),    }),    // Add your custom fields    defineField({      name: "customField",      type: "string",      title: "Your Custom Field",    }),    // ... other fields  ],  preview: {    select: {      title: "title",    },    prepare({ title }) {      return {        title: "Hero 12 Custom",        subtitle: title,      };    },  },});
```

--------------------------------

### Define Block-Specific Query

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Create a dedicated file for each block to define the data structure fetched from Sanity.

```typescript
// frontend/sanity/queries/hero/hero12-custom.tsimport { groq } from "next-sanity";import { linkQuery } from "../shared/link";import { imageQuery } from "../shared/image";import { bodyQuery } from "../shared/body";export const hero12CustomQuery = groq`  _type == "hero-12-custom" => {    _type,    _key,    title,    customField,    backgroundImage{      ${imageQuery}    },    links[]{      ${linkQuery}    },    body[]{      ${bodyQuery}    }  }`;
```

--------------------------------

### Organize Blocks in Insert Menu

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Group blocks into categories within the insertMenu options for improved UX in the Studio.

```typescript
options: {  insertMenu: {    groups: [      {        name: "hero",        of: [          "hero-12",          "hero-12-custom", // Add to appropriate group          "hero-13",          // ... other hero blocks        ],      },      {        name: "feature",        of: ["feature-1", "feature-3", /* ... */],      },      // ... other groups    ],  },}
```

--------------------------------

### Document Custom Changes

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Maintain a CUSTOM_CHANGES.md file to track added blocks, modified files, and new dependencies.

```markdown
# Custom Changes## Custom Blocks Added- `hero-12-custom`: Custom hero with additional CTA field- `testimonial-carousel`: New testimonial block with carousel## Modified Files- `frontend/components/blocks/index.tsx`: Added custom block imports- `studio/schema.ts`: Added custom schemas## New Dependencies- `swiper`: Added for carousel functionality
```

--------------------------------

### Define a standard block schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Use this pattern for blocks that rely on a separate section-header component for titles and descriptions.

```typescript
// Most blocks focus on content and layout, not headersexport default defineType({  name: "feature-1-custom",  title: "Feature 1 Custom",  fields: [    // No title/description fields - use section-header instead    defineField({      name: "features",      type: "array",      of: [        /* feature items */      ],    }),    // ... other content fields  ],});
```

--------------------------------

### Handle generated file conflicts

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Correct procedures for managing conflicts in auto-generated files like schema.json and sanity.types.ts.

```bash
# Don't manually edit these files during merge conflictsgit add studio/schema.jsongit add frontend/sanity.types.ts
```

```bash
# Remove the conflicted generated filesgit rm studio/schema.jsongit rm frontend/sanity.types.ts# Complete the mergegit commit# Regenerate the filespnpm typegen
```

--------------------------------

### Define Sanity Testimonial Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Create a new schema file in the studio directory to define the structure and validation rules for a testimonial block.

```typescript
import { defineField, defineType } from "sanity";import { MessageCircle } from "lucide-react";export default defineType({  name: "testimonial-1",  title: "Testimonial 1",  type: "object",  icon: MessageCircle,  fields: [    defineField({      name: "quote",      type: "text",      title: "Quote",      validation: (Rule) => Rule.required(),    }),    defineField({      name: "author",      type: "object",      fields: [        defineField({          name: "name",          type: "string",          validation: (Rule) => Rule.required(),        }),        defineField({          name: "title",          type: "string",        }),        defineField({          name: "avatar",          type: "image",          options: { hotspot: true },        }),      ],    }),  ],  preview: {    select: {      title: "author.name",      subtitle: "quote",    },  },});
```

--------------------------------

### Configure Custom Fonts

Source: https://www.shadcnblocks.com/docs/blocks/theming

Define custom font families by updating the --font-sans and --font-display CSS variables.

```css
:root {  --font-sans: "Your Font", ui-sans-serif, system-ui, sans-serif;  --font-display: "Your Display Font", sans-serif;}
```

--------------------------------

### Define a hero block schema with custom headers

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Use this pattern for blocks that require unique header styling or integrated layout components.

```typescript
// Hero blocks include their own headers for unique stylingexport default defineType({  name: "hero-12-custom",  title: "Hero 12 Custom",  fields: [    defineField({      name: "title",      type: "string", // Custom title for unique hero styling    }),    defineField({      name: "description",      type: "block-content", // Custom description    }),    defineField({      name: "links",      type: "array",      of: [{ type: "link-icon" }], // Custom CTAs    }),    // ... other hero-specific fields  ],});
```

--------------------------------

### Implement Frontend Component Mapping

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Uses a component map to dynamically render sub-blocks based on their Sanity _type.

```tsx
// frontend/components/blocks/feature/feature1/index.tsxconst componentMap = {  "feature-content": FeatureContent,  "feature-image": FeatureImage,};export default function Feature1({ columns }) {  return (    <div className="grid lg:grid-cols-2">      {columns?.map((column) => {        const Component = componentMap[column._type];        return <Component {...column} key={column._key} />;      })}    </div>  );}
```

--------------------------------

### Shared Image Query Fragment

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Use this fragment to fetch optimized image data, including LQIP and dimensions.

```typescript
// frontend/sanity/queries/shared/image.tsexport const imageQuery = `  ...,  asset->{    _id,    url,    mimeType,    metadata {      lqip,      dimensions {        width,        height      }    }  }`;
```

--------------------------------

### Configure Nodemailer SMTP Adapter

Source: https://www.shadcnblocks.com/docs/payload/email

Use the Nodemailer adapter for traditional SMTP email transport.

```javascript
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'export default buildConfig({  email: nodemailerAdapter({    transportOptions: {      host: 'smtp.example.com',      auth: {        user: 'username',        pass: 'password'      },      port: 587,      secure: false, // true for 465, false for other ports    },  }),})
```

--------------------------------

### Generate Sanity TypeScript types

Source: https://www.shadcnblocks.com/docs/sanity/sanity-typegen

Execute this command to generate the schema.json and sanity.types.ts files.

```bash
pnpm typegen
```

--------------------------------

### Update components.json Registry

Source: https://www.shadcnblocks.com/docs/blocks/getting-started

Configure the @shadcnblocks registry in your components.json file to include the required Authorization header.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "radix-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
     "@shadcnblocks": {
       "url": "https://www.shadcnblocks.com/r/{name}",
       "headers": {
         "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
     }
   }
}
```

--------------------------------

### Registering Icons in Frontend

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Update the icon mapping in the frontend component to include new Lucide React icons.

```typescript
// Add your new icon to the importsimport {  // ... existing imports  Calendar, // Add your new icon here  // ... other imports} from "lucide-react";// Add to the iconComponents mappingconst iconComponents: Record<string, LucideIcon> = {  // ... existing icons  calendar: Calendar, // Add your new icon here  // ... other icons};
```

--------------------------------

### Using link-icon Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Include the link-icon type in block schemas to enable icon selection functionality.

```typescript
// In any block schema using links with iconsdefineField({  name: "links",  type: "array",  of: [{ type: "link-icon" }], // This includes icon selection}),
```

--------------------------------

### Fetch upstream changes

Source: https://www.shadcnblocks.com/docs/sanity/updates-and-upgrades

Retrieve the latest changes from the upstream repository before performing an update.

```bash
git fetch upstream
```

--------------------------------

### Adapting a Shadcnblocks Component Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Use the -custom suffix when defining your Sanity schema to prevent naming conflicts with future official releases.

```javascript
// Instead of: testimonial-1// Use: testimonial-1-customexport default defineType({  name: "testimonial-1-custom",  title: "Testimonial 1 Custom",  // ... rest of schema});
```

--------------------------------

### Shared Link Query Fragment

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Use this fragment to resolve internal and external links automatically.

```typescript
// frontend/sanity/queries/shared/link.tsexport const linkQuery = `    _key,    ...,    "href": select(      isExternal => href,      @.internalLink->slug.current == "index" => "/",      @.internalLink->_type == "post" => "/blog/" + @.internalLink->slug.current,      "/" + @.internalLink->slug.current    )`;
```

--------------------------------

### Registering Icons in Sanity Schema

Source: https://www.shadcnblocks.com/docs/sanity/custom-blocks

Add new icon variants to the shared schema file to make them available in the Sanity Studio dropdown.

```typescript
export const ICON_VARIANTS = [  // ... existing variants  { title: "Calendar", value: "calendar" }, // Add your new icon here  // ... other variants];
```
Tokens:
Raw