Tailwind CSS for Laravel

Introduction

This package wraps the standalone Tailwind CSS CLI tool. No Node.js required.

Inspiration

This package was inspired by the Tailwind CSS for Rails gem.

Installation

You can install the package via composer:

Attention: Version 2.x requires Tailwind V4. Make sure your application was upgraded to it or install version 1.x instead.

Next, you may run the install command:

Optionally, you can publish the config file with:

Usage

The package consists of 4 commands and a helper function.

Download the Tailwind CSS Standalone Binary

Since each OS/CPU needs its own version of the compiled binary, the first thing you need to do is run the download command:

This will detect the correct version based on your OS and CPU architecture.

By default, it will place the binary at the root of your app. The binary will be called tailwindcss. You may want to add that line to your project's .gitignore file.

Alternatively, you may configure the location of this binary file in the config/tailwindcss.php (make sure you export the config file if you want to do that).

Installing the Scaffolding

There are some files needed for the setup to work. On a fresh Laravel application, you may run the install command, like so:

This will publish a new resources/css/app.css main Tailwind CSS file. Make sure you upgrade your application to Tailwind V4.

Building

To build the Tailwind CSS styles, you may use the build command:

By default, that will read your resources/css/app.css file and generate the compiled CSS file at public/css/app.css.

You may want to generate the final CSS file with a digest on the file name for cache busting reasons (ideal for production). You may do so with the --digest flag:

You may also want to generate a minified version of the final CSS file (ideal for production). You may do so with the --minify flag:

These two flags will make the ideal production combo. Alternatively, you may prefer using a single --prod flag instead, which is essentially the same thing, but shorter:

Watching For File Changes

When developing locally, it's handy to run the watch command, which will keep an eye on your local files and run a build again whenever you make a change locally:

Note: the watch command is not meant to be used in combination with --digest or --minify flags.

Using the Compiled Asset

To use the compiled asset, you may use the tailwindcss helper function instead of the mix function like so:

That should be all you need.

Deploying Your App

When deploying the app, make sure you add the ideal build combo to your deploy script:

If you're running on a "fresh" app (or an isolated environment, like Vapor), and you have added the binary to your .gitignore file, make sure you also add the download command to your deploy script before the build one. In these environments, your deploy script should have these two lines

Preloading Assets as Link Header

For Laravel 10:

If you want to preload the TailwindCSS asset on Laravel 10, add the AddLinkHeaderForPreloadedAssets middleware to your web route group in the app/Http/Kernel.php:

For Laravel 11:

If you want to preload the TailwindCSS asset on Laravel 11, add the AddLinkHeaderForPreloadedAssets middleware to your web route group in the bootstrap/app.php:

The package will preload the asset by default. If you're linking an asset like:

It will add a Link header to the HTTP response like:

It will keep any existing Link header as well.

If you want to disable preloading with the Link header, set the flag to false:

You may also change or set additional attributes:

This will generate a preloading header like:

Mock Manifest When Testing

The tailwindcss() function will throw an exception when the manifest file is missing. However, we don't always need the manifest file when running our tests. You may use the InteractsWithTailwind trait in your main TestCase to disable that exception throwing:

Alternatively, you may also use the trait on specific test cases if you want to, so we can toggle that behavior as you need:

Both tests should pass.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Tony Messias
• All Contributors

License

The MIT License (MIT). Please see License File for more information.