|
| 1 | +import { Callout } from 'nextra/components' |
| 2 | + |
| 3 | +# Migration · v7 → v8 |
| 4 | + |
| 5 | +`[email protected]` refactors the extraction engine, introduces typed option objects, and streamlines configuration sharing across the toolchain. This guide walks you through upgrading an existing v7 setup—CLI, configs, and bundler plugins—without losing backwards compatibility. |
| 6 | + |
| 7 | +<Callout type="info"> |
| 8 | +Legacy configs still work. You can migrate incrementally by adding new fields while keeping the historical `patch`/`cache` structure. |
| 9 | +</Callout> |
| 10 | + |
| 11 | +## 1. Update dependencies |
| 12 | + |
| 13 | +```sh npm2yarn |
| 14 | +npm i -D tailwindcss-patch@^8 unplugin-tailwindcss-mangle@latest @tailwindcss-mangle/config@latest @tailwindcss-mangle/core@latest |
| 15 | +``` |
| 16 | + |
| 17 | +- The patch package ships the new API surface. |
| 18 | +- `unplugin-tailwindcss-mangle` consumes the refreshed class inventory and honours the shared config defaults. |
| 19 | +- `@tailwindcss-mangle/config` normalises both legacy and modern shapes for CLI and plugin consumers. |
| 20 | + |
| 21 | +## 2. Review imports |
| 22 | + |
| 23 | +The package layout now exposes purpose-specific entry points: |
| 24 | + |
| 25 | +| v7 path | v8 replacement | |
| 26 | +| --- | --- | |
| 27 | +| `tailwindcss-patch/core/**` | `tailwindcss-patch/api/**`, `tailwindcss-patch/cache/**`, `tailwindcss-patch/runtime/**`, etc. | |
| 28 | +| `CacheManager` | `CacheStore` | |
| 29 | +| `processTailwindcss` | `runTailwindBuild` | |
| 30 | + |
| 31 | +Update manual imports accordingly: |
| 32 | + |
| 33 | +```ts |
| 34 | +import { TailwindcssPatcher } from 'tailwindcss-patch' |
| 35 | +import { CacheStore } from 'tailwindcss-patch/cache/store' |
| 36 | +import { applyTailwindPatches } from 'tailwindcss-patch/patching/patch-runner' |
| 37 | +``` |
| 38 | + |
| 39 | +## 3. Embrace the unified options object |
| 40 | + |
| 41 | +The constructor now accepts a single `TailwindcssPatchOptions` object. Passing a legacy object with `patch`/`cache` still works—the runtime calls `fromLegacyOptions()` internally. |
| 42 | + |
| 43 | +```ts |
| 44 | +// Legacy shape (still accepted) |
| 45 | +new TailwindcssPatcher({ |
| 46 | + patch: { |
| 47 | + output: { filename: '.tw-patch/tw-class-list.json', loose: true }, |
| 48 | + tailwindcss: { version: 3, v3: { cwd, config } }, |
| 49 | + applyPatches: { extendLengthUnits: true }, |
| 50 | + }, |
| 51 | +}) |
| 52 | + |
| 53 | +// Recommended v8 shape |
| 54 | +new TailwindcssPatcher({ |
| 55 | + overwrite: true, |
| 56 | + cache: { |
| 57 | + enabled: true, |
| 58 | + dir: '.tw-patch/cache', |
| 59 | + strategy: 'merge', |
| 60 | + }, |
| 61 | + output: { |
| 62 | + file: '.tw-patch/tw-class-list.json', |
| 63 | + format: 'json', |
| 64 | + removeUniversalSelector: true, |
| 65 | + }, |
| 66 | + features: { |
| 67 | + exposeContext: { refProperty: 'runtimeContexts' }, |
| 68 | + extendLengthUnits: { units: ['rpx'] }, |
| 69 | + }, |
| 70 | + tailwind: { |
| 71 | + version: 4, |
| 72 | + v4: { |
| 73 | + base: './src', |
| 74 | + cssEntries: ['dist/tailwind.css'], |
| 75 | + }, |
| 76 | + }, |
| 77 | +}) |
| 78 | +``` |
| 79 | + |
| 80 | +When migrating configs, add the new fields gradually: |
| 81 | + |
| 82 | +- `output.format` (`json` or `lines`) |
| 83 | +- `output.pretty` (indentation or `false`) |
| 84 | +- `tailwind.v4.cssEntries` / `tailwind.v4.sources` |
| 85 | +- `features.extendLengthUnits` with shared options for Tailwind v3 and v4 |
| 86 | + |
| 87 | +## 4. Refresh CLI usage |
| 88 | + |
| 89 | +`tw-patch install` and `tw-patch extract` keep their names but gained quality-of-life flags: |
| 90 | + |
| 91 | +| Flag | Description | |
| 92 | +| --- | --- | |
| 93 | +| `--output <file>` | Override the generated class list target. | |
| 94 | +| `--format <json|lines>` | Emit JSON (default) or newline-delimited text. | |
| 95 | +| `--css <file>` | Provide Tailwind v4 CSS entry files. Repeat for multiple entries. | |
| 96 | +| `--no-write` | Skip writing to disk, returning the class list to the caller. | |
| 97 | + |
| 98 | +Configuration is resolved from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Existing `tailwindcss-mangle.config.ts` files are still picked up. |
| 99 | + |
| 100 | +## 5. Cache strategy changes |
| 101 | + |
| 102 | +`CacheStore` replaces `CacheManager` and unifies async behaviour: |
| 103 | + |
| 104 | +```ts |
| 105 | +const cache = new CacheStore(options.cache) |
| 106 | +await cache.write(new Set(['text-lg'])) |
| 107 | +const values = await cache.read() |
| 108 | +``` |
| 109 | + |
| 110 | +- `cache.strategy` now accepts `merge` (default) or `overwrite`. |
| 111 | +- `cache.enabled` can be toggled globally or per command via overrides. |
| 112 | +- Invalid JSON files are purged automatically to avoid silent failures. |
| 113 | + |
| 114 | +## 6. Plugin & runtime alignment |
| 115 | + |
| 116 | +`@tailwindcss-mangle/config` feeds both the CLI and `unplugin-tailwindcss-mangle`. Ensure your config exposes: |
| 117 | + |
| 118 | +- `patch.output.filename` (or the new `output.file`) |
| 119 | +- `patch.applyPatches.extendLengthUnits` if you previously relied on the boolean flag |
| 120 | +- `mangle.classListPath` pointing at the generated `.tw-patch/tw-class-list.json` |
| 121 | +- `mangle.classMapOutput` if you need before/after maps for auditing |
| 122 | + |
| 123 | +In bundlers, the minimal setup looks like: |
| 124 | + |
| 125 | +```ts |
| 126 | +import tailwindcssMangle from 'unplugin-tailwindcss-mangle/vite' |
| 127 | + |
| 128 | +export default defineConfig({ |
| 129 | + plugins: [ |
| 130 | + tailwindcssMangle({ |
| 131 | + classListPath: '.tw-patch/tw-class-list.json', |
| 132 | + }), |
| 133 | + ], |
| 134 | +}) |
| 135 | +``` |
| 136 | + |
| 137 | +Nuxt 3 users should also set `experimental.inlineSSRStyles = false` so Vite emits CSS for scanning. |
| 138 | + |
| 139 | +## 7. Tailwind v4 projects |
| 140 | + |
| 141 | +Version 8.0 introduces native Tailwind v4 support: |
| 142 | + |
| 143 | +- Provide CSS entry files via `tailwind.v4.cssEntries`. |
| 144 | +- Define content sources through `tailwind.v4.sources` (defaults to `**/*` under `base`). |
| 145 | +- Use the new `--css` CLI flag when extracting from monorepos that emit multiple CSS bundles. |
| 146 | + |
| 147 | +## 8. Upgrade checklist |
| 148 | + |
| 149 | +1. Update dependencies (`tailwindcss-patch`, `unplugin-tailwindcss-mangle`, shared packages). |
| 150 | +2. Regenerate or tweak `tailwindcss-patch.config.ts`, adding new `output` and `tailwind.v4` fields as needed. |
| 151 | +3. Adjust custom imports to the new module folders. |
| 152 | +4. Verify CLI scripts and CI pipelines with the refreshed flags. |
| 153 | +5. Clear stale caches if necessary (`pnpm script:clean`) and rerun `tw-patch extract`. |
| 154 | +6. Run your bundler build and confirm class names are rewritten as expected. |
| 155 | +7. (Optional) Enable `classMapOutput` to audit mappings during the first migration run. |
| 156 | + |
| 157 | +## Need help? |
| 158 | + |
| 159 | +- Compare against the legacy docs in your repository history. |
| 160 | +- Open an issue with reproduction steps if you hit a regression—we track migration feedback closely. |
0 commit comments