Bootstrap a Laravel 7 with Tailwind CSS project

I've decided to redesign and upgrade my website with Tailwind CSS and Laravel 7 so here is a quick guide of how to bootstrap a project that uses both of them.

Install Laravel 7

The first thing to do is to make sure your system meets the requirements, mainly having PHP 7.2, composer and some extensions. Then as detailed in the Laravel official docs run composer global require laravel/installer and then use laravel new my-project to generate the project scaffold.

Additionally, you can run composer create-project --prefer-dist laravel/laravel my-project.

Once your project is created, you can run php artisan serve from the project folder to start a local server and open localhost:8000 in your browser to see the default Laravel welcome page.

Add Tailwind CSS to your Laravel 7 project

The next step is to add Tailwind to the project. I found plugin by Jeffrey Way that makes this super easy. Install it with npm install laravel-mix-tailwind --save-dev and then modify the file webpack.mix.js so it's like the next one:

const mix = require('laravel-mix')

// for Tailwind: https://github.com/JeffreyWay/laravel-mix-tailwind
require('laravel-mix-tailwind')

mix
  .js('resources/js/app.js', 'public/js')
  .sass('resources/sass/app.scss', 'public/css')
  .tailwind()

But what is this for? If you check the package.json file of your project, you can see that there is a dev/development script. These scripts run Webpack which is a module bundler that will take care of compiling our css or scss and js files in the resources folder and put the results in the public directory. It's normally used for javascript but we're going to use it for our css for now.

As detailed in the Tailwind docs, we need to import the Tailwind base and components to our css or scss file. Inside the resources folder, create a folder named "scss" and inside it, create a file named app.scss. In this file copy the following imports:

/* 
* resources/sass/app.scss
*/

// Imports Tailwind CSS
@tailwind base;

@tailwind components;

@tailwind utilities;

The next step is to generate a Tailwind config file. We can create it manually or we can generate it with the command npx tailwindcss init. This will generate an empty file but Tailwind allows you to customize your fonts, colours and a lot of other things in this file so check the corresponding page of their official docs for more info.

Now if you run npm run dev , Webpack should start to compile and generate the files in your public folder.

NOTE: The current version of laravel-mix-tailwind contains a bug as it expects the file tailwind.config.js to be named tailwind.js. The error in the console is:

_Error: Specified Tailwind config file "/Projects/my-project/tailwind.js" doesn't exist._

You can rename the file to match what it expects or you can change the line where it's hardcoded in the file /node_modules/laravel-mix-tailwind/index.js (line 14).

After Webpack finishes compiling, if you check the file public/app.css you can see there are a lot of classes in it (it will have more than 65k lines!). That's Tailwind being added to your project. Now if you include the app.css file in your views, you'll be able to use all the Tailwind classes 💪 .

Adding PurgeCSS to your Laravel 7 project

One of the inconveniences of Tailwind CSS is its size. As it has so many classes the size of the whole library is very big but we can use purgeCSS to remove all classes we are not using in our project. Similar to what we did to install Tailwind, we need to install a Laravel Mix plugin, in this case with the command npm i laravel-mix-purgecss --save-dev. Once installed, we need to add a few lines to our webpack.mix.js file:

const mix = require('laravel-mix')

// for Tailwind: https://github.com/JeffreyWay/laravel-mix-tailwind
require('laravel-mix-tailwind')

// for PurgeCSS
require('laravel-mix-purgecss')

mix
  .js('resources/js/app.js', 'public/js')
  .sass('resources/sass/app.scss', 'public/css')
  // .less('resources/less/app.less', 'public/css')
  .tailwind()
  .purgeCss({
    enabled: mix.inProduction(),
    folders: ['src', 'templates'],
    extensions: ['twig', 'html', 'js', 'php', 'vue'],
  })
  .setPublicPath('public')

With this configuration, we'll only run purgeCSS when we generate our production build with npm run prod. Go ahead and run it and compare the file sizes with the ones generated with npm run dev . In my case, the difference in the app.css file is 3.59Kb in production and 1.23Mb in development. That'll make a huge difference in the loading time of our web!

NOTE: if you want to add a more specific config to purgeCSS, you can create a file named postcss.config.js as detailed in this link.

Hope you find this useful. I've uploaded a scaffolded project to this public repo in GitHub so you can just clone it and start using it as the base for your next project. Just remember to follow the instructions in the Readme to install all dependencies!

Happy coding!