vannsl.io | Blog

Configuring TailwindCSS for Sapper

This article is Part III of my first three posts about Svelte. Part I described how to create Statically generated website with Svelte and Sapper. Part II discusses Svelte Single File Components in more detail.

In this article we will configure TailwindCSS for Svelte + Sapper.

Versions:

TL;DR

I forked the official sapper-template repository. It includes the integration of TailwindCSS, PostCSS and PurgeCSS. You can install the sapper-tailwindcss-template repository. Then you don't have to go through the Step by Step Guide below. To use it, execute the following commands:

npx degit "vannsl/sapper-tailwindcss-template#rollup" sapper-tailwindcss-template
# or
npx degit "vannsl/sapper-tailwindcss-template#webpack" sapper-tailwindcss-template
cd sapper-tailwindcss-template
npm install

To start the local server and watch tailwind, execute these two commands in separated windows of your terminal:

npm run dev:tailwindcss
npm run dev

Existing methods

On Github, there already exists a TailwindCSS Setup Example for Sapper. Although the general setup works, I had problems with PurgeCSS. The not used CSS of the TailwindCSS Framework was not removed when exporting a static version of my Sapper application. Maybe I did something wrong.

I did a bit of research and after a few try and error approaches, I finally got it to work. Here's the Step by Step Guide:

Step by Step Guide

In the following, we'll install Sapper and TailwindCSS.

Create a Sapper app

The following commands will install the example project for Sapper using the Rollup Configuration:

npx degit "sveltejs/sapper-template#rollup" sapper-tailwindcss
# or
npx degit "sveltejs/sapper-template#webpack" sapper-tailwindcss
cd sapper-tailwindcss
npm install

Now your Sapper application is installed. Run npm run dev to start the local server. Open http://localhost:3000 to check out the example project.

Alt Text

Download TailwindCSS, PostCSS and PurgeCSS

The following commands will download the packages for PostCSS and TailwindCSS as devDependencies and PurgeCSS as a dependency:

npm install -D postcss-cli tailwindcss --save
npm install @fullhuman/postcss-purgecss --save

Create the Configurations

The order of the following steps is not important. It will only work when all of the following changes are implemented.

tailwind.config.js

Afterward, initialize TailwindCSS with:

npx tailwind init

This command creates the file tailwind.config.js in the root directory of your project. It contains the following skeleton:

// tailwind.config.js

module.exports = {
  theme: {
    extend: {}
  },
  variants: {},
  plugins: []
}

For more information on how to customize TailwindCSS, please read the official TailwindCSS configuration documentation. You can leave it for now as it is.

postcss.config.js

Create an empty file with the name postcss.config.js. Either by creating this file in your IDE or finder or by executing the following command (if macOS) in the root folder of the sapper application:

touch postcss.config.js

Afterward, append the following content to the file:

// postcss.config.js

const tailwindcss = require("tailwindcss");

const purgecss = require("@fullhuman/postcss-purgecss")({
  content: ["./src/**/*.svelte", "./src/**/*.html"],
  defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || []
});

module.exports = {
  plugins: [
    tailwindcss("./tailwind.config.js"),

    ...(process.env.NODE_ENV === "production" ? [purgecss] : [])
  ]
};

rollup.config.js/webpack.config.js

Nothing to do. I added that section here because other approaches include adding PostCSS to the rollup config. There is no need to do this when using the approach of this post.

static/tailwind.css

Now it's time to add the TailwindCSS Styles to your project. Create a new CSS file in the statics directory.

cd static
touch tailwind.css

To import the TailwindCSS Styles, the rules have to be applied in this file:

/* static/tailwind.css */

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

The name of the CSS file is not important. It's best practice to use names like tailwind.css, main.css or global.css. Since the skeleton project of Sapper already provides a global.css, this tutorial recommends to use the name tailwind.css to prevent conflicts. When using a Utility-Based CSS Framework the styles of the preconfigured global.css may not be needed. If you want to, you can also use this file and override the default settings.

Note: This file can be used either for only adding TailwindCSS to the Sapper project or be extended with further global rules and styles. For example, custom CSS classes or Font Faces can be registered here.

package.json

Mostly done. To get the TailwindCSS CSS into the built application for dev and production mode, the following npm scripts in the package.json have to be added:

// package.json

// ...
scripts: {
 // ...
 "dev:tailwindcss": "postcss static/tailwind.css -o static/main.css -w",
 "build:tailwindcss": "NODE_ENV=production postcss static/tailwind.css -o static/main.css",
 // ...
}
// ...

These commands will create (or override if already existing) the file main.css in the static folder. The first command dev:tailwindcss will create a CSS file including all of the TailwindCSS styles. Any change in your source code will be immediately applied to the website with hot module replacement. When executing PostCSS in the production environment with NODE_ENV=production the file main.css will include only the styles of TailwindCSS you're using in your application thanks to PurgeCSS. If you try out both versions, you should see a significant difference in the file size of main.css.

You don't need to name that file main.css. You can choose any name that's not taken yet in your project. In the next section, we'll import the built CSS file in our application. But first, we'll add the statement to execute build:tailwindcss when building or exporting the Sapper application. Therefore add npm run build:tailwindcss && at the beginning of the build and export scripts:

// package.json for rollup

// ...
scripts: {
 // ...
 // "dev:tailwindcss": "postcss static/tailwind.css -o static/main.css -w",
 // "build:tailwindcss": "NODE_ENV=production postcss static/tailwind.css -o static/main.css",
 "build": "npm run build:tailwindcss && sapper build --legacy",
 "export": "npm run build:tailwindcss && sapper export --legacy",
 // ...
}
// ...


// package.json for webpack

// ...
scripts: {
 // ...
 // "dev:tailwindcss": "postcss static/tailwind.css -o static/main.css -w",
 // "build:tailwindcss": "NODE_ENV=production postcss static/tailwind.css -o static/main.css",
 "build": "npm run build:tailwindcss && sapper build",
 "export": "npm run build:tailwindcss && sapper export",
 // ...
}
// ...

.gitignore

If you've initialized a git repository, I recommend to add /static/main.css to your .gitignore file. For example, that's how the .gitignore of the Demo Git Repository looks like:

.DS_Store
/node_modules/
/src/node_modules/@sapper/
yarn-error.log
/cypress/screenshots/
/__sapper__/
/static/main.css

src/template.html

To import the generated main.css file, add the following line in the file src/template.html just above the other import:

<!-- src/template.html -->

<link rel="stylesheet" href="main.css">

Running the project

To run the application in production more, execute npm run build. To generate the static site of the application, run npm run export. By adding npm run build:tailwindcss to these scripts in the package.json, the commands will automatically generate the file main.css.

To run the project locally, execute the following commands in separated windows of your terminal:

npm run dev:tailwindcss
npm run dev

👏 That's it. You're done. 👏