Browse docs

Installation

Three steps. Two minutes. One working Button on screen.

Prerequisites

You should already have a React app with Tailwind CSS configured. If you don't, set one up first — Vite + Tailwind is the fastest path:

bash

pnpm create vite@latest my-app -- --template react-ts
cd my-app
pnpm add -D tailwindcss@^3 postcss autoprefixer
pnpm exec tailwindcss init -p

Required versions: React 18+ (19 supported), Tailwind CSS 3.x, TypeScript 5+ (for the typed token surface and component props).

1. Install Dashforge

pnpm add @dashforge/tw @dashforge/tw-theme @dashforge/tw-tokens

The three packages are versioned independently — you can upgrade tokens without touching components, or patch components without re-validating your theme. See each package's COMPAT.md for the compatibility matrix.

2. Wire the Tailwind preset

Add dashforgePreset() to your tailwind.config.js:

import { dashforgePreset } from '@dashforge/tw-theme';

/** @type {import('tailwindcss').Config} */
export default {
  presets: [dashforgePreset()],
  content: [
    './index.html',
    './src/**/*.{ts,tsx}',
    // Scan the library's own emitted classes so JIT keeps them:
    './node_modules/@dashforge/tw/dist/**/*.{js,mjs}',
  ],
};

What the preset does: it extends Tailwind's theme with the color scales (primary-500, success-600, etc.), the spacing scale, the radii and font sizes from @dashforge/tw-tokens — all of them mapped to CSS variables, not hardcoded values. That's what lets you flip the theme at runtime without rebuilding.

The content line scanning node_modules/@dashforge/tw/dist/** is non-optional. Tailwind's JIT only emits classes it sees in scanned files; the library's compiled output uses our utility classes, so it has to be in the scan or your <Button> will render unstyled.

3. Mount the provider

In your app root (typically main.tsx or App.tsx):

tsx

import { DashforgeTailwindProvider } from '@dashforge/tw-theme';
import './index.css'; // your Tailwind entry — must @tailwind base/components/utilities

export function App() {
  return (
    <DashforgeTailwindProvider>
      <YourApp />
    </DashforgeTailwindProvider>
  );
}

The provider:

Injects the resolved CSS variables on <html> so every Dashforge component (and your own utilities, if you reference our tokens) reads them.
Applies a dark class on <html> when the runtime mode flips to dark. Tailwind's dark: variant lights up.
Persists the user's mode choice in localStorage (key: dashforge-tw-mode).

4. Your first component

Drop a <Button> somewhere and confirm it paints:

tsx

import { Button } from '@dashforge/tw';

export function Hello() {
  return (
    <div className="p-8">
      <Button color="primary">It works</Button>
    </div>
  );
}

If you see a primary-colored button with a hover ring, you're done. If you see an unstyled <button>, jump to Troubleshooting — the most likely cause is the missing content entry for node_modules/@dashforge/tw/dist in step 2.

Next steps

Usage — build a real screen with the provider, the components, and a theme toggle.
Design Tokens — override colors, change the radius scale, define your own brand.
Components → Button — every variant, every prop, every escape hatch.