feat(tailwindcss-patch): tighten public option types

Author: sonofmagic

.changeset/friendly-trainers-share.md

@@ -0,0 +1,6 @@
+---
+"tailwindcss-patch": minor
+"@tailwindcss-mangle/config": minor
+---
+
+Remove legacy public option type aliases from the v9 alpha line and keep only the modern option names such as `TailwindCssPatchOptions`, `TailwindCssOptions`, `TailwindV2V3Options`, and `TailwindV4Options`.

package.json

@@ -11,6 +11,7 @@
     "build": "turbo run build --filter=./packages/*",
     "dev": "pnpm -r run dev",
     "test": "turbo run test --filter=./packages/*",
+    "test:types": "turbo run test:types --filter=./packages/*",
     "check:boundaries": "node scripts/check-package-boundaries.mjs",
     "test:e2e": "pnpm run test:e2e:apps",
     "test:e2e:apps": "TWM_APPS_E2E=1 vitest run --config e2e/vitest.config.ts e2e/apps.e2e.test.ts",
@@ -113,6 +114,7 @@
     "tailwindcss": "catalog:tailwindcss3",
     "tailwindcss-patch": "workspace:*",
     "tailwindcss2": "catalog:tailwindcss2",
+    "tsd": "^0.33.0",
     "tsdown": "^0.21.2",
     "tslib": "^2.8.1",
     "tsup": "^8.5.1",

packages/config/src/types.ts

@@ -46,12 +46,12 @@ export interface TransformerOptions {
   preserve?: TransformerPreserveOptions
 }
 
