Skip to main content

​
Installation

Blocks is built on top of shadcn/ui and requires a React project with Tailwind CSS. Follow these steps to set up your project and start using Blocks.

​
Prerequisites

Before installing Blocks, ensure you have:
  • Node.js 18+ - Required for running the shadcn CLI and build tools
  • React 19+ - Blocks uses React 19 features
  • A React project - Next.js, Remix, Vite, or any React framework
  • Tailwind CSS - Configured in your project for styling
If you don’t have Tailwind CSS set up yet, follow the Tailwind CSS installation guide for your framework before proceeding.

​
Step-by-Step Installation

1

Install shadcn/ui

If you haven’t already set up shadcn/ui in your project, initialize it:
npx shadcn@latest init
This will:
  • Create a components.json configuration file
  • Set up your components/ui directory
  • Configure Tailwind CSS with the necessary presets
  • Install required dependencies like class-variance-authority, clsx, and tailwind-merge
Choose the style and color scheme that matches your design system. You can always customize these later.
2

Configure the Blocks Registry

Open your components.json file and add the Blocks registry:
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@blocks": "https://blocks.so/r/{name}.json"
  }
}
The registries configuration tells shadcn CLI where to fetch block definitions. The {name} placeholder will be replaced with the block ID when you add blocks.
3

Install Base Dependencies

Blocks uses several Radix UI primitives and other dependencies. Install the core packages:
npm install @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-separator @radix-ui/react-slot
Or with other package managers:
npm install @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-separator @radix-ui/react-slot
Don’t worry about installing all dependencies upfront. When you add a block, the shadcn CLI will prompt you to install any missing dependencies automatically.
4

Verify Installation

Test that everything is set up correctly by adding your first block:
npx shadcn@latest add @blocks/login-01
This command will:
  1. Fetch the block definition from https://blocks.so/r/login-01.json
  2. Download the component files to your project
  3. Install any missing dependencies
  4. Place the component in your components directory
If successful, you’ll see:
✔ Done. Component added to your project.
The block will be added to your components directory based on your components.json aliases configuration.

​
Configuration Options

​
Registry URL Format

The Blocks registry uses this URL format: 
https://blocks.so/r/{name}.json
Where {name} is the block ID (e.g., login-01, dialog-05, sidebar-02).

​
Alternative: Direct Registry URLs

You can also add blocks without configuring the registry by using direct URLs: 
npx shadcn@latest add https://blocks.so/r/login-01.json
This method works without modifying components.json, but the registry configuration provides a cleaner syntax.

​
Troubleshooting

Use npx to run shadcn without installing it globally:
npx shadcn@latest add @blocks/login-01
The @latest ensures you’re using the most recent version of the CLI.
If you see import errors after adding a block, the block may depend on shadcn/ui components you haven’t installed yet. Add them individually:
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add label
Or check the error message for the specific component name.
Ensure your tailwind.config.js includes the components directory in the content array:
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  // ...
}
Double-check that the registries configuration in components.json exactly matches:
"registries": {
  "@blocks": "https://blocks.so/r/{name}.json"
}
The {name} placeholder is required for the shadcn CLI to substitute block IDs.

​
Next Steps

Now that your project is configured, learn how to add and customize blocks:

Usage Guide

Learn how to add blocks to your project and customize them

Build docs developers (and LLMs) love

Get started for freeTalk to us