Tailwind 4 Migration Guide for Laravel Breeze: Step-by-Step

Why Upgrade Laravel Breeze to Tailwind CSS 4

Tailwind CSS v4 brings performance improvements, new features, and a refined DX. If you’re using Laravel Breeze as your frontend starter kit, upgrading ensures you stay modern, fast, and compatible with latest plugins and tooling.

Upgrading isn’t complex—but it requires precision.

This step-by-step guide walks you through every important change you need to make when migrating Laravel Breeze to Tailwind CSS 4.

Key Takeaways

• Learn how to migrate Breeze projects to Tailwind CSS 4
• Update configs, dependencies, and build tools the right way
• Know what’s deprecated and what’s changed in Tailwind 4
• Keep your UI stable with minimal breakage

Prerequisites

Make sure your Laravel project is already set up with Breeze and Tailwind CSS 3.

laravel new my-app
cd my-app
php artisan breeze:install
npm install && npm run dev

Backup your project or work in a separate git branch before starting the migration.

Step-by-Step Tailwind 4 Migration in Laravel Breeze

1. Update Tailwind CSS to v4

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Confirm the version:

npx tailwindcss -v

You should see v4.x.x

2. Update Tailwind Configuration

Tailwind 4 uses an improved config pattern.

Before:

// tailwind.config.js
module.exports = {
  content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

After:

// tailwind.config.js
import defaultTheme from 'tailwindcss/defaultTheme';
export default {
  content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue'
  ],
  theme: {
    extend: {
      fontFamily: {
        sans: [defaultTheme.fontFamily.sans],
      },
    },
  },
  plugins: [],
};

Rename tailwind.config.js to tailwind.config.ts if you’re using TypeScript with Vite.

3. Check for Removed or Renamed Utilities

Tailwind 4 has removed some legacy utility classes. Check your codebase for:

• divide-* classes
• space-x-*, space-y-*
• Custom @apply that no longer resolves

Use Tailwind’s Upgrade Guide to validate changes.

4. Enable the New Just-in-Time Engine (JIT)

JIT is now the default in Tailwind 4. If you had custom configurations, remove them. The following is no longer needed:

mode: 'jit' // ❌ no longer required

Common Issues During Migration

Problem	Solution
Build fails on tailwind.config.js	Rename to .ts if using ESM or fix syntax
Missing utility class	Replace with alternative or create custom class
Purge not working	Make sure all content paths are correct
Styling looks broken	Revisit layout classes and spacing utilities

Best Practices After Migration

✅ Use Laravel Mix or Vite with PostCSS 8+

Tailwind 4 requires PostCSS 8+. Update your vite.config.ts or webpack.mix.js accordingly.

✅ Audit Your Components

Tailwind 4 may affect spacing, typography, and layout. Check key UI components:

• Auth forms
• Navbars
• Dashboards
• Buttons and inputs

✅ Test Responsiveness

Changes in container utilities and spacing could affect breakpoints. Test mobile views thoroughly.

✅ Keep a tailwind.config.backup.js

Keep a copy of your old config for reference or rollback.

FAQ

Is Tailwind 4 stable? Yes. Tailwind 4 is production-ready and widely adopted.

Does Laravel Breeze officially support Tailwind 4? Yes, new Breeze installs are compatible. Older ones can be migrated easily.

Can I use Tailwind 4 with Vue or React in Breeze? Absolutely. Tailwind works well across all supported stacks.

Do I need to remove custom components? Only if they depend on deprecated classes. Review each manually.

Key Tools and References

• Tailwind CSS 4 Release Notes
• Tailwind Upgrade Guide
• Laravel Breeze Docs

Conclusion

Migrating Laravel Breeze to Tailwind CSS 4 is a smart step toward keeping your frontend modern and maintainable. With a few command-line steps, config tweaks, and a little testing, you can be up and running in no time.

Don’t wait for legacy issues to pile up. Upgrade today and unlock all the perormance benefits and modern utilities Tailwind 4 has to offer.