tw-migrate 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -129
- package/dist/bin.js +9 -3
- package/dist/index.js +816 -171
- package/package.json +12 -8
package/README.md
CHANGED
|
@@ -1,142 +1,26 @@
|
|
|
1
1
|
# tw-migrate
|
|
2
2
|
|
|
3
|
-
Migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet
|
|
3
|
+
Migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet usage to Tailwind CSS v4 utilities. Supports CSS, SCSS, Sass, Less, and CSS Modules.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Install and configure Tailwind CSS v4 in the package you want to migrate by following the [official installation guide](https://tailwindcss.com/docs/installation/). The package must have a CSS entry that loads Tailwind CSS, usually with `@import "tailwindcss";`, so `tw-migrate` can validate generated utilities against the project's Tailwind configuration.
|
|
5
|
+
Requires Node.js 22.23.2+ and [Tailwind CSS v4 configured in your project](https://tailwindcss.com/docs/installation/) with a CSS entry such as `@import "tailwindcss";`. For Sass or Less, install the compiler in the project you are migrating.
|
|
8
6
|
|
|
9
7
|
## Usage
|
|
10
8
|
|
|
11
|
-
Run
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
npx tw-migrate # Migrate the current package
|
|
15
|
-
npx tw-migrate --dry-run # Preview the current package
|
|
16
|
-
npx tw-migrate path/to/Button.module.scss # Migrate one stylesheet
|
|
17
|
-
npx tw-migrate path/to/Button.module.scss --dry-run # Preview one stylesheet
|
|
18
|
-
npx tw-migrate --workspaces # Migrate every package
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
`pnpm dlx tw-migrate` and `yarn dlx tw-migrate` take the same arguments.
|
|
22
|
-
|
|
23
|
-
The CLI applies changes by default; `--dry-run` prints the diff without touching files. Pass `--tailwind-css path/to/globals.css` when the current package has multiple Tailwind entries. `--force` skips package groups that fail discovery or input parsing; plan-integrity and write failures always stop the run.
|
|
24
|
-
|
|
25
|
-
Unmatched media conditions are extracted into named `@custom-variant` definitions in the Tailwind entry and consumers receive stacked variants such as `screen:width-lte-700px:m-0`; verified built-ins and existing breakpoints are reused instead of redefined, and a second run recognizes the first run's definitions. Pass `--no-extract-media-queries` to keep the arbitrary-variant form instead.
|
|
26
|
-
|
|
27
|
-
## Run from a clone
|
|
28
|
-
|
|
29
|
-
The migration planner is a native addon, so a clone needs one build before the CLI runs:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
vp install # or: pnpm install
|
|
33
|
-
vp run build:debug # compiles the addon for your platform
|
|
34
|
-
node src/bin.ts --help
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
Then use `node src/bin.ts` wherever the commands above use `npx tw-migrate`. The CLI always migrates the package it is run from, so to migrate a different project, run the built entrypoint by absolute path from that project's directory:
|
|
9
|
+
Run from the package you want to migrate:
|
|
38
10
|
|
|
39
11
|
```bash
|
|
40
|
-
|
|
41
|
-
|
|
12
|
+
npx tw-migrate --dry-run # Preview changes
|
|
13
|
+
npx tw-migrate # Apply changes
|
|
14
|
+
npx tw-migrate path/to/Button.module.scss # Migrate one stylesheet
|
|
15
|
+
npx tw-migrate --workspaces # Migrate all packages
|
|
16
|
+
npx tw-migrate --help # See all options
|
|
42
17
|
```
|
|
43
18
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
- `.css`, `.scss`, `.sass`, and `.less` stylesheets
|
|
47
|
-
- SCSS/Sass/Less values evaluated with the target project's installed compiler; ambiguous mixin and partial origins are retained
|
|
48
|
-
- `.js`, `.jsx`, `.ts`, and `.tsx` source files
|
|
49
|
-
- static `.html` literal `class`/`id` attributes scoped by local external stylesheet links (link-level `print` media supported; other link media conditions are retained)
|
|
50
|
-
- Vue 3 `.vue` files: literal template `class`/`id` attributes and static string/template `:class` bindings matched against inline CSS, SCSS, Sass, and Less `<style scoped>` blocks plus statically imported stylesheets, parsed and compiled with the target project's dependencies
|
|
51
|
-
- direct `<script setup>` component imports can prove child-root and caller class surfaces across SFCs; unresolved components, exported roots, non-static bindings, and callers outside that graph retain scoped rules
|
|
52
|
-
- unscoped Vue styles migrate only in private single-source packages where their global usage is closed; broader unscoped surfaces retain with warnings
|
|
53
|
-
- Vue `<style module>` blocks migrate against direct `:class="$style.x"` member bindings; any other `$style`/`useCssModule` appearance or a named module retains the block
|
|
54
|
-
- direct CSS Module members, static template literals, and static expression literals
|
|
55
|
-
- global `className` and `id` literals
|
|
56
|
-
- React/Next.js `className` logical (`&&`, `||`, `??`) and conditional (`?:`) expressions: string and direct CSS Module member result leaves migrate without evaluating their conditions, `null`/`undefined`/`false`/empty-string results are warning-free, and unsupported result leaves retain with a warning while supported siblings still migrate
|
|
57
|
-
- multi-compound CSS Module selectors whose element relationships are proven from the JSX graph
|
|
58
|
-
- common state pseudo-classes, global arbitrary descendant variants, and conditional at-rules (`@media`, `@supports`, `@container`, `@starting-style`)
|
|
59
|
-
- `and`-joined media conditions decompose into stacked named variants with definitions extracted into the Tailwind entry; ordering-sensitive conflicts between overlapping conditions are retained unless the original winner is provable
|
|
60
|
-
- in `--workspaces` mode a package without its own Tailwind entry may reuse a proven ancestor entry, packages sharing one entry plan as a single group with one composed entry edit, and cross-package consumers must provably load the shared entry
|
|
61
|
-
- the tier-1 property mapping families with shorthand/longhand normalization
|
|
62
|
-
- exact Tailwind theme tokens and breakpoints with arbitrary-value fallback
|
|
63
|
-
- generated candidates are compiled against the project's Tailwind entry; failures retain the source rule
|
|
64
|
-
- batch migration of every stylesheet in a package, and `--workspaces` runs across packages
|
|
65
|
-
- CSS Module cleanup when every reference is safely migrated
|
|
66
|
-
|
|
67
|
-
Everything outside this subset is retained and reported with one of the warning codes below.
|
|
68
|
-
|
|
69
|
-
## Warning codes
|
|
70
|
-
|
|
71
|
-
| Code | Meaning |
|
|
72
|
-
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
73
|
-
| `aliased-css-module-reference` | A CSS Module class is aliased to a local binding, so the module is retained. |
|
|
74
|
-
| `batch-stylesheet-conflict` | Utilities generated from different stylesheets, or under overlapping media conditions with an unprovable order, conflict on the same element, so the contributing rule is retained. |
|
|
75
|
-
| `candidate-compilation-failure` | A generated candidate did not compile under the project's Tailwind entry, so its rule is retained. |
|
|
76
|
-
| `component-class-target` | A child component's root element can carry classes a Vue scoped rule matches, so the rule is retained. |
|
|
77
|
-
| `computed-css-module-reference` | A computed CSS Module access cannot be verified, so the module is retained. |
|
|
78
|
-
| `cross-package-stylesheet-link` | A linked stylesheet is owned by another package, so it is not analyzed outside workspace mode. |
|
|
79
|
-
| `css-module-composes` | The rule uses or is targeted by `composes`, so it is retained. |
|
|
80
|
-
| `dynamic-class-name` | A `className` value or expression result is dynamic, so that class site cannot be migrated. |
|
|
81
|
-
| `dynamic-html-attribute` | An HTML attribute is not a safely writable quoted literal, so the element cannot be migrated. |
|
|
82
|
-
| `dynamic-template-class` | A dynamic class binding makes a Vue template's class set unprovable, so its scoped rules are retained. |
|
|
83
|
-
| `existing-tailwind-conflict` | A generated utility may conflict with a Tailwind class already on the element. |
|
|
84
|
-
| `inferred-preprocessor-source` | A linked CSS file was matched to a uniquely named preprocessor source file. |
|
|
85
|
-
| `media-query-definition-fallback` | The Tailwind entry could not be edited safely, so media behavior was preserved with arbitrary variants. |
|
|
86
|
-
| `module-utilities-conflict` | Utilities generated from different module classes on one element overlap, so their rules are retained. |
|
|
87
|
-
| `non-classname-css-module-reference` | A CSS Module class is used outside a supported `className`, so the module is retained. |
|
|
88
|
-
| `open-root-fallthrough` | A parent component can merge classes onto a Vue SFC's single root element, so its scoped rules are retained. |
|
|
89
|
-
| `preprocessor-style-block` | A Vue `<style>` block uses a preprocessor language outside the supported SCSS, Sass, and Less set. |
|
|
90
|
-
| `rebuild-required` | A preprocessor entry was migrated; rebuild it to refresh its generated CSS. |
|
|
91
|
-
| `reference-only-css-module-consumer` | A reference-only (non-writable) source uses the CSS Module, so it is retained. |
|
|
92
|
-
| `retained-global-rule` | Global CSS is never deleted automatically. |
|
|
93
|
-
| `shadowed-scoped-rule` | Other package CSS also targets a class a Vue scoped rule matches, so the rule is retained to preserve the cascade. |
|
|
94
|
-
| `shared-preprocessor-source` | A Sass partial must be analyzed through every consuming entry, so it is retained. |
|
|
95
|
-
| `unproven-css-module-relationship` | A compound selector's element relationship could not be proven for every usage. |
|
|
96
|
-
| `unproven-script-reference` | An inline script names a CSS Module class, so the module is retained. |
|
|
97
|
-
| `unproven-shared-entry-flow` | A consumer flow could not be proven to load the shared Tailwind entry, so the stylesheet is retained. |
|
|
98
|
-
| `unproven-source-map` | A generated rule does not map uniquely to one authored source rule, so it is retained. |
|
|
99
|
-
| `unresolved-selector-target` | No exclusively supported `className` references were found for the rule. |
|
|
100
|
-
| `unscoped-style-block` | An unscoped Vue style does not have a closed private single-source usage surface, so it is retained. |
|
|
101
|
-
| `unsupported-animation` | The animation references keyframes that cannot be converted. |
|
|
102
|
-
| `unsupported-at-rule` | The rule contains or sits inside an at-rule outside the supported set. |
|
|
103
|
-
| `unsupported-container-query` | The `@container` condition has no Tailwind variant equivalent. |
|
|
104
|
-
| `unsupported-css-module-reference` | The CSS Module has an import or reference that cannot be migrated safely. |
|
|
105
|
-
| `unsupported-declaration` | A declaration is outside the supported property subset. |
|
|
106
|
-
| `unsupported-html-base` | A remote or unrepresentable base URL prevents safe stylesheet link resolution. |
|
|
107
|
-
| `unsupported-html-stylesheet-link` | Only local package stylesheet links are analyzed. |
|
|
108
|
-
| `unsupported-important` | `!important` declarations are not migrated. |
|
|
109
|
-
| `unsupported-link-media` | A stylesheet link or `@import` media condition cannot be represented safely. |
|
|
110
|
-
| `unsupported-media-query` | The `@media` condition has no Tailwind variant equivalent. |
|
|
111
|
-
| `unsupported-nested-at-rule` | A nested conditional at-rule could not be fully converted. |
|
|
112
|
-
| `unsupported-overlap` | Shorthand and longhand declarations overlap in a way that cannot be normalized. |
|
|
113
|
-
| `unsupported-rule-content` | The rule contains non-declaration content that cannot be converted. |
|
|
114
|
-
| `unsupported-selector` | The selector is outside the supported subset. |
|
|
115
|
-
| `unsupported-sfc-block` | A Vue SFC or one of its blocks cannot be analyzed safely, so it is retained. |
|
|
116
|
-
| `unsupported-starting-style` | The `@starting-style` condition could not be converted. |
|
|
117
|
-
| `unsupported-supports-query` | The `@supports` condition has no Tailwind variant equivalent. |
|
|
118
|
-
| `unsupported-value` | A declaration value cannot be represented as a Tailwind utility. |
|
|
119
|
-
| `unsupported-vue-version` | The project's Vue version is not Vue 3, so its SFCs are retained. |
|
|
120
|
-
|
|
121
|
-
See the [core RFC](./rfcs/css-to-tailwind-migration-cli.md) and [preprocessor/HTML RFC](./rfcs/preprocessor-and-html-migration.md) for the complete design and remaining scope.
|
|
122
|
-
|
|
123
|
-
## Testing the packaged CLI
|
|
124
|
-
|
|
125
|
-
Run `vp run test:snapshots` to build, pack, install, and test the published CLI shape against the cross-platform snapshot corpus. The command uses the npm registry and performs one shared install per test process. See [`crates/snapshots/README.md`](./crates/snapshots/README.md) for targeted runs and snapshot review commands.
|
|
126
|
-
|
|
127
|
-
## Testing browser ecosystem compatibility
|
|
128
|
-
|
|
129
|
-
Build the current-platform package and install Chromium before a focused browser run:
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
vp run build
|
|
133
|
-
vp run artifacts
|
|
134
|
-
vp exec playwright install chromium
|
|
135
|
-
vp run test:ecosystem --case react-vite-css
|
|
136
|
-
```
|
|
19
|
+
`pnpm dlx tw-migrate` and `yarn dlx tw-migrate` accept the same arguments.
|
|
137
20
|
|
|
138
|
-
|
|
21
|
+
**The CLI writes files by default.** Review the preview before applying. Unsupported or ambiguous rules stay in place with [warnings](https://github.com/jong-kyung/tw-migrate/blob/main/docs/warnings.md). Use `--tailwind-css path/to/globals.css` to select an entry when discovery is ambiguous.
|
|
139
22
|
|
|
140
|
-
|
|
23
|
+
## More
|
|
141
24
|
|
|
142
|
-
|
|
25
|
+
- [Supported behavior and design](https://github.com/jong-kyung/tw-migrate/tree/main/rfcs/)
|
|
26
|
+
- [Contributing and local development](https://github.com/jong-kyung/tw-migrate/blob/main/CONTRIBUTING.md)
|
package/dist/bin.js
CHANGED
|
@@ -4,7 +4,7 @@ import { styleText } from "node:util";
|
|
|
4
4
|
//#region src/bin.ts
|
|
5
5
|
const { version } = {
|
|
6
6
|
name: "tw-migrate",
|
|
7
|
-
version: "0.
|
|
7
|
+
version: "0.7.0",
|
|
8
8
|
description: "Preview and migrate React, Vue, and HTML CSS to Tailwind utilities",
|
|
9
9
|
keywords: [
|
|
10
10
|
"codemod",
|
|
@@ -36,16 +36,22 @@ const { version } = {
|
|
|
36
36
|
"artifacts": "node -e \"const fs=require('node:fs'); const files=fs.readdirSync('.').filter((file)=>file.startsWith('tw-migrate.')&&file.endsWith('.node')); if(files.length===0) throw new Error('no tw-migrate.*.node artifact in the package root; run build first'); for(const file of files) fs.copyFileSync(file, 'npm/'+file.slice('tw-migrate.'.length, -'.node'.length)+'/'+file)\"",
|
|
37
37
|
"test": "cargo test && pnpm build:debug && vp test",
|
|
38
38
|
"test:ecosystem": "node ecosystem-ci/run.ts",
|
|
39
|
+
"knip": "knip",
|
|
39
40
|
"typecheck": "tsc --noEmit",
|
|
40
41
|
"snapshots:prepare": "node -e \"const fs=require('node:fs'); for(const dir of fs.readdirSync('npm')) for(const file of fs.readdirSync('npm/'+dir)) if(file.endsWith('.node')) fs.rmSync('npm/'+dir+'/'+file)\" && pnpm build && pnpm artifacts",
|
|
41
42
|
"test:snapshots": "pnpm snapshots:prepare && cargo test -p tw-migrate-snapshots",
|
|
42
43
|
"prepare": "vp config"
|
|
43
44
|
},
|
|
44
|
-
dependencies: {
|
|
45
|
+
dependencies: {
|
|
46
|
+
"diff": "9.0.0",
|
|
47
|
+
"parse5": "8.0.1",
|
|
48
|
+
"zod": "4.5.4"
|
|
49
|
+
},
|
|
45
50
|
devDependencies: {
|
|
46
51
|
"@napi-rs/cli": "catalog:",
|
|
47
52
|
"@types/node": "catalog:",
|
|
48
53
|
"@vitest/browser-playwright": "catalog:",
|
|
54
|
+
"knip": "catalog:",
|
|
49
55
|
"less": "catalog:",
|
|
50
56
|
"playwright": "catalog:",
|
|
51
57
|
"sass": "catalog:",
|
|
@@ -75,7 +81,7 @@ const { version } = {
|
|
|
75
81
|
]
|
|
76
82
|
},
|
|
77
83
|
engines: { "node": ">=22.23.2" },
|
|
78
|
-
packageManager: "pnpm@11.
|
|
84
|
+
packageManager: "pnpm@11.24.0"
|
|
79
85
|
};
|
|
80
86
|
const usage = "Usage: tw-migrate [style-file] [options]";
|
|
81
87
|
const help = `${usage}
|