@knapsack/design-tokens-cli

Standalone, publishable CLI for the design-token build step: read a tokens JSON source, convert it, and write per-target files. It does not require the full knapsack CLI.

Output files are produced with the same converter (convertTokenDataToFiles) and writer (writeFormattedFile) as knapsack design-tokens build, so results match for the same input when at least one target is enabled.

Install

pnpm add -D @knapsack/design-tokens-cli

Requires Node.js 22.12 or later (configure() uses util.getCallSites()).

Config

Create design-tokens-cli.config.mjs in the working directory, or point at another .mjs file with --config ./path.mjs. Only .mjs config files are supported; a config with another extension (such as design-tokens-cli.config.ts) fails with a message naming the .mjs file to rename it to.

import { configure } from '@knapsack/design-tokens-cli';

export default configure({
  srcFilePath: './src/knapsack.design-tokens.json',
  distDir: './dist/tokens',
  // Omit `targets` to generate every target. Set `enabled: false` per target to skip.
  targets: {
    css: { enabled: true },
    js: { enabled: true },
    android: { enabled: false },
    ios: { enabled: false },
  },
});

The config shape matches KnapsackConfig['designTokens'] (srcFilePath, distDir, targets). srcFilePath is required. configure() resolves relative paths against the directory of the config file, so the build behaves the same from any working directory. The default export must be wrapped in configure() (or use absolute paths). If distDir is omitted, output goes to ./dist/tokens next to the config file, or in the working directory when there is no config.

Commands

design-tokens-cli build
design-tokens-cli build --config ./design-tokens-cli.config.mjs
design-tokens-cli build --src-file-path ./tokens.json --dist-dir ./dist
design-tokens-cli build --targets css,js

CLI flags override the same option in the config file. Flag paths resolve against the working directory.

Telemetry

Failures print to the terminal with the full cause chain. Best-effort Datadog telemetry (public client token) reports each failure with its message, stack trace, cause chain, and error code. Stack traces and messages can include local file paths. Set KS_DISABLE_TELEMETRY=yes to skip Datadog. The send is time-boxed so a blocked Datadog intake cannot hang the CLI.