@kanso-labs/unplugin-style-dictionary 0.8.0 → 0.10.0

package/{LICENSE → LICENSE.md}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Kanso
+Copyright (c) 2026 Kanso Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -10,19 +10,23 @@ compile **Style Dictionary** design tokens ahead of your bundler, with automatic
 watching, rebuilding, and hot reloading (HMR) under Vite's dev server.
 
 Built on unplugin, the same core plugin targets **Vite**, **Rolldown**,
-**Rollup**, and **Webpack** from a single implementation — useful when a project
-has more than one build surface (e.g. Storybook/Vitest on Vite, and a package
-build on Rolldown/tsdown) that both need tokens compiled ahead of them.
+**Rollup**, **Rspack**, and **Webpack** from a single implementation — useful
+when a project has more than one build surface (e.g. Storybook/Vitest on Vite,
+and a package build on Rolldown/tsdown) that both need tokens compiled ahead of
+them.
 
 ## Features
 
-- **Multi-bundler**: One implementation, four entry points — Vite, Rolldown,
-  Rollup, and Webpack.
-- **Asynchronous builds**: Native support for Style Dictionary v4/v5 async
-  compilation API.
+- **Multi-bundler**: One implementation, five entry points — Vite, Rolldown,
+  Rollup, Rspack, and Webpack.
+- **Asynchronous builds**: Native support for Style Dictionary v5's async
+  compilation API. The `style-dictionary` range in
+  [`package.json`](package.json)'s `peerDependencies` is the contract — this
+  bullet follows it rather than standing beside it.
 - **Automatic watching**: Reads the `source` and `include` patterns from your
-  Style Dictionary configurations and watches the files they match. What a
-  change then triggers depends on the target — see
+  Style Dictionary configurations and watches the files they match, including a
+  token package resolved through `node_modules` in a workspace. What a change
+  then triggers depends on the target — see
   [Watching, per target](#watching-per-target).
 - **Config flexibility**: Supports file paths (JSON, JSON5, JSONC, JS, MJS, TS),
   configuration objects, or functions — including registering custom formats at
@@ -47,9 +51,19 @@ build on Rolldown/tsdown) that both need tokens compiled ahead of them.
 npm install @kanso-labs/unplugin-style-dictionary style-dictionary --save-dev
 ```
 
-_Note: `style-dictionary` and your bundler (`vite`, `rolldown`, `rollup`, or
-`webpack`) are peer dependencies, so you can manage their versions
-independently._
+_Note: `style-dictionary` and your bundler (`vite`, `rolldown`, `rollup`,
+`@rspack/core`, or `webpack`) are peer dependencies, so you can manage their
+versions independently._
+
+**`style-dictionary` is the one peer that is not optional**, and its range is
+`^5.0.0`. An older major is refused at the install rather than failing later:
+
+```
+npm error code ERESOLVE
+npm error Found: style-dictionary@4.4.0
+npm error Could not resolve dependency:
+npm error peer style-dictionary@"^5.0.0" from @kanso-labs/unplugin-style-dictionary@0.9.0
+```
 
 **This package needs Node 22.12 or newer.** The floor is Style Dictionary v5's,
 not this plugin's: every 5.x release declares `engines.node >= 22.0.0`, and it
@@ -98,11 +112,12 @@ generated token files exist before the rest of the build consumes them.
 Under a real `rolldown.watch()`, do not rely on a token edit triggering a
 rebuild — see [Watching, per target](#watching-per-target).
 
-### Rollup / Webpack
+### Rollup / Webpack / Rspack
 
 ```typescript
 import StyleDictionary from '@kanso-labs/unplugin-style-dictionary/rollup'
 // or: import StyleDictionary from '@kanso-labs/unplugin-style-dictionary/webpack'
+// or: import StyleDictionary from '@kanso-labs/unplugin-style-dictionary/rspack'
 ```
 
 A `webpack.config.js` is often CommonJS rather than ESM. This package ships ESM
@@ -119,6 +134,14 @@ module.exports = {
 }
 ```
 
+**Rspack is webpack's plugin API, and this package treats it as one.** Swap the
+import for `…/rspack` and an `rspack.config.js` reads the same, `.default` hop
+included. Everything below that mentions webpack — where a relative `config` is
+resolved from, where a failed compile is reported, what a `config` function is
+told about the build — holds there too, and `tests/webpack-api.test.ts` runs the
+same cases against both. It installs as `@rspack/core`, which is the peer this
+package declares.
+
 _Note: that path needs Node 20.19+ or 22.12+, the versions that can `require` an
 ES module. Every Node release still in support clears it. Importing from ESM has
 no such floor._
