tailwindcss-patch 8.2.4 → 8.4.0

package/README.md

@@ -39,6 +39,60 @@ pnpm dlx tw-patch extract
 pnpm dlx tw-patch tokens --format lines
 ```
 
+### Embed into another CLI
+
+Reuse the same commands inside your own `cac` program:
+
+```ts
+import cac from 'cac'
+import { mountTailwindcssPatchCommands } from 'tailwindcss-patch'
+
+const cli = cac('my-tool')
+mountTailwindcssPatchCommands(cli, {
+  commandPrefix: 'tw:', // optional
+  commands: ['install', 'tokens'], // mount a subset if needed (defaults to all)
+  commandOptions: {
+    install: { name: 'patch-install', aliases: ['tw-install'] }, // override names/aliases
+  },
+})
+cli.help()
+cli.parse()
+```
+
+#### Custom command hooks
+
+Hosts can override per-command lifecycles by supplying `commandHandlers`. Each handler receives a context object (with the resolved `cwd`, parsed `args`, memoized `loadConfig`/`createPatcher` helpers, and the shared `logger`) plus a `next()` callback that runs the built-in action.
+
+```ts
+mountTailwindcssPatchCommands(cli, {
+  commandHandlers: {
+    install: async (ctx) => {
+      const patcher = await ctx.createPatcher()
+      await clearTailwindcssPatcherCache(ctx.cwd)
+      await patcher.patch()
+      await saveCliPatchTargetRecord({ cwd: ctx.cwd })
+    },
+    extract: async (ctx, next) => {
+      const result = await next() // run the default extract implementation
+      ctx.logger.success(`[host] wrote ${result.classList.length} classes`)
+      return result
+    },
+  },
+  commandOptions: {
+    extract: {
+      description: 'Localised extract command',
+      appendDefaultOptions: false,
+      optionDefs: [
+        { flags: '--entry <file>', description: 'Tailwind CSS entry file' },
+        { flags: '--preview', description: 'Print a preview instead of writing' },
+      ],
+    },
+  },
+})
+```
+
+Skip `next()` to fully replace a command (e.g. custom `init` or cache clearing before `install`). Calling `next()` returns the default result—`ExtractResult`, `TailwindTokenReport`, etc.—so hosts can log metadata or feed it into their own telemetry without re-implementing the commands.
+
 ### Extract options
 
 | Flag                     | Description                                                      |
@@ -53,13 +107,13 @@ The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Le
 
 ### Token report options
 
-| Flag                     | Description                                                                 |
-| ------------------------ | --------------------------------------------------------------------------- |
-| `--cwd <dir>`            | Use a different working directory when loading configuration.               |
-| `--output <file>`        | Override the token report target file (defaults to `.tw-patch/tw-token-report.json`). |
+| Flag                                   | Description                                                                               |
+| -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `--cwd <dir>`                          | Use a different working directory when loading configuration.                             |
+| `--output <file>`                      | Override the token report target file (defaults to `.tw-patch/tw-token-report.json`).     |
 | `--format <json\|lines\|grouped-json>` | Choose between a JSON payload (default), newline summaries, or JSON grouped by file path. |
-| `--group-key <relative\|absolute>` | Control grouped-json keys (defaults to relative paths). |
-| `--no-write`             | Skip writing to disk and only print a preview.                              |
+| `--group-key <relative\|absolute>`     | Control grouped-json keys (defaults to relative paths).                                   |
+| `--no-write`                           | Skip writing to disk and only print a preview.                                            |
 
 ## Programmatic API