Dispersa API

Core Functions

Dispersa provides standalone functions instead of a class:

import {
  build,
  buildOrThrow,
  buildPermutation,
  resolveTokens,
  lint,
  resolveAllPermutations,
  generateTypes,
} from 'dispersa'

build(config)

Runs a full build. Never throws — returns a BuildResult with success and optional errors.

build(config: BuildConfig): Promise<BuildResult>

import { build, css } from 'dispersa'

const result = await build({
  resolver: './tokens.resolver.json',
  buildPath: './dist',
  outputs: [css({ name: 'tokens', file: 'tokens.css' })],
})

if (result.success) {
  for (const output of result.outputs) {
    console.log(`${output.name}: ${output.path}`)
  }
} else {
  for (const err of result.errors ?? []) {
    console.error(`${err.code}: ${err.message}`)
  }
}

buildOrThrow(config)

Same as build, but throws on failure instead of returning errors.

buildOrThrow(config: BuildConfig): Promise<BuildResult>

import { buildOrThrow, css } from 'dispersa'

await buildOrThrow({
  resolver: './tokens.resolver.json',
  outputs: [css({ name: 'tokens', file: 'tokens.css' })],
})

buildPermutation(config, modifierInputs?)

Builds a single permutation with the given modifier inputs. Useful for generating one variant at a time.

buildPermutation(config: BuildConfig, modifierInputs?: ModifierInputs): Promise<BuildResult>

import { buildPermutation, css } from 'dispersa'

const result = await buildPermutation(
  {
    resolver: './tokens.resolver.json',
    outputs: [css({ name: 'dark', file: 'dark.css' })],
  },
  { theme: 'dark', density: 'compact' },
)

resolveTokens(resolver, modifierInputs?)

Resolves tokens for a resolver without rendering. Returns the resolved token map for the given modifier inputs.

resolveTokens(
  resolver: string | ResolverDocument,
  modifierInputs?: ModifierInputs,
): Promise<Record<string, ResolvedToken>>

import { resolveTokens } from 'dispersa'

const tokens = await resolveTokens('./tokens.resolver.json', {
  mode: 'light',
})
console.log(tokens['color.background.default'])

lint(options)

Runs lint rules on resolved tokens. Returns a LintResult with issues and counts.

lint(options: LintOptions): Promise<LintResult>

LintOptions accepts:

Property	Type	Description
resolver	string | ResolverDocument	Resolver file path or inline object
modifierInputs	Record<string, string>	Modifier values (e.g., { theme: 'dark' })
validation	ValidationOptions	Validation settings
plugins	Record<string, LintPlugin>	Lint plugins to load
rules	Record<string, RuleConfig>	Rule configurations
failOnError	boolean	Throw on lint errors (default: true)

import { lint } from 'dispersa'
import { recommendedConfig } from 'dispersa/lint'

const result = await lint({
  resolver: './tokens.resolver.json',
  ...recommendedConfig,
})
console.log(`Found ${result.errorCount} errors, ${result.warningCount} warnings`)

resolveAllPermutations(resolver)

Resolves tokens for every permutation defined in the resolver. Returns an array of { tokens, modifierInputs }.

resolveAllPermutations(
  resolver: string | ResolverDocument,
): Promise<{ tokens: Record<string, ResolvedToken>; modifierInputs: ModifierInputs }[]>

import { resolveAllPermutations } from 'dispersa'

const permutations = await resolveAllPermutations('./tokens.resolver.json')
for (const { tokens, modifierInputs } of permutations) {
  console.log('Permutation:', modifierInputs)
  console.log('Tokens:', Object.keys(tokens).length)
}

generateTypes(tokens, fileName, options?)

Generates TypeScript types for a resolved token map and writes to a file.

generateTypes(
  tokens: Record<string, ResolvedToken>,
  fileName: string,
  options?: { moduleName?: string },
): Promise<void>

import { resolveTokens, generateTypes } from 'dispersa'

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

BuildConfig

Configuration passed to build, buildOrThrow, and buildPermutation:

Option	Type	Description
resolver	string | ResolverDocument	Resolver file path or inline document
buildPath	string	Output directory
outputs	OutputConfig[]	Required. Output configurations
validation	{ mode?: 'error' | 'warn' | 'off' }	Validation mode
filters	Filter[]	Global filters applied before any output
transforms	Transform[]	Global transforms applied before any output
preprocessors	Preprocessor[]	Preprocessors applied to raw tokens
permutations	ModifierInputs[]	Explicit permutation list
lint	LintBuildConfig	Lint configuration
hooks	LifecycleHooks	onBuildStart, onBuildEnd

BuildResult

Returned by build, buildOrThrow, and buildPermutation:

Property	Type	Description
success	boolean	Whether the build completed without errors
outputs	{ name: string; path?: string; content: string }[]	Per-output results
errors	BuildError[]	Present when success is false
lintResult	LintResult	Lint results when linting is enabled

BuildError

Property	Type	Description
message	string	Human-readable error message
code	ErrorCode	Error category
path	string	File path when relevant
tokenPath	string	Token path when relevant
severity	'error' | 'warning'	Severity level
suggestions	string[]	Suggested fixes (e.g. similar token names)

ErrorCode

'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN'

Error handling

Use build() when you want to handle errors programmatically. Use buildOrThrow() when you want failures to propagate as exceptions.

Builder Functions Configure CSS, JSON, JS, Tailwind, iOS, and Android outputs.

Types Reference Full TypeScript definitions for all public types.