-export interface TailwindLocatorOptions {
+export interface TailwindV2V3Options {
   cwd?: string
   config?: string
 }
 
-export interface TailwindNextOptions {
+export interface TailwindV4Options {
   sources?: SourceEntry[]
   base?: string
   css?: string
@@ -94,20 +94,20 @@ export interface RegistryCacheOptions {
   driver?: 'file' | 'memory' | 'noop'
 }
 
-export interface TailwindTargetOptions {
+export interface TailwindCssOptions {
   version?: 2 | 3 | 4
   packageName?: string
   resolve?: PackageResolvingOptions
-  v2?: TailwindLocatorOptions
-  v3?: TailwindLocatorOptions
-  v4?: TailwindNextOptions
+  v2?: TailwindV2V3Options
+  v3?: TailwindV2V3Options
+  v4?: TailwindV4Options
   cwd?: string
   config?: string
 }
 
 export interface RegistryOptions {
   projectRoot?: string
-  tailwindcss?: TailwindTargetOptions
+  tailwindcss?: TailwindCssOptions
   apply?: RegistryApplyOptions
   extract?: RegistryExtractOptions
   cache?: RegistryCacheOptions

packages/config/test/defaults.test.ts

@@ -3,7 +3,7 @@ import { omit } from 'lodash-es'
 import { getDefaultRegistryConfig, getDefaultTransformerConfig, getDefaultUserConfig } from '@/defaults'
 
 function omitCwdPath(o: any) {
-  return omit(o, ['registry.tailwind.cwd'])
+  return omit(o, ['registry.tailwindcss.cwd'])
 }
 
 function normaliseRegex(value: any): any {

packages/tailwindcss-patch/MIGRATION.md

@@ -69,6 +69,33 @@ const patcher = new TailwindcssPatcher({
 
 Legacy constructor aliases are no longer accepted in v9.
 
+### Type names
+
+The alpha line now only exposes the modern public option type names. Historical aliases were removed instead of being kept with `@deprecated`.
+
+Use these names in user code:
+
+- `TailwindCssPatchOptions`
+- `TailwindCssOptions`
+- `TailwindV2V3Options`
+- `TailwindV4Options`
+- `ApplyOptions`
+- `ExtractOptions`
+- `CacheOptions`
+- `ExposeContextOptions`
+- `ExtendLengthUnitsOptions`
+- `NormalizedTailwindCssPatchOptions`
+
+Removed type names:
+
+- `TailwindcssPatchOptions`
+- `NormalizedTailwindcssPatchOptions`
+- `TailwindLocatorOptions`
+- `TailwindNextOptions`
+- `TailwindTargetOptions`
+
+If your code imported the removed names, switch imports to the modern names before adopting the current alpha builds.
+
 Migration mapping:
 
 - `cwd` -> `projectRoot`

packages/tailwindcss-patch/README-cn.md

@@ -60,6 +60,25 @@ pnpm dlx tw-patch validate --report-file .tw-patch/migrate-report.json --json
 
 CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`。v9 仅接受现代 `registry` 结构；如果项目里仍有旧字段，请先执行 `tw-patch migrate`，详情见 [迁移指南](./MIGRATION.md)。
 
+### 公开类型名
+
+当前 alpha 只导出新的 options 类型名：
+
+```ts
+import type {
+  ApplyOptions,
+  CacheOptions,
+  ExtractOptions,
+  TailwindCssOptions,
+  TailwindCssPatchOptions,
+  TailwindV2V3Options,
+  TailwindV4Options,
+  NormalizedTailwindCssPatchOptions,
+} from 'tailwindcss-patch'
+```
+
+像 `TailwindcssPatchOptions`、`TailwindLocatorOptions`、`TailwindTargetOptions` 这样的旧别名已经不再导出。
+
 ### v9 升级步骤
 
 1. 先执行 `pnpm dlx tw-patch migrate --dry-run`，确认有哪些配置需要改写。

packages/tailwindcss-patch/README.md

@@ -117,6 +117,25 @@ Skip `next()` to fully replace a command (e.g. custom `init` or cache clearing b
 
 The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. v9 expects the modern `registry` shape; use `tw-patch migrate` before upgrading if your config still uses deprecated keys.
 
+### Public Type Names
+
+The current alpha exports the modern option type names only:
+
+```ts
+import type {
+  ApplyOptions,
+  CacheOptions,
+  ExtractOptions,
+  TailwindCssOptions,
+  TailwindCssPatchOptions,
+  TailwindV2V3Options,
+  TailwindV4Options,
+  NormalizedTailwindCssPatchOptions,
+} from 'tailwindcss-patch'
+```
+
+Older aliases such as `TailwindcssPatchOptions`, `TailwindLocatorOptions`, and `TailwindTargetOptions` are intentionally removed in the alpha line.
+
 ### v9 upgrade flow
 
 1. Run `pnpm dlx tw-patch migrate --dry-run` to preview required config rewrites.

packages/tailwindcss-patch/package.json

@@ -39,18 +39,23 @@
   "files": [
     "bin",
     "dist",
-    "schema"
+    "schema",
+    "src"
   ],
   "scripts": {
     "dev": "tsup --watch --sourcemap",
     "build": "tsup",
     "test": "vitest run",
+    "test:types": "pnpm build && tsd --typings dist/index.d.mts --files test-d/**/*.test-d.ts",
     "test:dev": "vitest",
     "bench:cold-start": "node --import tsx bench/cold-start.ts",
     "patch": "tsx dev/bin.ts install",
     "r0": "tsx dev/bin.ts extract",
     "r1": "tsx dev/bin.ts extract --css index.css"
   },
+  "tsd": {
+    "directory": "test-d"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",

packages/tailwindcss-patch/src/api/tailwindcss-patcher.ts

@@ -1,13 +1,13 @@
 import type { SourceEntry } from '@tailwindcss/oxide'
 import type { PackageInfo } from 'local-pkg'
-import type { NormalizedTailwindcssPatchOptions } from '../config'
+import type { NormalizedTailwindCssPatchOptions } from '../config'
 import type {
   CacheClearOptions,
   CacheClearResult,
   CacheContextMetadata,
   CacheReadMeta,
   ExtractResult,
-  TailwindcssPatchOptions,
+  TailwindCssPatchOptions,
   TailwindTokenByFileMap,
   TailwindTokenFileKey,
   TailwindTokenReport,
@@ -92,7 +92,7 @@ function resolveMajorVersionOrThrow(
 
 function createCollector(
   packageInfo: PackageInfo,
-  options: NormalizedTailwindcssPatchOptions,
+  options: NormalizedTailwindCssPatchOptions,
   majorVersion: TailwindMajorVersion,
   snapshotFactory: () => string,
 ): TailwindCollector {
@@ -104,7 +104,7 @@ function createCollector(
 }
 
 export class TailwindcssPatcher {
-  public readonly options: NormalizedTailwindcssPatchOptions
+  public readonly options: NormalizedTailwindCssPatchOptions
   public readonly packageInfo: PackageInfo
   public readonly majorVersion: TailwindMajorVersion
 
@@ -117,7 +117,7 @@ export class TailwindcssPatcher {
   private readonly collector: TailwindCollector
   private patchMemo: PatchMemo | undefined
 
-  constructor(options: TailwindcssPatchOptions = {}) {
+  constructor(options: TailwindCssPatchOptions = {}) {
     this.options = normalizeOptions(options)
     const packageInfo = getPackageInfoSync(
       this.options.tailwind.packageName,

packages/tailwindcss-patch/src/cache/context.ts

@@ -1,5 +1,5 @@
 import type { PackageInfo } from 'local-pkg'
-import type { NormalizedTailwindcssPatchOptions } from '../options/types'
+import type { NormalizedTailwindCssPatchOptions } from '../options/types'
 import type { CacheContextDescriptor, CacheContextMetadata } from './types'
 import { createHash } from 'node:crypto'
 import process from 'node:process'
@@ -49,7 +49,7 @@ function resolveFileMtimeMsSync(value: string | undefined): number | undefined {
 }
 
 function resolveTailwindConfigPath(
-  options: NormalizedTailwindcssPatchOptions,
+  options: NormalizedTailwindCssPatchOptions,
   majorVersion: 2 | 3 | 4,
 ): string | undefined {
   const tailwind = options.tailwind
@@ -114,7 +114,7 @@ function hash(input: string): string {
   return createHash('sha256').update(input).digest('hex')
 }
 
-function toFingerprintOptions(normalized: NormalizedTailwindcssPatchOptions) {
+function toFingerprintOptions(normalized: NormalizedTailwindCssPatchOptions) {
   return {
     overwrite: normalized.overwrite,
     output: {
@@ -136,7 +136,7 @@ function toFingerprintOptions(normalized: NormalizedTailwindcssPatchOptions) {
 }
 
 export function createCacheContextDescriptor(
-  options: NormalizedTailwindcssPatchOptions,
+  options: NormalizedTailwindCssPatchOptions,
   packageInfo: PackageInfo,
   majorVersion: 2 | 3 | 4,
 ): CacheContextDescriptor {