feat!: tailwindcss-patch 8.x

Author: sonofmagic

.changeset/refactor-tailwindcss-patch.md

@@ -0,0 +1,5 @@
+---
+'tailwindcss-patch': major
+---
+
+refactor!: redesign the patcher architecture, CLI surface, and documentation while adding Tailwind CSS v4 extraction support. Legacy APIs are wrapped for compatibility but consumers should migrate to the new entry points.

packages/tailwindcss-patch/CHANGELOG.md

@@ -1,5 +1,12 @@
 # tailwindcss-patch
 
+## Unreleased
+
+- refactor: rebuild around the new `TailwindcssPatcher` API, explicit module boundaries (`api/`, `patching/`, `runtime/`, `options/`, `extraction/`).
+- feat: add Tailwind CSS v4 class discovery plus configurable output formats (`json` or newline delimited).
+- feat: expose helpers such as `CacheStore`, `normalizeOptions`, and v4 candidate scanners as public exports.
+- docs: add `MIGRATION.md` and refresh both README variants to describe the new workflow and CLI flags.
+
 ## 7.1.6
 
 ### Patch Changes

packages/tailwindcss-patch/MIGRATION.md

@@ -0,0 +1,123 @@
+# Migration Guide
+
+This document describes the changes introduced by the full refactor of `tailwindcss-patch`. It helps teams upgrading from the 7.x line (or earlier) to the new architecture.
+
+> TL;DR — the public API now revolves around the `TailwindcssPatcher` class, helpers live in explicit folders, and the CLI exposes clearer options. Legacy configuration objects are still accepted, but adopting the new structure unlocks additional features.
+
+## 1. Package layout
+
+| Before | After |
+| --- | --- |
+| `src/core/**` mix of cache, patch and runtime helpers | Dedicated folders: `api/`, `cache/`, `patching/`, `runtime/`, `options/`, `extraction/` |
+| `CacheManager`, `InternalPatchOptions`, ad-hoc exports | `CacheStore`, `normalizeOptions`, typed helpers with explicit imports |
+| `processTailwindcss` | `runTailwindBuild` in `runtime/process-tailwindcss.ts` |
+
+Imports such as `@/core/patcher` or `@/core/cache` must be updated. Use the new entry-points:
+
+```ts
+import { TailwindcssPatcher } from 'tailwindcss-patch'
+import { CacheStore } from 'tailwindcss-patch/cache/store'
+import { applyTailwindPatches } from 'tailwindcss-patch/patching/patch-runner'
+```
+
+## 2. TailwindcssPatcher options
+
+### Previous shape
+
+```ts
+new TailwindcssPatcher({
+  cache: { dir: '.cache', file: 'classes.json' },
+  patch: {
+    overwrite: true,
+    output: { filename: '.tw-patch/tw-class-list.json', loose: true },
+    tailwindcss: { version: 3, v3: { cwd, config } },
+    applyPatches: { extendLengthUnits: true },
+  },
+})
+```
+
+### New shape
+
+```ts
+new TailwindcssPatcher({
+  overwrite: true,
+  cache: {
+    enabled: true,
+    dir: '.tw-patch/cache',
+    strategy: 'merge',
+  },
+  output: {
+    file: '.tw-patch/tw-class-list.json',
+    format: 'json',
+    removeUniversalSelector: true,
+  },
+  features: {
+    exposeContext: { refProperty: 'runtimeContexts' },
+    extendLengthUnits: { units: ['rpx'] },
+  },
+  tailwind: {
+    version: 4,
+    v4: {
+      base: './src',
+      cssEntries: ['dist/tailwind.css'],
+    },
+  },
+})
+```
+
+Both shapes are accepted. When the constructor detects `patch`/`cache` keys it automatically converts them via `fromLegacyOptions()`. This allows step-by-step migrations.
+
+## 3. CLI changes
+
+- `tw-patch install` still applies the runtime patch, but logging and error handling were refreshed.
+- `tw-patch extract` gained new flags (`--output`, `--format`, `--no-write`, `--css`).
+- Commands resolve configuration from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Existing configuration files continue to work without changes.
+
+## 4. Cache handling
+
+`CacheManager` has been replaced by `CacheStore`:
+
+```ts
+const cache = new CacheStore(normalized.cache)
+await cache.write(new Set(['text-lg']))
+const values = await cache.read()
+```
+
+This ensures consistent async behaviour and reliable error recovery (invalid JSON files are removed automatically).
+
+## 5. Exported helpers
+
+- Runtime context access now lives in `runtime/context-registry.ts` (`loadRuntimeContexts`).
+- Tailwind v4 candidate extraction moved to `extraction/candidate-extractor.ts`.
+- Custom unit support is available from `patching/operations/extend-length-units.ts`.
+
+Update imports accordingly when consuming these helpers directly.
+
+## 6. Configuration advice
+
+`defineConfig` from `tailwindcss-patch` (provided by `@tailwindcss-mangle/config`) still emits the legacy `patch` object. All new fields—`output.format`, extended `tailwindcss.v4` options, `applyPatches.extendLengthUnits` objects—are handled transparently. You may migrate gradually by adding the new keys into the existing `patch` block.
+
+If you want the new structure inside application code, prefer creating the patcher manually and pass the modern object as demonstrated above.
+
+## 7. Feature highlights
+
+- Tailwind v4 is supported without monkey patching. Provide CSS entries and content sources to `tailwind.v4` and call `extract()`.
+- Custom length units patching (`extendLengthUnits`) now supports Tailwind v3 and v4 with a single option object.
+- Filters are composed with the `output.removeUniversalSelector` flag so `'*'` can be kept when desired.
+
+## 8. Removal summary
+
+- The entire `src/core/**` directory was removed. Update imports to their new locations.
+- `defaults.ts`, `InternalPatchOptions`, and related helpers were removed.
+- Old tests referencing `CacheManager` or `processTailwindcss` no longer apply.
+
+## 9. Checklist for upgrading projects
+
+1. Update the dependency to the latest version of `tailwindcss-patch`.
+2. Review custom imports from `tailwindcss-patch/core/*` and switch to the new module paths.
+3. If you instantiate the patcher manually, adopt the new options object (or keep legacy options temporarily).
+4. Refresh CLI usage in scripts (e.g. add `--output` or `--no-write` where appropriate).
+5. For Tailwind v4 projects, configure `tailwind.v4.cssEntries` and `sources` so that `extract()` can discover candidates.
+6. Run your extraction workflow and ensure the generated class list matches expectations.
+
+For any regressions or gaps discovered during migration, please open an issue with reproduction details so we can iterate quickly.

