Skip to content
Dispersa

Using the CLI

Install

Section titled “Install”

The quickest way to get a CLI-based project is with the scaffold:

Terminal window
pnpm create dispersa

Choose the CLI template when prompted. This gives you a dispersa.config.ts, token files, and a dispersa build script — ready to run.

Global Install

Section titled “Global Install”

You can also install Dispersa globally to use the CLI across multiple projects without npx:

Terminal window
pnpm add -g dispersa

Basic Usage

Section titled “Basic Usage”
Terminal window
dispersa build

The CLI discovers your configuration automatically and builds all configured outputs.

Config File

Section titled “Config File”

The CLI looks for a config file named dispersa.config.ts (or .js, .mts, .mjs, .cts, .cjs) in your project root. Use defineConfig for type safety:

import { defineConfig } from 'dispersa/config'
import { css, json } from 'dispersa'
import { colorToHex, nameKebabCase } from 'dispersa/transforms'


export default defineConfig({
  resolver: './tokens.resolver.json',
  buildPath: './dist',
  outputs: [
    css({
      name: 'css',
      file: 'tokens.css',
      preset: 'bundle',
      selector: ':root',
      transforms: [nameKebabCase(), colorToHex()],
    }),
    json({
      name: 'json',
      file: 'tokens-{theme}.json',
      preset: 'standalone',
      structure: 'flat',
    }),
  ],
})

Custom Config Path

Section titled “Custom Config Path”

To use a config file in a different location:

Terminal window
dispersa build --config ./my-config.ts

How It Works

Section titled “How It Works”

The CLI uses jiti for dynamic ESM imports, so you can use TypeScript config files (dispersa.config.ts) without precompiling them.

Project Structure Recommended directory layouts for organizing tokens, resolver, and build configuration.