Project Setup

Before you begin

Project setup is the technical blueprint that connects your initial installation to building charts. It ensures your codebase has the directory structure, path aliases, theme variables, and architecture boundaries needed before adding visualization components.

Plotcn does not require you to reorganize your entire project. It is designed to integrate seamlessly into standard React and Next.js applications, matching your existing conventions for components, utilities, and styling tokens.

Project structure

Plotcn organizes chart code around engine isolation. Primitives for Recharts, D3, and Google Charts reside in dedicated directories, while cross-engine infrastructure stays strictly engine-independent.

Highlighted directories

• components/charts/: The destination directory for all Plotcn visualization components. Components installed from the registry are copied directly here as editable source code.
• components/ui/: Base shadcn/ui primitives (Button, Tooltip, Card, Dialog) utilized by chart headers, interactive legends, and filter controls.
• lib/charts/: Engine-neutral math utilities, coordinate transforms, and theme option adapters (such as Google Charts palette generators).
• globals.css: Defines CSS variables (--chart-1 through --chart-5, gridlines, axes) that power both light and dark visualization modes.
• components.json: The shadcn configuration file instructing the CLI where to place imported components and how to resolve aliases.

Path aliases

Registry-installed source files require predictable import paths to find helper functions, theme tokens, and UI primitives without fragile relative imports like ../../../lib/utils.

Stabilizing your path aliases early is essential: changing aliases after installing components requires manually updating import statements across your chart files.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Import conventions

When components are imported into your pages or dashboards, use the root alias:

// Recommended: Clean root-relative importsimport { LineChartBasic } from "@/components/charts/recharts/line-chart-basic"import { ChartContainer } from "@/components/charts/shared/chart-container"

components.json

The components.json file is the registry manifest used by the shadcn CLI to determine styles, Tailwind CSS paths, import aliases, and target directories for new components.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "hugeicons",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Key configuration fields

• rsc: Set to true in Next.js App Router and full-stack SSR environments. Set to false in client-only Vite or SPA setups.
• tailwind.css: Points to your primary CSS entrypoint containing the @theme inline definitions and CSS variables (app/globals.css or src/index.css).
• aliases.components: Maps @/components so registry components install into your component hierarchy without manual path entry.
• aliases.utils: Resolves @/lib/utils where the cn() class merge utility is located.

Chart directories

Plotcn enforces strict separation between visualization engines. Each engine has unique rendering models, runtime lifecycles, and dependency requirements.

Engine isolation principles

Cross-engine dependencies are strictly prohibited:

// ❌ WRONG: Cross-engine coupling// In components/charts/google/geo-chart.tsx:import { Tooltip } from "@/components/charts/recharts/tooltip"// ✅ CORRECT: Engine-independent shared layer// In components/charts/google/geo-chart.tsx:import { ChartContainer } from "@/components/charts/shared/chart-container"import { getGoogleChartTheme } from "@/lib/google-charts/theme"

Shared chart infrastructure

Plotcn shares common product concerns across all chart engines without forcing them into a rigid, monolithic wrapper.

Shared vs engine-specific concerns

Theme tokens

Plotcn charts adapt directly to your design system using CSS variables rather than hardcoded hex colors. This ensures charts automatically match your light and dark themes.

Tailwind CSS v4 variables

Add chart tokens to your @theme inline block in app/globals.css:

@import "tailwindcss";@import "tw-animate-css";@theme inline {  --color-background: var(--background);  --color-foreground: var(--foreground);  --color-border: var(--border);  --color-muted: var(--muted);  --color-muted-foreground: var(--muted-foreground);  /* Plotcn categorical chart color tokens */  --color-chart-1: var(--chart-1);  --color-chart-2: var(--chart-2);  --color-chart-3: var(--chart-3);  --color-chart-4: var(--chart-4);  --color-chart-5: var(--chart-5);}

Semantic palette values

Plotcn uses a restrained Zinc / Titanium palette for crisp contrast in both light and dark modes:

:root {  --background: oklch(1 0 0);  --foreground: oklch(0.145 0 0);  --border: oklch(0.922 0 0);  --muted: oklch(0.97 0 0);  --muted-foreground: oklch(0.556 0 0);  /* Light mode chart palette (Zinc / Titanium scale) */  --chart-1: oklch(0.87 0 0);  --chart-2: oklch(0.556 0 0);  --chart-3: oklch(0.439 0 0);  --chart-4: oklch(0.371 0 0);  --chart-5: oklch(0.269 0 0);}.dark {  --background: oklch(0.145 0 0);  --foreground: oklch(0.985 0 0);  --border: oklch(1 0 0 / 10%);  --muted: oklch(0.269 0 0);  --muted-foreground: oklch(0.708 0 0);  /* Dark mode chart palette */  --chart-1: oklch(0.87 0 0);  --chart-2: oklch(0.556 0 0);  --chart-3: oklch(0.439 0 0);  --chart-4: oklch(0.371 0 0);  --chart-5: oklch(0.269 0 0);}

Google Charts theme adapter

Unlike React SVG charts that read CSS variables directly, Google Charts renders inside an isolated iframe/canvas managed by an external script. Plotcn provides theme adapter functions in lib/google-charts/theme.ts that resolve your CSS variables into Google options at runtime.

Server and client boundaries

In Next.js App Router and modern SSR frameworks, maintaining strict server and client boundaries is essential for performance and bundle size.

Best practices for Next.js

1. Keep pages server-first: Never place "use client" at app/layout.tsx, docs layouts, or entire page routes. Fetch data and construct layout on the server.
2. Isolate interactive charts: Add "use client" only at the leaf component boundary where DOM measurements (ResizeObserver), SVG animations, or user hover events take place.
3. D3 math utilities: D3 calculation functions (scales, shapes, pie layouts) are pure functions and can run on both server and client without "use client".
4. Google Charts runtime: Google Charts requires the browser window object. Keep the loader and chart wrapper behind a strict client component boundary to prevent SSR hydration errors.

Registry output

When you install a component using the shadcn CLI, Plotcn copies the component source code directly into your repository.

Source ownership

• No opaque packages: Installed components are regular TypeScript and React files in your project. You have complete freedom to tweak SVG markup, add custom animations, or adjust styling.
• Dependency isolation: Installing a Recharts component installs recharts only. Installing a D3 component installs modular micro-packages like d3-shape. No single chart forces you to install an all-in-one bundle.

Example file placement after installing a line chart and a Google GeoChart:

Verify setup

Before installing components, confirm your project configuration using this readiness checklist and run verification commands:

Next steps

With your codebase structured and verified, explore component installation and theming:

• shadcn/ui Setup: Learn how components.json and registry namespaces work.
• Plotcn Registry: Explore the full catalog of source-available visualization components.
• Installation Guide: Revisit package manager commands and framework setup.