@@ -127,6 +150,33 @@ _The subpaths also need a TypeScript `moduleResolution` of `bundler`, `node16`
 or `nodenext`. The deprecated `node10` cannot resolve them, and TypeScript 6
 already warns that it stops working in 7._
 
+### Finding a Config File
+
+With no `config`, the root is searched for `sd.config.json`, `config.json`,
+`sd.config.js` and `sd.config.mjs`, in that order — and the first one that
+**looks like a Style Dictionary configuration** wins. That means declaring at
+least one of `platforms`, `source`, `include` or `tokens`. A candidate that
+fails the check is reported and skipped rather than adopted, so an unrelated
+`config.json` — an extremely common name for something else — no longer gets
+compiled over and added to the watch set. The path that was picked is printed,
+so which configuration a build used is answerable from the console.
+
+`config.json` stays in the list because Style Dictionary's own CLI defaults to
+it, so a project relying on that default keeps working.
+
+**Two of the four names are modules, and reading a module runs it.** A root
+`sd.config.js` is imported — freshly, on every watch event — and validation
+cannot prevent that, because the check can only look at what the import
+returned. If you name your configuration explicitly, or have none, say so:
+
+```typescript
+StyleDictionary({ config: false })
+```
+
+That turns discovery off entirely: nothing is looked for, nothing is watched,
+and nothing is compiled. A configuration you name yourself is never
+second-guessed by the check above — it goes straight to Style Dictionary.
+
 ### Config File Formats
 
 A `config` path may be `.json`, `.json5`, `.jsonc`, `.js`, `.mjs` or `.ts`. The
