Getting Started

components.json

components.json is the project configuration file for the ParticleUI CLI. It lives at your project root and tells the CLI how to install components — which registries to use, where to place files, and how to resolve aliases.

Note

Run npx particleui-cli init to generate this file automatically. If you already have one from a previous setup, just add the registries key.

Overview

A freshly initialised project produces a file like this:

components.json

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

Registry configuration

Add a registries key at the top level. Each key is a namespace prefix you'll use in the CLI command. The url field uses {name} as a placeholder — the CLI fills it in automatically.

components.json

{
  "registries": {
    "@particleui": {
      "url": "https://particleui.dev/r/react/{name}.json",
      "headers": {
        "Authorization": "Bearer ${PARTICLEUI_TOKEN}"
      }
    }
  }
}

url

The registry endpoint. {name} is replaced by the component name.

headers.Authorization

Optional for free components. Required for Pro — set PARTICLEUI_TOKEN in your .env.

Full example

A complete components.json with ParticleUI configured:

components.json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@particleui": {
      "url": "https://particleui.dev/r/react/{name}.json",
      "headers": {
        "Authorization": "Bearer ${PARTICLEUI_TOKEN}"
      }
    }
  }
}

The Authorization header is silently ignored for free components, so you can keep the entry consistent across all projects.

Framework URLs

Change the url to target a different framework:

Reacthttps://particleui.dev/r/react/{name}.json

Vuehttps://particleui.dev/r/vue/{name}.json

Sveltehttps://particleui.dev/r/svelte/{name}.json

Installation

MCP Server