Quick start

Get from zero to styled in under two minutes. This guide uses Vite — for other setups see Installation.

Coming from Tailwind?Most utilities are identical, but a few layout names differ. The ones you'll hit first: flex-col → direction-column, items-center → align-center, flex-wrap → wrap, grid-cols-3 → cols-3. Full comparison →

1. Install

terminal
npm install beamcss @beamcss/vite

2. Create your config

Add beam.config.ts to your project root. This is where your design tokens live — colors, spacing, type scale, breakpoints.

beam.config.ts
import { defineConfig } from 'beamcss'

export default defineConfig({
  tokens: {
    color: {
      base: '#0b0b0c',
      surface: '#16161a',
      fg: '#e8e8ea',
      accent: '#3b82f6',
      'on-accent': '#ffffff',
    },
    radius: { md: '8px' },
    text: { base: '16px', lg: '20px' },
    font: { ui: 'Inter, system-ui, sans-serif' },
    screens: { tablet: '48rem' },
  },
  background: 'base',
  foreground: 'fg',
})

3. Add the Vite plugin

Tell the plugin where your config is and which directory to scan for class strings.

vite.config.ts
import { defineConfig } from 'vite'
import { beamcss } from '@beamcss/vite'

export default defineConfig({
  plugins: [
    beamcss({
      config: './beam.config.ts',
      content: ['./src'],
    }),
  ],
})

The content option takes directory paths — Beam recursively scans them for class and className attributes in .tsx, .jsx, .html, .vue, and .svelte files.

4. Write your first component

Use your token names directly as utility values. No @import needed — Beam injects the compiled CSS automatically.

src/App.tsx
export default function App() {
  return (
    <main className="grid place-center h-screen bg-base text-fg font-ui">
      <div className="flex direction-column align-center gap-4 p-8 bg-surface rounded-md">
        <h1 className="text-lg text-accent font-bold">Hello Beam</h1>
        <button className="rounded-md px-4 py-2 bg-accent text-on-accent
                           hover:(bg-accent+12 scale-105) transition">
          Get started
        </button>
      </div>
    </main>
  )
}

5. Run the dev server

terminal
npm run dev

Beam scans ./src on every save, compiles only the classes you use, and hot-reloads instantly — no full-page reload required.

Next steps