@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.

[samrap]

Finally had a chance to take a look at this. Your solution of logging each file helped to identify the problem.

In our case, it was the Laravel Telescope and Nova files in public/vendor that were causing the issue. I simply moved these out of the repo for the upgrade and moved them back afterwards.

Thank you for the help! I think it would be great if the upgrade tool had a verbose option.

[mdocter]

Today I ran into this same issue, but in my code repository it was a large XML file instead of a JSON file. So both these file types can block the script from continuing. Thank you @kazuemon for pointing me in the right direction!

[mrextreme]

this should be a --verbose option

[fritzfr]

Honestly, the upgrade script is unusable. I let it run for 3 hours on a medium sized project and aborted it, there was no output any more after a while. I added the debugging and noticed that it looks at almost every file. Why? Why does tailwind upgrade script look at gitlab-ci.yml, app.js.LICENSE.txt and so many other files?

[wongjn]

I think it tries to be as agnostic as possible so scans a lot of files that you know are not related. Consider using .gitignore to exclude any vendor or distributed/minified files that don't need migrating. Or temporarily move them elsewhere. See #18972.