AdonisJS Quick Tip Lesson 4

How To Add TailwindCSS to a New AdonisJS Project

tomgobich avatar
tomgobich
5 min
Quick Summary

This lesson covers creating a new AdonisJS project that includes Webpack Encore, then adding and configuring PostCSS and TailwindCSS within the project.

If you’re here, I’m going to assume you know what both AdonisJS and TailwindCSS are and at least the basics of them, so let’s kick it!

Creating Our AdonisJS Project

First, we’re going to want to create a new AdonisJS project. I’ll be naming mine tailwindcss-example, feel free to name yours whatever you wish.

npm init adonis-ts-app@latest tailwindcss-example

Once you enter this command it’ll ask you a few questions so the project is generated to your liking. The only options we care about are the project structure and Webpack Encore. We’ll want to use the “web” project structure and you’ll want to select “yes” when asked if Webpack Encore should be configured. For everything else, please choose to your liking.

❯ Select the project structure · web
❯ Enter the project name · tailwindcss-example
❯ Setup eslint? (y/N) · yes/no, your preference
❯ Setup prettier? (y/N) · yes/no, your preference
❯ Configure webpack encore for compiling frontend assets? (y/N) · yes

Once this has been completed successfully you’ll see something similar to the below in your terminal.

RUNNING TASKS
❯ Scaffold project 40 ms
❯ Install dependencies 37 s
❯ Configure installed packages 1.22 s
❯ Configure webpack encore 14 s

[ success ]  Project created successfully

╭─────────────────────────────────────────────────╮
│    Run following commands to get started             │
│─────────────────────────────────────────────────│
│                                                      │
│    ❯ cd tailwindcss-example                          │
│    ❯ node ace serve --watch                          │
│                                                      │
╰─────────────────────────────────────────────────╯

Now that our project is created, lets change into it’s directory.

cd tailwindcss-example

Installing Required Dependencies

Once you’ve changed into your project directory, it’s time to install the required dependencies! First, since TailwindCSS uses PostCSS, we’ll want to install postcss-loader for Webpack so we can compile our TailwindCSS.

npm i -D postcss-loader

Then, we’ll need to also install TailwindCSS.

npm i -D tailwindcss

We’ll also want to have TailwindCSS generate its configuration file, which we can do by running the below.

npx tailwindcss init

This will generate the tailwind.config.js file within the root of our project.

Configuring PostCSS

Once we have our dependencies installed, it’s time to jump inside our project’s code. Let’s first jump into our webpack.config.js file at the root of our project. Go ahead and scroll down to about line 172 and uncomment Encore.enablePostCssLoader(). This will enable the postcss-loader we just installed within our Webpack configuration.

// webpack.config.js

// Encore.enablePostCssLoader() // 👈 uncomment this

Encore.enablePostCssLoader() // 👈 so it looks like this

Next, in order for PostCSS to know what plugins to use for our project, we’ll need to define a PostCSS configuration within our project. There are a few ways to go about this, today let’s just go with the default way of adding a postcss.config.js file to the root of our project. Then, within this file, we’ll want to define TailwindCSS as a plugin, like the below.

// postcss.config.js

module.exports = {
  plugins: [
    require('tailwindcss')()
  ]
}

That’s all we need to do to get PostCSS working within our project. Next, we’ll move on to TailwindCSS.

Configuring TailwindCSS

By default, when we start our server up TailwindCSS is going to to purge all the TailwindCSS classes not in-use within our project. So, we’ll want to define the content files it should check for class usages within our project. We can do this by defining template paths within our tailwind.config.js file’s content array, like the below.

// tailwind.config.js

module.exports = {
  content: [
    './resources/**/*.{edge,js,ts,vue,jsx,tsx}' // 👈
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

This will include all files within the resources directory ending with the extension edge, js, ts, vue, jsx, and tsx. Feel free to alter what I have here for your use case.

Lastly, we’ll want to add the TailwindCSS directives to our CSS file.

/* resources/css/app.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

AdonisJS starts us out with some boilerplate styles for the welcome page. Feel free to replace all of that boilerplate in your CSS file with the above.

Testing It Out

With that, TailwindCSS should now be fully set up within our project, congratulations! Next, let’s go ahead and boot our server up and test it out.

npm run dev

Once you run that you should see something like the below.

npm run dev                                                                                                                                                                   

# ❯ tailwindcss-example@1.0.0 dev
# ❯ node ace serve --watch

# [ info ]  building project...
# [ info ]  starting http server...
# [1641664665768] INFO (tailwindcss-example/30436 on toms-mbp.lan): started server on 0.0.0.0:3333
# [ encore ] Running webpack-dev-server ...
# [ info ]  watching file system for changes
# ╭────────────────────────────────────────────────────────╮
# │                                                             │
# │    Server address: <http://127.0.0.1:3333>                  │
# │    Watching filesystem for changes: YES                     │
# │    Encore server address: <http://localhost:8080>           │
# │                                                             │
# ╰────────────────────────────────────────────────────────╯
# [ encore ]  DONE  Compiled successfully in 586ms12:57:46 PM
# [ encore ] webpack compiled successfully
# UPDATE: public/assets/manifest.json
# UPDATE: public/assets/entrypoints.json

This is stating that our AdonisJS server has booted up successfully at http://localhost:3333. It’s also stating that our Webpack Encore server, which will serve our style and script assets, has successfully started at http://localhost:8080.

Now, the “web” project structure for AdonisJS conveniently comes out-of-the-box with our CSS and JavaScript file rigged up to our welcome page. So, we don’t need to do anything to get those working. We can jump straight into our page at http://localhost:3333.

Note this only happens when you also install Webpack Encore at the time your project is created.

You should see a bland page where all the test is in the top-right corner and all the text is the same size, despite the first line being an H1. If that’s what you see all is working well. All the text is the same size due to TailwindCSS’ CSS reset.

Testing A TailwindCSS Class

Just to be sure let’s do the infamous CSS test of making the text red. Go ahead and jump into the welcome page’s code at resources/views/welcome.edge and on the H1 element add the TailwindCSS class text-red-600.

{{-- resources/views/welcome.edge --}}

{{-- ... --}}

<main>
  <div>
    {{-- 👇 let's add the class 'text-red-600' to the h1 --}}
    <h1 class="title text-red-600"> It Works! </h1>
    <p class="subtitle">
      Congratulations, you have just created your first AdonisJS app.
    </p>
      
    {{-- ... --}}
  </div>
</main>

Once you save this change, the Webpack Encore will recognize the change and immediately reflect the change in your browser. So, go ahead and open your browser and you should now see the heading is a nice red color.

If that’s what you see then all is working well!

You can find the code for this lesson at our adonisjs-tailwindcss-example repository on GitHub.