shadcn/ui Setup

How Plotcn uses shadcn/ui

Plotcn uses the shadcn Registry model as its installation and distribution layer. Instead of importing every visualization from a single opaque, monolithic npm package, you install individual chart source files directly into your own codebase.

The official shadcn CLI resolves the registry item, installs its specific dependencies, writes the TypeScript source files to your configured aliases, and rewrites imports to match your project structure.

Why registry distribution matters

• 100% Source Ownership: The code lives in your repository. You can customize SVG paths, alter animations, or tweak layout logic without waiting for upstream package releases.
• Dependency Isolation: Installing a Recharts line chart installs recharts only. It does not force you to install D3 or Google Charts dependencies.
• Unified Design Tokens: Charts inherit your project's existing shadcn CSS variables, typography, and border radii automatically.

components.json

The components.json file at the root of your project is the manifest read by the shadcn CLI. It instructs the CLI where to install files, how to rewrite import statements, what CSS entrypoint to update, and which remote registries to query.

Core configuration

The following properties in components.json define the CLI environment and file generation rules:

Style immutability

In shadcn/ui, the selected style cannot simply be changed after project initialization without breaking existing component primitives. Plotcn is designed to adapt to whatever style your project uses. We do not require a specific shadcn style, base color, or border radius.

Path aliases

The shadcn CLI uses aliases to determine where files are written and how imports are rewritten inside generated components.

Import stability rule

Registry items should resolve through stable path aliases, not fragile relative import chains:

// ✅ RECOMMENDED: Stable root-relative aliasimport { cn } from "@/lib/utils"import { ChartContainer } from "@/components/charts/shared/chart-container"// ❌ FRAGILE: Brittle relative pathimport { cn } from "../../../lib/utils"

Modern package imports

Current shadcn versions also support Node.js subpath imports configured in package.json#imports alongside TypeScript path mappings. Standard path aliases (@/*) remain the recommended default for most React projects.

React Server Components

The rsc field in components.json informs the CLI whether your application environment supports React Server Components.

Framework-specific RSC behavior

• Next.js App Router (rsc: true): Plotcn keeps data math, layout shells, and static utilities server-safe, while isolating interactive charts behind "use client" leaf boundaries.
• Vite & Client SPAs (rsc: false): The CLI omits redundant "use client" directives from generated component files.

TypeScript output

Plotcn is architected TypeScript-first with strict interfaces for chart props, datum schemas, and layout configurations:

{  "tsx": true}

Tailwind and CSS variables

Plotcn charts inherit colors directly from your existing design system using CSS variables:

{  "tailwind": {    "config": "",    "css": "app/globals.css",    "baseColor": "neutral",    "cssVariables": true  }}

Inherit, do not repaint

Plotcn adapts to your existing application palette (background, foreground, muted, border, card, primary). Visualization components reference categorical variables (--chart-1 through --chart-5) defined in your stylesheet, ensuring charts automatically transition between light and dark modes.

Configure the Plotcn registry

Because @plotcn is officially included in the shadcn/ui community registry directory, simply running an add command (like npx shadcn@latest add @plotcn/line-basic) works out of the box and registers the entry in your components.json automatically.

You can also explicitly define the registry in your components.json:

{  "registries": {    "@plotcn": "https://plotcn.vercel.app/r/{name}.json"  }}

Registering via CLI

You can also add the Plotcn registry namespace using the shadcn CLI:

pnpm dlx shadcn@latest registry add @plotcn=https://plotcn.vercel.app/r/{name}.json

GitHub source registries

Modern shadcn also supports installing components directly from public GitHub repositories that provide a root registry.json. During local development or experimental releases, you can install components directly from the Plotcn repository address.

Add a Plotcn component

You install visualization components using the @plotcn namespace just like standard shadcn primitives:

What happens during installation

When you execute an add command, the shadcn CLI performs a structured 7-step sequence:

1. Resolve Namespace: Checks components.json to map @plotcn to the remote registry URL.
2. Fetch Schema: Downloads the component JSON manifest containing source files and dependencies.
3. Resolve Registry Dependencies: Identifies shared Plotcn primitives (e.g. chart-container) needed by the component.
4. Install Package Dependencies: Installs only the engine needed (e.g. recharts for a Recharts line chart).
5. Copy Source Files: Injects the component files directly into your components/charts/ folder.
6. Rewrite Imports: Rewrites import statements inside the new files to match your project's configured aliases.
7. Verify CSS Tokens: Checks that required theme tokens are present in your stylesheet.

Package vs registry dependencies

• dependencies: Standard npm packages installed into node_modules (e.g. recharts, d3-shape).
• registryDependencies: Reusable component primitives copied as editable source code (e.g. chart-container, chart-state).

What gets added

Installing a component places readable, editable source code into your repository:

You own the installed source

After installation, Plotcn component source becomes an integral part of your application. You can freely inspect SVG rendering, adjust responsive breakpoints, change tooltip styling, or extend interaction handlers.

Common setup mistakes

Review these common configuration mismatches and their solutions:

Verify setup

Verify your shadcn/ui and registry configuration before installing your first visualization:

Next steps

Now that your configuration pipeline is ready, explore the component registry and theming:

• Plotcn Registry: Learn how source components are packaged and distributed.
• Usage Guide: General conventions, imports, and responsive container guidelines.
• Theming Guide: Customize categorical color tokens and light/dark mode palettes.