sodcalculator

10 Tech How-To

Tailwind CSS v4 Migration: Key Checks Beyond Build Setup

Tag 10-55766 · Updated · Standard formula, shown below

Volume 9.26 yd³
Volume
250.0 ft³
Result
Lawn length
40 ft
You entered
Lawn width
25 ft
You entered
You enter
Lawn length, Lawn width, Depth
You get
Volume, Volume
Rounding
2 dp · 1 dp

When migrating to Tailwind CSS v4, the build setup is only the beginning—you must also audit your custom configuration, class name usage, and plugin compatibility to avoid silent style regressions. This guide covers the critical checks beyond the initial installation, helping you identify and fix issues before they reach production.

Formula

The calculator uses the standard volume formula for a rectangular prism: Volume = Length × Width × Depth. For cubic yards, the result is divided by 324 (since 1 cubic yard = 27 cubic feet, and depth is in inches, so 27 × 12 = 324). For cubic feet, the result is divided by 12 to convert inches to feet.

Variables:

  • l = lawn length (ft)
  • w = lawn width (ft)
  • d = depth of material (in)

Worked Example

Using the default values: length = 40 ft, width = 25 ft, depth = 3 in.

  1. Calculate volume in cubic feet: 40 × 25 × (3 / 12) = 40 × 25 × 0.25 = 250 ft³.
  2. Convert to cubic yards: 250 / 27 = 9.259 yd³ (rounded to 2 decimals: 9.26 yd³).

The calculator gives 9.26 yd³ and 250 ft³, matching the manual calculation.

Why This Check Matters

Tailwind v4 introduced a new engine that scans your source files for class names and generates CSS on demand. This means any class that isn’t detected won’t be included in the output. The most common issue after migration is missing styles because the scanner doesn’t recognize dynamic class construction or files outside the configured content paths. Unlike v3, where you explicitly listed content files, v4 uses automatic source detection, which can miss files in monorepos or those with unusual extensions.

Key Checks Beyond Build Setup

Here are the critical areas to review after updating your build configuration:

  • Custom configuration migration: Your tailwind.config.js file is no longer used by default. v4 uses CSS-based configuration via @theme and @utility directives. Move custom colors, fonts, and spacing values into your CSS file.
  • Content scanning: Verify that all template files (HTML, JSX, Vue, etc.) are being scanned. Use the @source directive to add explicit paths if automatic detection misses files.
  • Class name detection: Avoid string concatenation like bg-${color}-500. v4’s scanner may not pick these up. Use full class names or safelist them.
  • Plugin compatibility: Third-party plugins that rely on the old configuration API may break. Check for updated versions or replace them with CSS-based alternatives.
  • Variant changes: Some variants have changed syntax (e.g., dark: now uses @variant in CSS). Review your custom variants.
  • Removed utilities: A few utilities were removed or renamed (e.g., shadow-sm now behaves differently). Search your codebase for deprecated classes.

Common Problems and How to Fix Them

During migration, you may encounter these issues:

  • Missing styles after build: This usually means the scanner didn’t find a class. Check the generated CSS for the class name. If missing, add an explicit @source path or use the @utility directive to define it.
  • Custom colors not appearing: In v4, define colors in @theme block. For example: @theme { --color-brand: #ff0000; }. Then use bg-brand.
  • Build errors with plugins: If a plugin throws an error, try removing it and using plain CSS. Many plugins have v4-compatible versions, so update to the latest.
  • Dark mode not working: v4 defaults to prefers-color-scheme. To use class-based dark mode, add @custom-variant dark (&:where(.dark, .dark *)); to your CSS.

How to Choose What to Update First

Prioritize updates that affect the largest portion of your UI. Start with the global configuration (colors, fonts, spacing) because they impact every component. Then move to custom utilities and variants. Finally, handle deprecated classes and plugins. Use a systematic search for class names that no longer exist in v4’s default theme.

Comparison with v3

v4 is significantly faster due to its new Rust-based engine, but it requires a different mental model. In v3, you configured everything in a JavaScript file; in v4, you configure via CSS. This shift reduces build complexity but increases the learning curve. The automatic content detection is convenient but can be less predictable in complex projects.

Safety and Best Practices

Before deploying, run a visual regression test across key pages. Check for layout shifts, missing colors, and font changes. Keep a backup of your v3 configuration so you can roll back if needed. Also, ensure your team understands the new CSS-first configuration to avoid future mistakes.

Frequently Asked Questions

Do I need to remove tailwind.config.js?

No, but v4 ignores it unless you explicitly require it. If you have custom values, move them to @theme in your CSS. Leaving the file won’t break anything, but it’s cleaner to delete it.

Why are my custom classes not working?

v4 only generates classes it finds in your content. If you define a custom class in CSS using @utility, it should work. If you’re using dynamic class names, the scanner may miss them. Use full class names or add a safelist.

Can I use v4 with a monorepo?

Yes, but you may need to specify source paths using @source to include files from other packages. Automatic detection works best when all files are in the same project.

What happened to the `@apply` directive?

It still works, but it’s recommended to use it in your CSS files. In v4, @apply can be used with any utility, including custom ones defined with @utility.

How do I migrate custom plugins?

Check if the plugin has a v4-compatible version. If not, rewrite it as a CSS utility using @utility. Most plugin functionality can be replicated with CSS variables and custom properties.

Related

Formula used
in l | Lawn length | ft | 40 | 0 | 100000
in w | Lawn width | ft | 25 | 0 | 100000
in d | Depth | in | 3 | 0 | 120
out yd | Volume | yd³ | l * w * d / 324 | 2
out ft3 | Volume | ft³ | l * w * d / 12 | 1

Each line is one input (in, sel, list) or one result (out: label, unit, formula, decimals). How the calculators work

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More in this bed

The whole Tech How-To bed →