API and watch mode
Building the theme from code with build() and generate(), TypeScript types and rebuilding on token changes.
build()
build() does the same as the CLI: reads token files, builds the theme and writes it to output. It takes the same fields as config.json or a path to the config. It returns an object with the contents of the written files.
import { build } from 'tailwind-dictionary';
const files = await build({
version: 4,
source: ['tokens/**/*.json'],
output: './styles',
themeAliases: { color: 'color' },
});
// or
await build({ config: './config.json' });generate()
generate() does not touch the file system: it takes token objects and returns file contents. Use it in your own build scripts, plugins and in the browser.
import { generate } from 'tailwind-dictionary/generate';
const files = await generate({
tokens: { color: { $type: 'color', white: { $value: '#ffffff' } } },
themes: { dark: { color: { white: { $value: '#000000' } } } }, // optional
themeAliases: { color: 'color' },
version: 4,
});
files['tailwind/theme.css'];themes may also contain default (the name of the default theme) and prefix (the v4 variable prefix). Warnings go to console.warn; to intercept them pass logger: { warn(message) {} }.
version | Result keys |
|---|---|
4 | tailwind/theme.css |
3 | tailwind/theme.js, plus tailwind/theme.css with themes |
In the browser generate() works without fs and path polyfills, but it brings Style
Dictionary along: the bundle is sizeable: about 0.8 MB (≈ 265 KB gzipped) in a minified production
build, about 3.6 MB without minification. Load it lazily with a dynamic import().
TypeScript
Types are included: for build(), generate() and the config. Nothing else to install.
import { build } from 'tailwind-dictionary';
import { generate } from 'tailwind-dictionary/generate';For the JSON config use the JSON Schema from the package — it gives autocompletion and hints in the editor:
{
"$schema": "./node_modules/tailwind-dictionary/schema/config.schema.json"
}Watch mode
npx tailwind-dictionary -c ./config.json --watchThe theme is rebuilt when files from source, themes or the config itself change. Only token folders are watched, not the whole project.
Errors
Errors are printed as one line with the file name and the token path, the exit code is 1:
✘ Config file not found: nope.json
✘ Token "color.text" (tokens/color.json) references {color.nope}, which is not defined
✘ No token files matched: tokens/*.jsonThe build stops on a broken reference, typography without fontSize, mixed value and $value, a missing or broken config. An unknown $type and a theme token missing in one of the themes are warnings.