@tailwindcss/upgrade: Upgrade frozen on template migration step

[samrap]

Attempting to upgrade Tailwind from V3 to V4 in a Laravel 12 project.

The upgrade tool continues to hang on the Migrating templates... step. I've let it run for ~30 minutes before sending SIGTERM and attempting multiple times, with the same results.

We have a hundred or so JSX files in the project...nothing crazy. FWIW, all of the template files in the project have diffs which leads me to believe they are migrated successfully, but the tool is stuck on something.

I cannot find other discussions or issues on this topic, so I'm asking here. How can I investigate this further?

Node: 20.18.0
TailwindCSS: 4.1.11
MacOS: 14.6.1

[wongjn]

I'm not sure if adding DEBUG=* would help in any way? Perhaps the directory you are running the command could have some impact? Consider checking if you have sufficiently gitignored stuff properly. Also, you could consider providing a git repo that reproduces the unexpected behavior and we can take a look.

[wongjn]

Hmm, I'm not sure if the repeated lines of:

INFO tailwindcss_oxide::scanner: Provided sources:
INFO tailwindcss_oxide::scanner: Optimized sources:
INFO get_candidates_with_positions: tailwindcss_oxide::scanner: enter
INFO get_candidates_with_positions: tailwindcss_oxide::scanner: exit

is expected…

[samrap]

Are you familiar with the upgrade tool/what is going on here?

[wongjn]

Can't say I am familiar with the upgrade tool or what is going on there. Though you could consider providing a git repo that reproduces the unexpected behavior and I can take a closer look for you.

[samrap]

Unfortunately can't provide access to the repo but I appreciate your offer and help.

[wongjn]

You could make a copy with private parts removed.

[kazuemon]

(📝 I am using a translator)

Are there any large files (e.g., mechanically generated JSON files) included in the group of files subject to change?

I've encountered the same behavior.

• There are more than 100 files to be migrate in this project.
• I use both Mac and Windows (WSL), and this happens on both.
• In my case, the contents of the target file became empty and froze as it was.

For the purposes of this analysis, we rewrote the code as follows.

tailwindcss/packages/@tailwindcss-upgrade/src/index.ts

Lines 296 to 301 in 4d37043

	// Migrate each file
	await Promise.allSettled(
	filesToMigrate.map((file) =>
	migrateTemplate(designSystem, config?.userConfig ?? null, file),
	),
	)

for await (const file of filesToMigrate) {
  console.log(`Migrating: ${highlight(file)}`)
  await migrate(designSystem, config?.userConfig ?? null, file);
  console.log(`Migrated: ${highlight(file)}`)
}

When I ran it, I found that it was stuck at "Migrating" as shown below, but I realized that the file causing the problem was always the same.

Upon checking the target file, we found that it was a VERY long JSON file generated for documentation purposes. After deleting this file, the migration command completed without any problems.

I don't know if you have the same cause, but I hope this information is helpful.

[Ryan-M-Smith]

This ended up being my issue. I had a similar issue with some large JSON config files, and temporarily moving the outer folder out of my codebase allowed to script to complete.