@@ -262,6 +312,23 @@ export default defineConfig({
 })
 ```
 
+## Platforms
+
+Linux, macOS and Windows. All three run the suite in CI, and Windows is a
+`Test on Windows` job rather than a claim — it was added after two defects
+reached `main` because nothing ran there.
+
+Both are fixed. The atomic write used to fail under the condition it exists for:
+with a reader holding the destination open, Windows refuses the rename, so the
+compile failed rather than the read being protected. The rename now backs off on
+`EPERM` and `EBUSY` and retries, bounded, so a rename that genuinely cannot
+succeed still fails rather than hanging a dev server.
+
+And a token package resolved through `node_modules` used to build once and never
+rebuild. Vite's watcher cannot be made to deliver those events on Windows — no
+spelling of the ignore-list negation reaches them, and `watcher.add()` does not
+either — so the plugin watches those directories itself, on every platform.
+
 ## Watching, per target
 
 Every target compiles tokens before the build that consumes them. What a later
@@ -273,6 +340,7 @@ on what the host bundler does with the watch list the plugin registers.
 | **Vite**     | yes                       | yes, under the dev server      | yes                     |
 | **Rollup**   | yes                       | yes, under `rollup --watch`    | yes                     |
 | **Webpack**  | yes                       | yes, under `webpack --watch`   | yes                     |
+| **Rspack**   | yes                       | yes, under `rspack --watch`    | yes                     |
 | **Rolldown** | yes                       | platform-dependent — see below | yes                     |
 
 Patterns and literal paths behave the same way wherever rebuilds happen at all.
@@ -287,12 +355,78 @@ reaches no hook, while on a Linux runner the same edit reaches a rebuild. Treat
 rolldown's watch mode as compiling once and not tracking tokens, and reach for a
 one-shot build or another target if you need rebuild-on-change.
 
+**A token package resolved through `node_modules` is watched too, and that took
+a fix.** In a workspace — `app/node_modules/@acme/tokens` symlinked to
+`packages/tokens` — Vite's dev-server watcher is built with `**/node_modules/**`
+already in its ignore list, and the entries a consumer adds are appended after
+it rather than subtracted from it. So the first build was correct and no edit
+ever rebuilt, with nothing printed to say so. The plugin now un-ignores exactly
+the files it registers, by name, on Vite 6, 7 and 8. The rest of `node_modules`
+stays ignored, which matters: handing the whole dependency tree to the watcher
+is thousands of files no token build reads.
+
+Nothing is needed from you for that. If you had worked around it with a
+`server.watch.ignored` negation of your own, it still works — the plugin appends
+to your list rather than replacing it.
+
 "Safe from rebuild loops" is worth stating because consuming code imports the
 generated file, so every regenerate is itself a change the host reacts to. The
 plugin subtracts its own output from the watch list, skips recompiling when a
 watch rebuild re-enters `buildStart`, and skips the write entirely when a
 rebuild renders bytes identical to what is already on disk.
 
+## Building Only Some Platforms
+
+Every rebuild used to compile every platform, so a dev server serving a web app
+paid for Objective-C headers, Android XML and Dart classes on every token save.
+`platforms` narrows it:
+
+```typescript
+StyleDictionary({
+  config: 'sd.config.json',
+  // Build everything once, then rebuild only css while serving.
+  platforms: { watch: ['css'] },
+})
+```
+
+Measured on a six-platform configuration (css, scss, js, ios, android, flutter),
+with the timer around the build call alone:
+
+| Tokens | All platforms | css only | Saved  |
+| ------ | ------------- | -------- | ------ |
+| 500    | 12 ms         | 1 ms     | 10 ms  |
+| 3,000  | 36 ms         | 2 ms     | 34 ms  |
+| 10,000 | 103 ms        | 4 ms     | 99 ms  |
+| 30,000 | 330 ms        | 12 ms    | 319 ms |
+
+An array — `platforms: ['css']` — applies to every build. The object form splits
+the first compile from the watch rebuilds, and an omitted key means every
+platform. A name the configuration does not define is an error, matching Style
+Dictionary's own CLI.
+
+**Unselected platforms keep whatever they last wrote.** Nothing removes or
+refreshes their files, so scoping the `build` half ships stale output for the
+rest. Scope `watch` unless that is what you want.
+
+## Generated Output Is Disposable
+
+Nothing removes a generated file, ever. Drop a `files` entry from a
+configuration, remove a whole platform, or move a `buildPath`, and the old
+output stays where it was — still resolving, still importable, still carrying
+its old token values, and in a package build still published, with nothing in
+the log mentioning it.
+
+So treat the build directory as disposable: delete it when a configuration
+changes shape, and keep it out of version control and out of any directory
+holding hand-written files.
+
+There is deliberately no `clean` option. Style Dictionary's
+`cleanAllPlatforms()` does not solve this — it removes the destinations the
+_current_ configuration declares, which are exactly the files that are not
+orphans, and it removes the `buildPath` directory along with them. Measured:
+after dropping `legacy.scss` from a configuration, a clean run left
+`legacy.scss` standing and deleted `vars.css`, the file still in use.
+
 ## Skipping a Build That Would Change Nothing
 
 A configuration whose output is already newer than everything it reads is not
@@ -340,8 +474,8 @@ and does not cache anything for later.
 Two bases, and which one applies depends on whose path it is.
 
 **The `config` option is the plugin's**, so a relative path is looked up under
-the host's root: Vite's `root`, webpack's `context`, and the working directory
-for rollup and rolldown, which report none. `root` overrides that.
+the host's root: Vite's `root`, webpack's or rspack's `context`, and the working
+directory for rollup and rolldown, which report none. `root` overrides that.
 
 **Everything inside a Style Dictionary configuration is Style Dictionary's**, so
 `source`, `include` and `buildPath` are resolved against the working directory.
@@ -399,13 +533,20 @@ own way:
 | ------------------ | ------------------------ | ---------------------------------- |
 | Vite               | `config.logger.info`     | `config.logger.error`              |
 | Rollup, Rolldown   | the plugin context's log | the context's warning channel      |
-| Webpack            | the console              | `compilation.warnings`, so `stats` |
+| Webpack, Rspack    | the console              | `compilation.warnings`, so `stats` |
 | No host (one-shot) | the console              | the console                        |
 
 That is what makes a `customLogger` and `clearScreen` work under Vite, and what
 puts a failed compile into `stats.toJson()` under webpack — where it reaches CI
 annotations and anything else reading the build's own output.
 
+**Rspack reformats what it is given, and webpack does not.** The plugin hands
+both the same plain text; rspack wraps every diagnostic in its own frame — a `⚠`
+marker and a `│` gutter — and colours that frame whenever it thinks colour is
+wanted, which setting `CI` is enough to do. So a warning read out of rspack's
+`stats` can carry ANSI escapes that came from rspack rather than from here.
+Strip them before feeding that text to anything that expects plain output.
+
 **A failure is reported as a warning, never on the host's error channel.**
 Rollup's `this.error` aborts the bundle, so reporting a failure through it would
 stop every build that reported one — taking the decision `failOnError` exists to
@@ -443,6 +584,19 @@ StyleDictionary({
 })
 ```
 
+**A configuration that resolves no tokens is a failure, not an empty build.**
+Style Dictionary writes the destination with nothing in it and reports success,
+so a token file deleted mid-session used to take the generated output down with
+it, and a `source` matching nothing shipped an empty stylesheet from a build
+that exited 0. The check runs before the compile, so the previous good output is
+still on disk when it fires and nothing is overwritten. The message names the
+configuration and the patterns that matched no files.
+
+This is about the resolved token set, not about the patterns: a configuration
+that supplies `tokens` inline and declares no `source` at all is valid and
+builds. And it goes through `failOnError` like any other compile failure, so
+`failOnError: false` reports it and carries on.
+
 A failure is always reported by the plugin, whatever `failOnError` and `silent`
 are set to — see [Where the messages go](#where-the-messages-go) for which
 channel it arrives on, and for the one thing that can still suppress it.
@@ -497,14 +651,14 @@ the host stops, the other is that a build went wrong.
 
 ## Public API
 
-Small on purpose. Four bundler entry points, one root entry, and two types.
+Small on purpose. Five bundler entry points, one root entry, and two types.
 
-| Import                                          | What it is                                                                                                             |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `…/vite`, `…/rolldown`, `…/rollup`, `…/webpack` | Default export: the plugin for that bundler. Call it with the options below.                                           |
-| `…` (the root)                                  | Default export, also named `unplugin`: the unplugin instance, carrying `.vite`, `.rolldown`, `.rollup` and `.webpack`. |
-| `UnpluginStyleDictionaryOptions`                | The options type, exported from every entry above.                                                                     |
-| `StyleDictionaryConfigContext`                  | What the function form of `config` is handed, exported from every entry above.                                         |
+| Import                                                      | What it is                                                                                                                        |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `…/vite`, `…/rolldown`, `…/rollup`, `…/rspack`, `…/webpack` | Default export: the plugin for that bundler. Call it with the options below.                                                      |
+| `…` (the root)                                              | Default export, also named `unplugin`: the unplugin instance, carrying `.vite`, `.rolldown`, `.rollup`, `.rspack` and `.webpack`. |
+| `UnpluginStyleDictionaryOptions`                            | The options type, exported from every entry above.                                                                                |
+| `StyleDictionaryConfigContext`                              | What the function form of `config` is handed, exported from every entry above.                                                    |
 
 Anything not in that table is internal, whatever a build output happens to
 contain. In particular the watch filter and the raw unplugin factory are not
@@ -524,7 +678,7 @@ const plugin = styleDictionary.rollup({ config: 'sd.config.json' })
 
 ## Options Reference
 
-```typescript
+````typescript
 /**
  * Options for the Style Dictionary unplugin factory, shared across all bundler
  * targets (Vite, Rolldown, Rollup, Webpack).
@@ -651,7 +805,19 @@ export interface UnpluginStyleDictionaryOptions {
    *
    * If not provided, the root directory is searched for 'sd.config.json',
    * 'config.json', 'sd.config.js' and 'sd.config.mjs', in that order. The
-   * first one that exists wins, and the rest are not looked at.
+   * first one that *looks like a Style Dictionary configuration* wins — it has
+   * to declare at least one of `platforms`, `source`, `include` or `tokens` —
+   * and the path it picked is announced, so which file a build used is
+   * answerable from the console. A candidate that fails that check is reported
+   * and skipped rather than adopted, because `config.json` is an extremely
+   * common name for something else entirely.
+   *
+   * **`false` turns discovery off.** Two of the four names are modules rather
+   * than data, and reading a module means running it: a `sd.config.js` in the
+   * root is imported, freshly, on every watch event. Validation cannot prevent
+   * that, because the check can only look at what the import returned — so a
+   * project that names its configuration explicitly, or has none, should say
+   * `config: false` rather than rely on there being nothing to find.
    */
   config?:
     | ((
@@ -659,6 +825,7 @@ export interface UnpluginStyleDictionaryOptions {
       ) => Config | Config[] | Promise<Config | Config[]>)
     | Config
     | Config[]
+    | false
     | string
     | string[]
 
@@ -780,6 +947,48 @@ export interface UnpluginStyleDictionaryOptions {
    */
   onBuildStart?: () => Promise<void> | void
 
+  /**
+   * Which platforms to build, by the names the configuration defines.
+   *
+   * Every rebuild used to compile every platform. Measured on a six-platform
+   * configuration (css, scss, js, ios, android, flutter), with the timer around
+   * the build call alone:
+   *
+   * ```
+   * tokens   all platforms   css only   saved
+   *    500          12 ms       1 ms    10 ms
+   *   3000          36 ms       2 ms    34 ms
+   *  10000         103 ms       4 ms    99 ms
+   *  30000         330 ms      12 ms   319 ms
+   * ```
+   *
+   * So a dev server serving a web app paid for Objective-C headers, Android
+   * XML and Dart classes on every token save, and the cost grows with the
+   * token count.
+   *
+   * Two shapes. An array selects the same platforms for every build. An object
+   * splits the first compile from the watch rebuilds, which is the common
+   * want — build everything once, then rebuild only what the page uses:
+   *
+   * ```typescript
+   * platforms: ['css']
+   * platforms: { watch: ['css'] }
+   * ```
+   *
+   * An omitted key means every platform, so `{ watch: ['css'] }` builds all of
+   * them once and then only css. A name the configuration does not define is an
+   * error, matching Style Dictionary's own CLI — "Must be defined in the
+   * config".
+   *
+   * **Unselected platforms keep whatever they last wrote.** Their files are not
+   * removed and not refreshed, so a one-shot build that scopes platforms ships
+   * stale output for the rest. Scope the watch half rather than the build half
+   * unless that is what you want.
+   *
+   * @default undefined, which builds every platform
+   */
+  platforms?: string[] | { build?: string[]; watch?: string[] }
+
   /**
    * Whether the table of generated files and their sizes is produced.
    *
@@ -843,7 +1052,7 @@ export interface UnpluginStyleDictionaryOptions {
    */
   watch?: string | string[]
 }
-```
+````
 
 ## Migrating from `vite-plugin-style-dictionary`
 
@@ -864,6 +1073,68 @@ plugin. As of this unplugin-based rewrite:
 - Behavior under Vite is unchanged: the same `buildStart`-time compilation and
   dev-server watch/rebuild logic as before.
 
+## Development
+
+Fork, then clone the repository:
+
+```shell
+git clone https://github.com/your-username/unplugin-style-dictionary.git
+```
+
+Install with the Node version in [`.tool-versions`](.tool-versions). CI resolves
+it from that file, and an older npm rewrites `package-lock.json` as it installs.
+If `node --version` disagrees:
+
+```shell
+mise exec node@"$(awk '/^nodejs/{print $2}' .tool-versions)" -- npm install
+```
+
+### The four commands
+
+These are what CI runs, and between them they are the whole gate:
+
+```shell
+npm run lint           # oxlint, then ESLint, then oxfmt --check
+npm run build          # tsc -b, then tsdown into dist/
+npm test               # vitest, one run, no watch
+npm run package:check  # publint, attw, then scripts/check-package.mjs
+```
+
+`npm run package:check` reads `dist/`, so it needs a build first.
+`npm run peers:check` is the slower one that packs the tarball and builds it
+against both ends of every declared peer range; `Build` runs it, and it is worth
+running locally when you touch the exports map or the peer declarations.
+
+**oxfmt formats this repository, not Prettier**, and it covers Markdown, JSON
+and YAML as well as TypeScript. `npm run lint -- --fix` will not reformat
+anything — reach for `npm run format`.
+
+### Tests
+
+`tests/` drives real bundlers against real files in temporary directories rather
+than mocking Style Dictionary: a real Vite dev server, a real `rollup.watch()`,
+a real `webpack()` compile, a real `rspack()` compile, and all five targets
+through their own entry points. A new hook needs a matching caller in
+`tests/index.test.ts` — calling one bare leaves `this` undefined and the failure
+reads as a plugin bug.
+
+The suite prints nothing. If you add a test that provokes the plugin's failure
+report, spy on `console.error`, **assert the message is there**, and restore in
+a `finally`. You can check the whole suite is quiet with:
+
+```shell
+npx vitest run --reporter=verbose 2>&1 | grep -E '^std(out|err) \|'
+```
+
+That should print nothing.
+
+[`AGENTS.md`](AGENTS.md) carries the conventions, the traps, and the reasoning
+behind both. It is written for coding agents and is equally the fullest thing a
+human contributor can read.
+
+Contribution guidelines for the organization are in
+[`kanso-labs/.github`](https://github.com/kanso-labs/.github).
+
 ## License
 
 MIT
@@ -875,7 +1146,7 @@ MIT
 [codecov]: https://codecov.io/gh/kanso-labs/unplugin-style-dictionary
 [coverage-shield]:
   https://img.shields.io/codecov/c/github/kanso-labs/unplugin-style-dictionary?label=Coverage
-[license]: ./LICENSE
+[license]: ./LICENSE.md
 [license-shield]:
   https://img.shields.io/github/license/kanso-labs/unplugin-style-dictionary
 [npm]: https://www.npmjs.com/package/@kanso-labs/unplugin-style-dictionary