JavaScript / TypeScript

Overview

The js() builder renders design tokens as ES modules. Supports flat or nested structure, optional lookup helpers, and TypeScript declaration generation.

import { js } from 'dispersa'

Options

Option	Type	Default	Description
name	string	—	Unique output identifier
file	string or function	—	Output path (supports {*context*} interpolation for modifiers)
preset	’bundle’ | ‘standalone'	'standalone’	Output preset
structure	’flat’ | ‘nested'	'nested’	Token structure
moduleName	string	’tokens’	Module name for exports
generateHelper	boolean	—	Generate token lookup helper
minify	boolean	—	Minify output
transforms	Transform[]	—	Per-output transforms
filters	Filter[]	—	Per-output filters

Basic Flat Output

import { Dispersa, js } from 'dispersa'
import { nameCamelCase, colorToHex, dimensionToPx } from 'dispersa/transforms'

await dispersa.build({
  outputs: [
    js({
      name: 'tokens',
      file: 'tokens.js',
      structure: 'flat',
      moduleName: 'tokens',
      transforms: [nameCamelCase(), colorToHex(), dimensionToPx()],
    }),
  ],
})

Output:

export const colorBrandPrimary = '#0066cc'
export const spacingMedium = '16px'

Nested Output

js({
  name: 'tokens',
  file: 'tokens.js',
  structure: 'nested',
  moduleName: 'tokens',
  transforms: [colorToHex(), dimensionToPx()],
})

Output:

export const color = {
  brand: {
    primary: '#0066cc'
  }
}
export const spacing = {
  medium: '16px'
}

Token Lookup Helper

When generateHelper is true (bundle mode), a getTokens() lookup function is added:

js({
  name: 'tokens',
  file: 'tokens.js',
  preset: 'bundle',
  structure: 'flat',
  generateHelper: true,
  moduleName: 'tokens',
  transforms: [nameCamelCase(), colorToHex()],
})

The helper returns the resolved token set for a given modifier combination (e.g., getTokens({ theme: 'dark' })).

Type Generation

Generate a TypeScript declaration file for your tokens:

const tokens = await dispersa.resolveTokens('./tokens.resolver.json')
await dispersa.generateTypes(tokens, 'tokens.d.ts', { moduleName: 'tokens' })

Tailwind CSS v4 Generate Tailwind CSS v4 theme files with @theme blocks and custom variants.