@kanso-labs/unplugin-style-dictionary 0.7.0 → 0.9.0

package/README.md

@@ -21,12 +21,16 @@ build on Rolldown/tsdown) that both need tokens compiled ahead of them.
 - **Asynchronous builds**: Native support for Style Dictionary v4/v5 async
   compilation API.
 - **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
   config-resolution time.
+- **Error overlay**: A rebuild that fails under Vite's dev server is pushed to
+  the error overlay rather than only to the terminal, and cleared on the next
+  one that succeeds.
 - **Atomic writes**: Every generated file is written to a temporary sibling and
   renamed into place, so code importing a token file while it is being rebuilt
   never reads a half-written file.
@@ -124,6 +128,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
@@ -191,6 +222,38 @@ source and no config file does not reach it, so a dev server editing unrelated
 project files leaves it alone — treat it as the place to prepare a build, not as
 a general file-change hook.
 
+**It is handed what the host is doing**, so the configuration it returns can
+depend on it — build an expensive platform on `vite build` and skip it while the
+dev server runs:
+
+```typescript
+styleDictionaryPlugin({
+  config: ({ command, mode, watch }) => ({
+    source: ['tokens/**/*.json'],
+    platforms: {
+      css: {
+        transformGroup: 'css',
+        buildPath: 'dist/',
+        files: [{ destination: 'vars.css', format: 'css/variables' }],
+      },
+      // Shells out to a native toolchain, so it is worth a minute of a real
+      // build and not worth a second of every rebuild.
+      ...(command === 'build' && !watch ? { ios: iosPlatform(mode) } : {}),
+    },
+  }),
+})
+```
+
+`command` is `'serve'` only under Vite's dev server; every other target builds.
+`mode` is Vite's or webpack's own, and follows `command` on rollup and rolldown,
+which have no such concept. `watch` is read from the host rather than inferred
+from `command`, because `rollup --watch` both watches and builds. The full
+contract is [`StyleDictionaryConfigContext`](#options-reference).
+
+A function taking no arguments stays valid — TypeScript accepts one of fewer
+parameters and JavaScript ignores the extra argument — so the example below
+needs no change.
+
 ```typescript
 // Named `styleDictionaryPlugin` here to avoid colliding with the `StyleDictionary`
 // class imported from the `style-dictionary` package itself, below.
@@ -252,12 +315,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
@@ -355,6 +484,41 @@ A compile that fails is reported at every level, including `'silent'`, which is
 why there is no `'error'`. `log.warnings` is never touched: if your
 configuration turns a warning into a thrown build, that stays your decision.
 
+### Where the messages go
+
+Through your bundler, not straight to the console, and each one takes them its
+own way:
+
+| Target             | Progress lines           | A failed compile                   |
+| ------------------ | ------------------------ | ---------------------------------- |
+| 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` |
+| 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.
+
+**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
+make. The same reasoning puts webpack's report in `compilation.warnings` rather
+than `compilation.errors`, so `failOnError: false` really does leave the build
+passing.
+
+**Your bundler's own log level applies.** `vite --logLevel silent` silences
+Vite's logger, and the plugin's lines are Vite's logger's now, so they go too.
+Nothing is lost by it that matters: `failOnError` decides whether a broken token
+set stops the build, and it decides that whether or not anything was printed.
+
+Colour follows the usual conventions, which it previously ignored entirely: no
+escapes when `NO_COLOR` is set, or when the stream is not a terminal, or under
+`TERM=dumb`; escapes when `FORCE_COLOR` is set to anything but `0`, including on
+a non-terminal, which is what that variable is for. `NO_COLOR` wins over
+`FORCE_COLOR`. stdout and stderr are decided separately, because they are
+redirected separately.
+
 ## Failing the Build
 
 A token compile that fails stops the build. `vite build`, `rollup` and `webpack`
@@ -373,17 +537,81 @@ StyleDictionary({
 })
 ```
 
-A failure is always reported, whatever `failOnError` and `silent` are set to.
+**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.
+
+Under Vite's dev server it is reported to the browser as well. A failed rebuild
+is pushed to Vite's error overlay, naming this plugin and carrying Style
+Dictionary's message, and the overlay is dismissed by the next rebuild that
+succeeds — so a page left rendering the last good token file says so instead of
+looking current. Set `errorOverlay: false` to keep the failure in the terminal
+only.
+
+`failOnError` and `errorOverlay` answer different questions and do not interact:
+the first decides whether the host stops, the second whether the browser is
+told. The dev server's default is not to stop, which is exactly when the overlay
+is the only thing that can report the failure.
+
+## Build Hooks
+
+Three optional callbacks, for work that has to happen around a compile rather
+than inside one — formatting the generated files, type-checking them, telling
+something else they have landed.
+
+```typescript
+StyleDictionary({
+  config: 'sd.config.json',
+  onBuildStart: () => console.log('compiling tokens'),
+  onBuildEnd: async (files, durationMs) => {
+    console.log(`wrote ${files.length} files in ${durationMs}ms`)
+    await formatGeneratedFiles(files)
+  },
+  onBuildError: (error) => notifySomething(error),
+})
+```
+
+`files` holds the absolute, platform-native path of every file the build
+declares, sorted. It is what the build declares rather than what it happened to
+write this time: a configuration skipped because its output was already current
+contributes its destinations too, so a post-processing step still sees the whole
+set on a rebuild that changed one file.
+
+A rebuild is a build, so all three fire again on every watch-triggered one.
+
+**A hook cannot fail the build that called it.** The return value is not
+awaited, so nothing waits for post-processing; a hook that throws is reported
+and the build stands, and a promise that rejects is caught and reported rather
+than reaching the host as an unhandled rejection — which would otherwise take a
+dev server down from inside a step meant to reformat a file.
+
+`onBuildError` fires whatever `failOnError` is set to, and before that option
+decides whether to rethrow. The two answer different questions: one is whether
+the host stops, the other is that a build went wrong.
 
 ## Public API
 
-Small on purpose. Four bundler entry points, one root entry, and one type.
+Small on purpose. Four 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.                                         |
 
 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
@@ -403,7 +631,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).
@@ -415,12 +643,72 @@ const plugin = styleDictionary.rollup({ config: 'sd.config.json' })
  * build (e.g. `tsdown`/`rolldown build` without `--watch`) only builds once, in
  * `buildStart`.
  *
+ * Everything the plugin says goes through the host rather than to the console:
+ * Vite's `config.logger`, the plugin context under rollup and rolldown, and
+ * `compilation.warnings` under webpack, which is what puts a failed compile in
+ * `stats.toJson()`. A failure is reported on the warning channel and never the
+ * error one — rollup's `this.error` aborts the bundle, and that decision is
+ * `failOnError`'s alone. Where no host offers a channel the console is used,
+ * with colour gated on `NO_COLOR`, `FORCE_COLOR` and whether the stream is a
+ * terminal.
+ *
+ * The three `onBuild*` hooks are called synchronously and their return value
+ * is not awaited, so a build never waits for one. A hook may still be written
+ * `async`: a promise it returns is left to run on its own, and a rejection is
+ * caught and reported rather than reaching the host as an unhandled one. A
+ * hook that throws is reported and does not fail the build that called it.
+ *
+ * They return `Promise<void> | void` rather than `void` for that reason. Both
+ * accept an `async` hook as far as the compiler is concerned, but `void` alone
+ * makes one a `no-misused-promises` error under the type-aware lint rules a
+ * consumer is likely to be running — for a hook this documents as supported.
+ *
  * Rolldown's watch mode is the exception, and it is not about glob patterns.
  * `addWatchFile` is accepted either way, but what happens next differs by
  * platform — on macOS a file registered through it is watched by nothing, while
  * on a Linux runner the same edit reaches a rebuild. Do not rely on a token
  * edit triggering a rebuild there.
  */
+/**
+ * What the host is doing, handed to the function form of `config` so it can
+ * decide what to build.
+ *
+ * Only Vite reports all three. Where a host does not say, the value is
+ * derived rather than guessed at, and each field below says how.
+ */
+export interface StyleDictionaryConfigContext {
+  /**
+   * Whether the host is serving or building.
+   *
+   * `'serve'` comes from Vite's own `config.command` and is the dev server.
+   * Every other target builds, so it is `'build'` there — rollup, rolldown and
+   * webpack have no serving mode of their own to report.
+   */
+  command: 'build' | 'serve'
+
+  /**
+   * The host's mode, as it names it.
+   *
+   * Vite reports its `config.mode` — `'development'` serving,
+   * `'production'` building, or whatever `--mode` named. webpack reports its
+   * `mode` option. rollup and rolldown have no such concept, so the value
+   * follows `command`: `'development'` when serving, `'production'` when
+   * building.
+   */
+  mode: string
+
+  /**
+   * Whether the host will keep rebuilding.
+   *
+   * `true` under Vite's dev server, `rollup --watch`, `rolldown.watch()` and
+   * `webpack --watch`; `false` for a one-shot build. It is read from the
+   * host — the plugin context's `meta.watchMode` on the three rollup-shaped
+   * targets, and `compiler.watchMode` on webpack — rather than inferred from
+   * `command`, because `rollup --watch` both watches and builds.
+   */
+  watch: boolean
+}
+
 export interface UnpluginStyleDictionaryOptions {
   /**
    * Whether a configuration whose output is already up to date may skip its
@@ -462,18 +750,64 @@ export interface UnpluginStyleDictionaryOptions {
    * - A function that returns a config or array of configs (or resolves to them).
    *   Useful for calling `StyleDictionary.registerFormat()` (or other `register*`
    *   methods) before returning a config that references the custom format by name.
+   *   It is handed a `StyleDictionaryConfigContext` describing what the host is
+   *   doing, so an expensive platform can be built only when it is wanted —
+   *   skipped under the dev server, built by `vite build`. A function taking no
+   *   arguments stays valid: TypeScript accepts one of fewer parameters, and
+   *   JavaScript ignores the extra argument.
    *
    * 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?:
-    | (() => Config | Config[] | Promise<Config | Config[]>)
+    | ((
+        context: StyleDictionaryConfigContext,
+      ) => Config | Config[] | Promise<Config | Config[]>)
     | Config
     | Config[]
+    | false
     | string
     | string[]
 
+  /**
+   * Whether a failed rebuild is pushed to Vite's error overlay.
+   *
+   * A rebuild that fails under the dev server used to reach the browser
+   * nowhere: the page went on rendering the last good generated file, and the
+   * only trace was one red terminal line the developer may not have been
+   * looking at. With this on, the failure is sent to the page as an error
+   * frame naming this plugin, and the overlay is dismissed on the next
+   * rebuild that succeeds.
+   *
+   * This is Vite's overlay, so it does nothing on the other three targets,
+   * and nothing under `vite build` — there is no page to draw on.
+   *
+   * It is not `failOnError`'s job, and the two are independent. `failOnError`
+   * decides whether the host stops; this decides whether the browser is told.
+   * A dev server deliberately keeps serving through a failed rebuild, which is
+   * precisely the case where the overlay is the only thing that can say so.
+   *
+   * A failure Style Dictionary raises before this plugin can catch it — a
+   * token file that is not valid JSON, which rejects out of band — reaches
+   * neither the overlay nor this option.
+   *
+   * @default true
+   */
+  errorOverlay?: boolean
+
   /**
    * Whether a compile that fails should throw rather than only be reported.
    *
@@ -513,11 +847,101 @@ export interface UnpluginStyleDictionaryOptions {
    * A compile that fails is reported at every level, so there is no
    * `'error'`: `'silent'` is the quietest and still reports a failure.
    *
+   * This option governs what the plugin says, not where it goes. The messages
+   * are handed to the host — Vite's `config.logger`, the rollup and rolldown
+   * plugin context, webpack's `compilation` — so a host silenced by its own
+   * log level suppresses them after this option has let them through. A
+   * failure still stops the build whenever `failOnError` says it should,
+   * printed or not.
+   *
    * @default undefined, which prints the plugin's own lines and leaves the
    * configuration's `log.verbosity` alone
    */
   logLevel?: 'info' | 'silent' | 'verbose' | 'warn'
 
+  /**
+   * Called once a build has finished, with every file it declares and how long
+   * it took in milliseconds.
+   *
+   * The paths are absolute and platform-native, sorted so two runs of the same
+   * configuration hand back the same order. They are what the build declares
+   * rather than what it wrote this time: a configuration skipped by `cache`
+   * contributes its destinations too, because they are on disk and current,
+   * and a post-processing step that ignored them would leave half the output
+   * untouched on a rebuild that changed one file.
+   *
+   * This is where formatting the generated files, type-checking them, or
+   * telling something else they have landed belongs.
+   *
+   * @default undefined
+   */
+  onBuildEnd?: (files: string[], durationMs: number) => Promise<void> | void
+
+  /**
+   * Called when a build fails, with whatever was thrown.
+   *
+   * It fires whatever `failOnError` is set to, and before that option decides
+   * whether to rethrow — the two answer different questions, and under a dev
+   * server the default is not to throw at all.
+   *
+   * The failure is reported to the console either way, so this is for reacting
+   * to one rather than for noticing it.
+   *
+   * @default undefined
+   */
+  onBuildError?: (error: unknown) => Promise<void> | void
+
+  /**
+   * Called before a build begins, once per build.
+   *
+   * A watch-triggered rebuild is a build, so this fires again for each one.
+   *
+   * @default undefined
+   */
+  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.
    *
@@ -581,7 +1005,7 @@ export interface UnpluginStyleDictionaryOptions {
    */
   watch?: string | string[]
 }
-```
+````
 
 ## Migrating from `vite-plugin-style-dictionary`
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { UnpluginStyleDictionaryOptions } from "./types.js";
+import { StyleDictionaryConfigContext, UnpluginStyleDictionaryOptions } from "./types.js";
 //#region src/index.d.ts
 export declare const unplugin: import("unplugin").UnpluginInstance<UnpluginStyleDictionaryOptions | undefined, false>;
 //#endregion
-export { type UnpluginStyleDictionaryOptions, unplugin as default };
+export { type StyleDictionaryConfigContext, type UnpluginStyleDictionaryOptions, unplugin as default };
 //# sourceMappingURL=index.d.ts.map