packages/tailwindcss-patch/README-cn.md

@@ -1,116 +1,137 @@
-# 使用 `tailwindcss-patch@2` 来提取你的类名吧
+# tailwindcss-patch
 
-- [使用 `tailwindcss-patch@2` 来提取你的类名吧](#使用-tailwindcss-patch2-来提取你的类名吧)
-  - [安装](#安装)
-  - [使用方式](#使用方式)
-    - [命令行 Cli](#命令行-cli)
-      - [开始提取吧](#开始提取吧)
-    - [Nodejs API 的方式来使用](#nodejs-api-的方式来使用)
-  - [配置](#配置)
-    - [初始化](#初始化)
-  - [What's next?](#whats-next)
+重新设计的 Tailwind CSS 补丁工具，用于导出运行时上下文、扫描 v4 的类候选、并在同一个入口管理缓存与输出。新的架构提供更清晰的配置体验，同时完全兼容旧版配置文件。
 
-`tailwindcss-patch` 是一个 `tailwindcss` 生态的扩展项目。也是 [`tailwindcss-mangle`](https://github.com/sonofmagic/tailwindcss-mangle) 项目重要的组成部分。
-
-最近我发布了 `tailwindcss-patch` 的 `2.x` 版本，主要添加了一个配置文件读取和工具类名提取额功能。
-
-让我们来看看怎么使用它吧。
+- 自动为 Tailwind v2/v3 打补丁，暴露运行时上下文，不再手动修改源码。
+- 针对 Tailwind v4，通过扫描 CSS 和内容源生成完整类名清单。
+- 支持写入 JSON 或纯文本文件，也可以仅在内存中返回结果，方便集成到自定义流程。
+- 集中式配置：缓存策略、过滤器、自定义长度单位都可以在一个对象里完成。
 
 ## 安装
 
-选择你喜欢的包管理器
-
-```sh
-<yarn|npm|pnpm> add -D tailwindcss-patch
-```
-
-1. 给 `tailwindcss` 打补丁
-
-```sh
-npx tw-patch install
+```bash
+pnpm add -D tailwindcss-patch
+pnpm dlx tw-patch install
 ```
 
-1. 在 `npm` 的 `prepare` `hook` 里加入指令
-
-`package.json`
+为了在安装依赖时自动保持补丁，可添加 `prepare` 脚本：
 
 ```json
 {
-  /* ... */
   "scripts": {
     "prepare": "tw-patch install"
   }
 }
 ```
 
-## 使用方式
+## CLI 使用
 
-### 命令行 Cli
+在项目根目录通过 `tw-patch`（或 `tailwindcss-patch`）运行命令：
 
-#### 开始提取吧
+```bash
+# 为当前安装的 Tailwind 应用补丁
+pnpm dlx tw-patch install
 
-```sh
-npx tw-patch extract
+# 生成类名清单到配置的输出文件
+pnpm dlx tw-patch extract
 ```
 
-默认情况下，执行成功后会有一个 `json` 文件 `.tw-patch/tw-class-list.json` 在你的项目中出现。
-
-当然，你可以通过配置文件 `tailwindcss-mangle.config.ts` 来自定义这个行为。
+### `extract` 常用参数
 
-### Nodejs API 的方式来使用
+| 参数 | 说明 |
+| --- | --- |
+| `--cwd <dir>` | 指定读取配置的工作目录。 |
+| `--output <file>` | 覆盖输出文件路径。 |
+| `--format <json|lines>` | 切换 JSON（默认）或换行分隔的纯文本。 |
+| `--css <file>` | 使用 Tailwind v4 时指定 CSS 入口文件。 |
+| `--no-write` | 仅返回结果，不落盘。 |
 
-```js
-import { TailwindcssPatcher } from 'tailwindcss-patch'
+CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`。旧配置仍可使用，详情请参考 [迁移指南](./MIGRATION.md)。
 
-const twPatcher = new TailwindcssPatcher(/* options */)
-// do patch
-twPatcher.patch()
-// get all contexts at runtime
-twPatcher.getContexts()
-// get all class generated by tailwindcss utilities
-twPatcher.getClassSet()
-```
+## 编程接口
 
-## 配置
+```ts
+import { TailwindcssPatcher } from 'tailwindcss-patch'
 
-### 初始化
+const patcher = new TailwindcssPatcher({
+  overwrite: true,
+  cache: {
+    enabled: true,
+    dir: '.tw-patch/cache',
+    strategy: 'merge',
+  },
+  output: {
+    file: '.tw-patch/tw-class-list.json',
+    format: 'json',
+  },
+  features: {
+    exposeContext: { refProperty: 'runtimeContexts' },
+    extendLengthUnits: {
+      units: ['rpx'],
+    },
+  },
+  tailwind: {
+    version: 4,
+    v4: {
+      base: './src',
+      cssEntries: ['dist/tailwind.css'],
+    },
+  },
+})
 
-```sh
-npx tw-patch init
+await patcher.patch()
+const { classList, filename } = await patcher.extract()
 ```
 
-这样在你的当前的 `cwd` 中就会出现一个 `tailwindcss-mangle.config.ts` 文件:
+构造函数既可以接收上述新版对象，也可以传入旧的 `patch`/`cache` 结构；内部会自动完成兼容转换。
 
-```ts
-import { defineConfig } from 'tailwindcss-patch'
+### 可复用工具
 
-export default defineConfig({})
-```
+- `normalizeOptions`：归一化用户输入并应用默认值。
+- `CacheStore`：读写类名缓存，支持合并或覆盖策略。
+- `extractValidCandidates`：利用 Tailwind Oxide 扫描 v4 CSS 与内容源。
+- `runTailwindBuild`：在 v2/v3 项目中运行 Tailwind PostCSS 插件以预热上下文。
 
-你可以通过 `patch` 字段来自定义它的行为:
+以上工具均由包入口导出，便于集成到自定义流程。
+
+## 配置示例
 
 ```ts
+// tailwindcss-patch.config.ts
 import { defineConfig } from 'tailwindcss-patch'
 
 export default defineConfig({
   patch: {
     output: {
-      filename: 'xxx.json',
-      loose: true,
-      removeUniversalSelector: true
+      filename: '.tw-patch/tw-class-list.json',
+      removeUniversalSelector: true,
+      format: 'json',
     },
     tailwindcss: {
-      config: 'path/to/your-tailwind.config.js',
-      cwd: 'project/cwd'
-    }
-  }
+      version: 4,
+      v4: {
+        cssEntries: ['dist/tailwind.css'],
+        sources: [
+          { base: 'src', pattern: '**/*.{html,tsx}', negated: false },
+        ],
+      },
+    },
+    applyPatches: {
+      exportContext: true,
+      extendLengthUnits: {
+        units: ['rpx'],
+      },
+    },
+  },
 })
 ```
 
-## What's next?
+虽然 `defineConfig` 仍然暴露旧的字段名，但所有新增字段都会被自动识别并归一化。
+
+## 迁移
 
-目前我只是提取了所有的工具类，实际上可以获取 `tailwindcss` 的上下文进行分析。你可以给我提 `issue` 或者 `pr` 的方式，来为这个项目添加更多的功能，
+从 7.x 或更早版本升级时，请阅读 [MIGRATION.md](./MIGRATION.md) 获取模块调整和 API 变化说明。
 
-当然，提取之后这个 `json` 当然也不是只是给你看看的。你可以对它进行一些分析，而我是把它作为我 `tailwindcss-mangle` 的数据文件来使用的。
+## License
 
-`tailwindcss-mangle` 本身是一个混淆工具，用来混淆 `tailwindcss` 生成的工具类，具体的使用方式就看下篇文章吧。
+MIT © ice breaker