feat(tailwindcss-patch): simplify options and deprecate legacy fields

Author: sonofmagic

.changeset/late-snakes-applaud.md

@@ -0,0 +1,14 @@
+---
+"tailwindcss-patch": minor
+---
+
+Redesign `TailwindcssPatcher` options to a simpler, migration-friendly shape while preserving backward compatibility.
+
+- add modern constructor fields:
+  - `projectRoot` (replaces `cwd`)
+  - `tailwindcss` (replaces `tailwind`)
+  - `apply` (replaces `overwrite` + `features`)
+  - `extract` (replaces `output`)
+- keep existing fields working, but mark legacy fields with `@deprecated` JSDoc and document planned removal in the next major release
+- make option normalization prefer modern fields when both modern and legacy values are provided
+- update legacy/unified config conversion and CLI overrides to emit the modern option shape

packages/tailwindcss-patch/MIGRATION.md

@@ -40,22 +40,24 @@ const patcher = new TailwindcssPatcher({
 
 ```ts
 const patcher = new TailwindcssPatcher({
-  overwrite: true,
+  projectRoot: process.cwd(),
   cache: {
     enabled: true,
     dir: '.tw-patch/cache',
     strategy: 'merge',
   },
-  output: {
+  extract: {
+    write: true,
     file: '.tw-patch/tw-class-list.json',
     format: 'json',
     removeUniversalSelector: true,
   },
-  features: {
+  apply: {
+    overwrite: true,
     exposeContext: { refProperty: 'runtimeContexts' },
     extendLengthUnits: { units: ['rpx'] },
   },
-  tailwind: {
+  tailwindcss: {
     version: 4,
     v4: {
       base: './src',
@@ -67,6 +69,15 @@ const patcher = new TailwindcssPatcher({
 
 Both shapes are accepted. When the constructor detects `patch`/`cache` keys it automatically converts them via `fromLegacyOptions()`. This allows step-by-step migrations.
 
+Deprecated fields (planned removal in the next major): `cwd`, `overwrite`, `tailwind`, `features`, `output`.
+
+Migration mapping:
+- `cwd` -> `projectRoot`
+- `overwrite` -> `apply.overwrite`
+- `tailwind` -> `tailwindcss`
+- `features` -> `apply`
+- `output` -> `extract`
+
 ## 3. CLI changes
 
 - `tw-patch install` still applies the runtime patch, but logging and error handling were refreshed.
@@ -104,15 +115,15 @@ 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.
+`defineConfig` from `tailwindcss-patch` (provided by `@tailwindcss-mangle/config`) still emits the legacy `patch` object. The patcher normalizer maps it to the modern runtime shape (`tailwindcss`, `apply`, `extract`) automatically, so migration can be gradual.
 
 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()`.
+- Tailwind v4 is supported without monkey patching. Provide CSS entries and content sources to `tailwindcss.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.
+- Filters are composed with the `extract.removeUniversalSelector` flag so `'*'` can be kept when desired.
 
 ## 8. Removal summary
 
@@ -126,7 +137,7 @@ If you want the new structure inside application code, prefer creating the 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.
+5. For Tailwind v4 projects, configure `tailwindcss.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

@@ -67,24 +67,26 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 import { TailwindcssPatcher } from 'tailwindcss-patch'
 
 const patcher = new TailwindcssPatcher({
-  overwrite: true,
+  projectRoot: process.cwd(),
   cache: {
     enabled: true,
     dir: '.tw-patch/cache',
     strategy: 'merge',
     driver: 'file',
   },
-  output: {
+  extract: {
+    write: true,
     file: '.tw-patch/tw-class-list.json',
     format: 'json',
   },
-  features: {
+  apply: {
+    overwrite: true,
     exposeContext: { refProperty: 'runtimeContexts' },
     extendLengthUnits: {
       units: ['rpx'],
     },
   },
-  tailwind: {
+  tailwindcss: {
     version: 4,
     v4: {
       base: './src',
@@ -103,7 +105,16 @@ console.log(groupedTokens['src/button.tsx'][0].rawCandidate)
 // await patcher.collectContentTokensByFile({ key: 'absolute', stripAbsolutePaths: false })
 ```
 
-构造函数既可以接收上述新版对象，也可以传入旧的 `patch`/`cache` 结构；内部会自动完成兼容转换。
+构造函数既可以接收上述新版对象，也可以传入旧结构；内部会自动完成兼容转换。
+
+已标记弃用（下一个大版本移除）的旧字段：`cwd`、`overwrite`、`tailwind`、`features`、`output`。
+
+字段迁移关系：
+- `cwd` -> `projectRoot`
+- `overwrite` -> `apply.overwrite`
+- `tailwind` -> `tailwindcss`
+- `features` -> `apply`
+- `output` -> `extract`
 
 当遇到文件权限受限等情况时，可通过 cache.driver 切换为默认的文件缓存、内存缓存（memory）或无操作模式（noop）。
 

packages/tailwindcss-patch/README.md

@@ -124,24 +124,26 @@ The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Le
 import { TailwindcssPatcher } from 'tailwindcss-patch'
 
 const patcher = new TailwindcssPatcher({
-  overwrite: true,
+  projectRoot: process.cwd(),
   cache: {
     enabled: true,
     dir: '.tw-patch/cache',
     strategy: 'merge',
     driver: 'file',
   },
-  output: {
+  extract: {
+    write: true,
     file: '.tw-patch/tw-class-list.json',
     format: 'json',
   },
-  features: {
+  apply: {
+    overwrite: true,
     exposeContext: { refProperty: 'runtimeContexts' },
     extendLengthUnits: {
       units: ['rpx'],
     },
   },
-  tailwind: {
+  tailwindcss: {
     version: 4,
     v4: {
       base: './src',
@@ -162,7 +164,16 @@ const patchStatus = await patcher.getPatchStatus()
 console.log(patchStatus.entries)
 ```
 
-The constructor accepts either the new object shown above or the historical `patch`/`cache` shape. Conversions happen internally so existing configs remain backwards compatible.
+The constructor accepts either the new object shown above or historical shapes. Conversions happen internally so existing configs remain backwards compatible.
+
+Deprecated fields kept temporarily (to be removed in the next major): `cwd`, `overwrite`, `tailwind`, `features`, `output`.
+
+Migration mapping:
+- `cwd` -> `projectRoot`
+- `overwrite` -> `apply.overwrite`
+- `tailwind` -> `tailwindcss`
+- `features` -> `apply`
+- `output` -> `extract`
 
 Use cache.driver to switch between the default file-backed cache, an in-memory cache (memory), or a no-op cache (noop) when filesystem permissions are restricted.
 

packages/tailwindcss-patch/src/cli/commands.ts

@@ -371,15 +371,15 @@ async function extractCommandDefaultHandler(ctx: TailwindcssPatchCommandContext<
   let hasOverrides = false
 
   if (args.output || args.format) {
-    overrides.output = {
+    overrides.extract = {
       ...(args.output === undefined ? {} : { file: args.output }),
       ...(args.format === undefined ? {} : { format: args.format }),
     }
     hasOverrides = true
   }
 
   if (args.css) {
-    overrides.tailwind = {
+    overrides.tailwindcss = {
       v4: {
         cssEntries: [args.css],
       },

packages/tailwindcss-patch/src/options/legacy.ts

@@ -94,14 +94,14 @@ export function fromLegacyOptions(options?: LegacyTailwindcssPatcherOptions): Ta
 
   const tailwindConfigPath = tailwindV3?.config ?? tailwindV2?.config
   const tailwindCwd = tailwindV3?.cwd ?? tailwindV2?.cwd ?? patch?.cwd
-  const normalizedOutput = output
+  const normalizedExtract = output
     ? {
         ...(output.filename === undefined ? {} : { file: output.filename }),
         pretty: output.loose ? 2 : false,
         ...(output.removeUniversalSelector === undefined ? {} : { removeUniversalSelector: output.removeUniversalSelector }),
       }
     : undefined
-  const normalizedTailwind = {
+  const normalizedTailwindcss = {
     ...(patch?.packageName === undefined ? {} : { packageName: patch.packageName }),
     ...(tailwindVersion === undefined ? {} : { version: tailwindVersion }),
     ...(patch?.resolve === undefined ? {} : { resolve: patch.resolve }),
@@ -119,18 +119,19 @@ export function fromLegacyOptions(options?: LegacyTailwindcssPatcherOptions): Ta
           enabled: options.cache.enabled ?? true,
         }
       : undefined
+  const normalizedApply = {
+    ...(patch?.overwrite === undefined ? {} : { overwrite: patch.overwrite }),
+    exposeContext: features.exposeContext,
+    extendLengthUnits: features.extendLengthUnits,
+  }
 
   return {
-    ...(patch?.cwd === undefined ? {} : { cwd: patch.cwd }),
-    ...(patch?.overwrite === undefined ? {} : { overwrite: patch.overwrite }),
+    ...(patch?.cwd === undefined ? {} : { projectRoot: patch.cwd }),
     ...(patch?.filter === undefined ? {} : { filter: patch.filter }),
     ...(normalizedCache === undefined ? {} : { cache: normalizedCache }),
-    ...(normalizedOutput === undefined ? {} : { output: normalizedOutput }),
-    tailwind: normalizedTailwind,
-    features: {
-      exposeContext: features.exposeContext,
-      extendLengthUnits: features.extendLengthUnits,
-    },
+    ...(normalizedExtract === undefined ? {} : { extract: normalizedExtract }),
+    ...(Object.keys(normalizedTailwindcss).length === 0 ? {} : { tailwindcss: normalizedTailwindcss }),
+    apply: normalizedApply,
   }
 }
 
@@ -151,14 +152,14 @@ export function fromUnifiedConfig(registry?: RegistryOptions): TailwindcssPatchO
     }
     return output.pretty
   })()
-  const normalizedOutput = output
+  const normalizedExtract = output
     ? {
         ...(output.file === undefined ? {} : { file: output.file }),
         ...(pretty === undefined ? {} : { pretty }),
         ...(output.stripUniversalSelector === undefined ? {} : { removeUniversalSelector: output.stripUniversalSelector }),
       }
     : undefined
-  const normalizedTailwind = tailwind
+  const normalizedTailwindcss = tailwind
     ? {
         ...(tailwind.version === undefined ? {} : { version: tailwind.version }),
         ...(tailwind.package === undefined ? {} : { packageName: tailwind.package }),
@@ -172,7 +173,7 @@ export function fromUnifiedConfig(registry?: RegistryOptions): TailwindcssPatchO
     : undefined
 
   return {
-    ...(normalizedOutput === undefined ? {} : { output: normalizedOutput }),
-    ...(normalizedTailwind === undefined ? {} : { tailwind: normalizedTailwind }),
+    ...(normalizedExtract === undefined ? {} : { extract: normalizedExtract }),
+    ...(normalizedTailwindcss === undefined ? {} : { tailwindcss: normalizedTailwindcss }),
   }
 }