Configuration

The catalogue is configured via catalogue.config.ts in your project root.

Full Configuration

export default {
  // Display title for the catalogue
  title: 'My Component Library',

  // Path to registry directory (relative to config)
  registryDir: './registry',

  // Output directory for static builds
  outDir: './dist/catalogue',

  // Base path for deployment
  // Use '/' for root, '/docs/' for subdirectory
  basePath: '/',

  // Development server port
  port: 5173,

  // Component source configuration
  components: {
    // Entry point that exports all components
    entry: './src/components/index.ts',

    // Optional: npm package name for imports
    package: '@myorg/components',
  },

  // Playwright visual testing configuration
  playwright: {
    // Breakpoints for screenshot testing
    breakpoints: [
      { name: 'mobile', width: 375, height: 667 },
      { name: 'tablet', width: 768, height: 1024 },
      { name: 'desktop', width: 1280, height: 800 },
    ],

    // Themes to test
    themes: ['light', 'dark'],

    // Screenshot output directory
    screenshotDir: './screenshots',
  },

  // Additional Vite configuration (merged with defaults)
  vite: {
    // Any valid Vite config options
  },
};

Configuration Options

title

• Type: string
• Default: 'Component Catalogue'

The title displayed in the catalogue header.

registryDir

• Type: string
• Default: './registry'

Path to the registry directory containing component definitions.

outDir

• Type: string
• Default: './dist/catalogue'

Output directory for catalogue build.

basePath

• Type: string
• Default: '/'

Base path for deployment. Set this if hosting in a subdirectory:

// For https://example.com/docs/components/
basePath: '/docs/components/',

port

• Type: number
• Default: 5173

Port for the development and preview servers.

components.entry

• Type: string
• Default: './src/components/index.ts'

Entry point file that exports all web components. This file is imported by the catalogue to register custom elements.

playwright.breakpoints

• Type: Array<{ name: string, width: number, height: number }>

Viewport sizes for visual regression testing.

playwright.themes

• Type: Array<'light' | 'dark'>
• Default: ['light', 'dark']

Themes to test during visual regression.

Environment-Specific Config

Use environment variables or conditional logic:

const isDev = process.env.NODE_ENV === 'development';

export default {
  title: 'My Components',
  basePath: isDev ? '/' : '/production-path/',
  port: isDev ? 5173 : 4173,
};

TypeScript Support

The config file supports TypeScript out of the box. For type hints, you can use JSDoc:

/** @type {import('@clearforest/catalogue-cli').CatalogueConfig} */
export default {
  title: 'My Components',
  // ...
};