Laravel docs need some work - currently incorrect

[rickmills]

The new framework setup docs for Laravel are not functioning on a fresh install of Laravel and Tailwind 4.

It makes no mention of what to do with the existing laravel-vite-plugin that is installed as default. If you leave it in place you get the following error:

[vite] Internal server error: [postcss] It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

If you remove it, you then can't compile as you get a vite error:

Could not resolve entry module "index.html".

If you remove it and try running npm run dev you get a manifest error as the Laravel plugin is presumably required.

• If the Laravel plugin is still required, the docs page should show this.
• If it is not required, the docs page should cover how to get it to work correctly so you get a valid manifest.

As it stands on a fresh install of Laravel 11 and TailwindCSS 4, you cannot get a working environment setup using the provided instructions.

[rozsazoltan]

If you remove it, you then can't compile

The reproduction step is unclear. Did you remove postcss? And did you install @tailwindcss/postcss?

If the Laravel plugin is still required, the docs page should show this.

I don't understand the question about laravel-vite-plugin; it's independent of TailwindCSS but an essential plugin for the Laravel and Vite connection. I don't think they need to list an entire vite.config.js just to make it perfectly fit Laravel. The goal here, in my opinion, would simply have been to mention that you need to add @tailwindcss/vite to the plugins section of vite.config.js. Although it's true that mentioning the laravel-vite-plugin would make it clearer, they don’t depend on it... only Laravel does.

[rickmills]

I've not added/removed anything, as I say, a fresh copy of Laravel so the default vite file and packages that it installs. I'm not sure calling it "An entire vite file" is quite fair, it adds 1 line to the example if indeed it does still require laravel-vite-plugin to be installed to work, but like I said, regardless of if that is included it fails to work on a new Laravel project.

For reproduction steps:

1. Create a brand new laravel project, I used laravel new testproject
2. Go directly to the TailwindCSS 4 instructions for Laravel and follow it exactly as it is written and shown with zero other modifications to any part of Vite, Tailwind or Laravel that are not covered in the TailwindCSS 4 Laravel framework instructions.

[tedslittlerobot]

If it helps, I second this.

Following the tailwind v4 setup instructions on the tailwind website, against a fresh copy of the latest version of laravel results in an error when running npm run dev or npm run build. In the case of npm run dev, the command runs and launches the dev server, but fails when building for the first time (when you load a page). npm run build errors right there in the terminal.

Both give the output:

vite v6.0.11 building for production...
✓ 1 modules transformed.
x Build failed in 17ms
error during build:
[@tailwindcss/vite:generate:build] Can't resolve 'tailwindcss' in '/Users/$USER/Developer/tlr/tw-demo/resources/css'
file: /Users/$USER/Developer/tlr/tw-demo/resources/css/app.css
    at finishWithoutResolve (/Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:564:18)
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:656:15
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:718:5
    at eval (eval at create (/Users/$USER/Developer/tlr/tw-demo/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:15:1)
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:718:5
    at eval (eval at create (/Users/$USER/Developer/tlr/tw-demo/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:27:1)
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/DescriptionFilePlugin.js:89:43
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:718:5
    at eval (eval at create (/Users/$USER/Developer/tlr/tw-demo/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:15:1)
    at /Users/$USER/Developer/tlr/tw-demo/node_modules/enhanced-resolve/lib/Resolver.js:718:5

[tedslittlerobot]

Compared a working tailwind 4 laravel install (done via the upgrade cli) against a fresh one with the current tailwind 4 laravel instructions.

The issue is that the current latest laravel new will create a laravel project with tailwind 3.x installed.

At present, in order to use tailwind 4 with a new laravel install, the following steps are missing from the tailwind docs:

• manually upgrade tailwind from 3 to 4 in package.json
• remove tailwind (and autoprefixer) from postcss.config.js
• (not strictly necessary, but probably worth it to avoid future clashes: remove autoprefixer from package.json, as tailwind does this internally now)

[rozsazoltan]

Maybe it would be more beneficial to update the Laravel installation to use Tailwind 4.

In progress: laravel/laravel#6523

Regardless, I now understand your issue. I never actually followed the first step myself, so I didn't realize that it already includes TailwindCSS. So, theoretically, once the mentioned PR is merged, you should only need to execute the first step when installing Laravel, which will then use TailwindCSS 4 instead of v3. The other steps are just useful as additional information to show which configurations are included.

I assume the issue is caused by Laravel preferring TailwindCSS by default, so it is included in the installer.

[tedslittlerobot]

sorry - it was late last night when i posed the above - i meant to add as well that the issue should ideally be resolved on the laravel side as you have said. The above was for anyone in the meantime who found there way to this issue.

i was surprised as well to find that laravel has tailwind installed by default - it didn't used to! it used to be completely frontend-agnostic, and there was a cli command to add tailwind and load in some default tailwind views. But i haven't set up many new laravel projects in a while.

That said - a comment in laravel/laravel#6523 implies that it won't get merged until they have updated some related packages to support tailwind 4. It may be worth at least putting a warning on the tailwind docs to acknowledge this?

Something like "If your package.json has tailwind 3 in it..." or even recommend just running tailwind's auto upgrade tool, which should fix it in one hit...

[philipp-spiess]

Thanks for the clarification! Going to close this then since it's not an issue in our docs but looks like the Laravel community is already fixing things 💪