Quick Start

🔄 Auto-generated mirror. Canonical source: docs/quick-start.md. Edit there — changes here are overwritten by CI.

Quick start

Nav: Quick start · Writing cases · Hierarchy · Tweaks · Theming · Documentation panel · Writing placard docs · Testing · CLI · AI agents · Configuration

Get a component browsing in a few minutes. Everything here runs on Bun — no bundler config, no separate dev server.

1. Write a config

Display Case looks for a display-case.config.ts at the root of the package it is pointed at. It must default-export defineConfig(...).

// display-case.config.ts
import { defineConfig } from '@awarebydefault/display-case'

export default defineConfig({
  title: 'Display Case',
  roots: ['src/components/**/*.case.tsx'],
  globalStyles: ['./src/tokens.css', './src/components.css'],
})

• title shows in the browsing chrome and the manifest.
• roots are globs (relative to the package) that locate your case files.
• globalStyles are CSS entrypoints injected into every preview, so components render with their real tokens and styles.

Full reference: Configuration.

2. Write a case file

A case file is *.case.tsx, colocated with the component it showcases. It default-exports defineCases(...).

// src/components/tweak-control.case.tsx
import { defineCases } from '@awarebydefault/display-case'
import { TweakControl } from './tweak-control'

export default defineCases('TweakControl', {
  Variants: () => (
    <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
      <TweakControl kind="text" label="Label" value="Save" />
      <TweakControl kind="choice" label="Variant" options={['default', 'outline']} value="default" />
      <TweakControl kind="boolean" label="Disabled" value={false} />
    </div>
  ),
}, { level: 'atom' })

The render functions are lazy thunks — they only run when a case is viewed or screenshotted. Keep the module side-effect-free at the top level; the server imports it to build the manifest without ever calling them.

3. Start the server

Point the CLI at the package directory:

bunx @awarebydefault/display-case .

Or wire up an npm script and use that:

// package.json
{ "scripts": { "display-case": "display-case ." } }

bun run display-case

The server prints its URL (default http://localhost:3100). Open it and you'll see your components grouped by hierarchy level in the sidebar, with each case rendered in an isolated frame.

Change a *.case.tsx or *.placard.md file and the server rebuilds automatically. There is no in-page hot reload — refresh to pick up the change.

4. Next steps

• Add interactive controls: Tweaks.
• Group and order components: Hierarchy.
• Document a component inline: Documentation panel.
• Catch regressions: Testing.