|
1 | | -# 待办事项 |
| 1 | +import { Callout } from 'nextra/components' |
| 2 | + |
| 3 | +# 3.Config |
| 4 | + |
| 5 | +The toolchain reads configuration through `@tailwindcss-mangle/config`. Both `tailwindcss-patch.config.ts` and the historic `tailwindcss-mangle.config.ts` are recognised, so you can migrate gradually without breaking existing projects. |
| 6 | + |
| 7 | +## Generate a starter file |
| 8 | + |
| 9 | +```sh npm2yarn |
| 10 | +npx tw-patch init |
| 11 | +``` |
| 12 | + |
| 13 | +This command creates a minimal config at the project root: |
| 14 | + |
| 15 | +```ts |
| 16 | +import { defineConfig } from 'tailwindcss-patch' |
| 17 | + |
| 18 | +export default defineConfig({}) |
| 19 | +``` |
| 20 | + |
| 21 | +<Callout type="info"> |
| 22 | +`defineConfig` provides typed completion, but the runtime accepts additional fields that map to the modern `TailwindcssPatcher` options. Unknown keys are forwarded during normalisation. |
| 23 | +</Callout> |
| 24 | + |
| 25 | +## Example configuration |
| 26 | + |
| 27 | +```ts |
| 28 | +import { defineConfig } from 'tailwindcss-patch' |
| 29 | + |
| 30 | +export default defineConfig({ |
| 31 | + patch: { |
| 32 | + output: { |
| 33 | + filename: '.tw-patch/tw-class-list.json', |
| 34 | + format: 'json', |
| 35 | + pretty: 2, |
| 36 | + removeUniversalSelector: true, |
| 37 | + }, |
| 38 | + tailwindcss: { |
| 39 | + version: 4, |
| 40 | + v4: { |
| 41 | + cssEntries: ['dist/tailwind.css'], |
| 42 | + sources: [ |
| 43 | + { base: 'src', pattern: '**/*.{astro,tsx,mdx}', negated: false }, |
| 44 | + ], |
| 45 | + }, |
| 46 | + }, |
| 47 | + applyPatches: { |
| 48 | + exportContext: true, |
| 49 | + extendLengthUnits: { |
| 50 | + units: ['rpx'], |
| 51 | + }, |
| 52 | + }, |
| 53 | + }, |
| 54 | + cache: { |
| 55 | + enabled: true, |
| 56 | + dir: '.tw-patch/cache', |
| 57 | + strategy: 'merge', |
| 58 | + }, |
| 59 | + mangle: { |
| 60 | + classListPath: '.tw-patch/tw-class-list.json', |
| 61 | + include: [ |
| 62 | + /\.(html|vue|tsx|jsx|mdx)$/, |
| 63 | + ], |
| 64 | + classGenerator: { |
| 65 | + classPrefix: 'tw-', |
| 66 | + reserveClassName: [/^theme-/], |
| 67 | + }, |
| 68 | + classMapOutput: { |
| 69 | + enable: false, |
| 70 | + filename: '.tw-patch/tw-map-list.json', |
| 71 | + loose: true, |
| 72 | + }, |
| 73 | + preserveFunction: ['twIgnore'], |
| 74 | + }, |
| 75 | +}) |
| 76 | +``` |
| 77 | + |
| 78 | +## Patch options |
| 79 | + |
| 80 | +The `patch` block keeps the legacy shape but is converted to the new `TailwindcssPatchOptions` internally. |
| 81 | + |
| 82 | +### `output` |
| 83 | + |
| 84 | +- `filename` – destination for the extracted inventory (default `.tw-patch/tw-class-list.json`). |
| 85 | +- `format` – either `json` or `lines`; the CLI uses JSON by default. |
| 86 | +- `pretty` – `false`, a boolean, or a number of spaces when writing JSON. |
| 87 | +- `removeUniversalSelector` – skip `*` from the generated list when `true`. |
| 88 | + |
| 89 | +### `tailwindcss` |
| 90 | + |
| 91 | +- `version` – optional hint (`2`, `3`, or `4`) when multiple versions are installed. |
| 92 | +- `v2` / `v3` – provide `cwd` and `config` when Tailwind lives in a workspace package. |
| 93 | +- `v4.cssEntries` – CSS entry files used by the Oxide scanner. Repeat for multi-bundle setups. |
| 94 | +- `v4.sources` – custom content sources for v4 projects (defaults to `**/*` under `base`). |
| 95 | + |
| 96 | +### `applyPatches` |
| 97 | + |
| 98 | +- `exportContext` – expose Tailwind contexts at runtime so the API can read them back later. |
| 99 | +- `extendLengthUnits` – customise the built-in length-unit patching; accepts booleans or an option object (`units`, `overwrite`, etc.). |
| 100 | + |
| 101 | +### `cache` and `overwrite` |
| 102 | + |
| 103 | +- `cache.enabled` – persist collected classes under `node_modules/.cache/tailwindcss-patch` (enabled by default). |
| 104 | +- `cache.dir` / `cache.file` – control where the cache set is stored. |
| 105 | +- `cache.strategy` – `merge` adds to the existing cache, `overwrite` replaces it on each extraction. |
| 106 | +- `overwrite` (top-level) – reapply Tailwind patches even if a patched version already exists. |
| 107 | + |
| 108 | +### `filter` |
| 109 | + |
| 110 | +Provide a function to skip classes during extraction. Return `false` to drop a class; all other return values keep it. |
| 111 | + |
| 112 | +## Mangle options |
| 113 | + |
| 114 | +The `mangle` block is read by both the core runtime and `unplugin-tailwindcss-mangle`. |
| 115 | + |
| 116 | +- `classListPath` – absolute or relative path to the extracted class list. |
| 117 | +- `include` / `exclude` – control which files the plugin scans; defaults cover HTML, frameworks, CSS, and MDX. |
| 118 | +- `mangleClassFilter` – override the class-level filter before the generator runs. |
| 119 | +- `classGenerator` – customise minified names via `classPrefix`, `reserveClassName`, `exclude`, or `customGenerate`. |
| 120 | +- `classMapOutput` – set to `true` to reuse config defaults, provide an object (`enable`, `filename`, `loose`) to emit JSON, or supply a callback for full control. |
| 121 | +- `preserveFunction` – list of helper names (e.g. `twIgnore`) that mark template literals as safe from mangling. |
| 122 | +- `disabled` – when `true`, skips rewriting (the default is `process.env.NODE_ENV === 'development'`). |
| 123 | + |
| 124 | +## Using the config |
| 125 | + |
| 126 | +- `tw-patch install` / `tw-patch extract` resolve this file automatically. |
| 127 | +- `unplugin-tailwindcss-mangle` mirrors the same configuration, so plugin options and CLI behaviour stay aligned. |
| 128 | +- When you need programmatic control, construct a `TailwindcssPatcher` manually and pass the modern options object—the legacy config is converted for you at runtime. |
0 commit comments