Optimizing for Production

Removing unused CSS from your production builds for maximum performance.

Overview

Using the default configuration, the development build of Tailwind CSS is 3645.2kB uncompressed, 294.2kB minified and compressed with Gzip, and 72.8kB when compressed with Brotli.

This might sound enormous but the development build is large by design.

To make the development experience as productive as possible, Tailwind generates thousands of utility classes for you, most of which you probably won’t actually use.

Think of Tailwind like a giant box of LEGO — you dump it all out on the floor and build what you want to build, then when you’re done you put all the pieces you didn’t use back into the box.

For example, Tailwind generates margin utilities for every size in your spacing scale, for every side of an element you might want to apply margin to, at every breakpoint you are using in your project. This leads to hundreds of different combinations that are all important to have available, but not all likely to be needed.

When building for production, you should always use Tailwind’s purge option to tree-shake unused styles and optimize your final build size. When removing unused styles with Tailwind, it’s very hard to end up with more than 10kb of compressed CSS.

Writing purgeable HTML

Before getting started with the purge feature, it’s important to understand how it works and build the correct mental model to make sure you never accidentally remove important styles when building for production.

PurgeCSS (the library we use under the hood) is intentionally very naive in the way it looks for classes in your HTML. It doesn’t try to parse your HTML and look for class attributes or dynamically execute your JavaScript — it simply looks for any strings in the entire file that match this regular expression:

/[^<>"'`\s]*[^<>"'`\s:]/g

This basically matches any string separated by spaces, quotes or angle brackets, including HTML tags, attributes, classes, and even the actual written content in your markup.

<div class="md:flex">
  <div class="md:flex-shrink-0">
    <img class="rounded-lg md:w-56" src="/img/shopping.jpg" alt="Woman paying for a purchase">
  </div>
  <div class="mt-4 md:mt-0 md:ml-6">
    <div class="uppercase tracking-wide text-sm text-indigo-600 font-bold">
      Marketing
    </div>
    <a href="/get-started" class="block mt-1 text-lg leading-tight font-semibold text-gray-900 hover:underline">
      Finding customers for your new business
    </a>
    <p class="mt-2 text-gray-600">
      Getting a new business off the ground is a lot of hard work.
      Here are five ideas you can use to find your first customers.
    </p>
  </div>
</div>

That means that it is important to avoid dynamically creating class strings in your templates with string concatenation, otherwise PurgeCSS won’t know to preserve those classes.

Don’t use string concatenation to create class names

<div class="text-{{  error  ?  'red'  :  'green'  }}-600"></div>

Do dynamically select a complete class name

<div class="{{  error  ?  'text-red-600'  :  'text-green-600'  }}"></div>

As long as a class name appears in your template in its entirety, PurgeCSS will not remove it.

Removing unused CSS

Basic usage

To get started, provide an array of paths to all of your template files using the purge option:

// tailwind.config.js
module.exports = {
  purge: [
    './src/**/*.html',
    './src/**/*.vue',
    './src/**/*.jsx',
  ],
  theme: {},
  variants: {},
  plugins: [],
}

This list should include any files in your project that reference any of your styles by name. For example, if you have a JS file in your project that dynamically toggles some classes in your HTML, you should make sure to include that file in this list.

When using important with the selector strategy, be sure that the template file that includes your root selector is included in your purge configuration, otherwise all of your CSS will be removed when building for production.

Now whenever you compile your CSS with NODE_ENV set to production, Tailwind will automatically purge unused styles from your CSS.

Enabling manually

If you want to manually control whether unused styles should be removed (instead of depending implicitly on the environment variable), you can use an object syntax and provide the enabled option, specifying your templates using the content option:

// tailwind.config.js
module.exports = {
  purge: {
    enabled: true,
    content: ['./src/**/*.html'],
  },
  // ...
}

We recommend only removing unused styles in production, as removing them in development means you need to recompile any time you change your templates and compiling with PurgeCSS enabled is much slower.

Safelisting specific classes

If you need to safelist specific classes to make sure they are never accidentally removed from your CSS (perhaps because they are used in content that comes from a database or similar), you can use our top-level safelist option:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.html'],
    safelist: [
      'bg-blue-500',
      'text-center',
      'hover:opacity-100',
      // ...
      'lg:text-right',
    ]
  },
  // ...
}

Transforming content

Sometimes you are authoring content in a format that compiles to HTML, and it would be better to compile that content to HTML before looking for potential classes. A great example of this is working with markdown files.

You can use the transform option to tell Tailwind to transform any file matching a specific extension before it looks for classes to guarantee the most accurate results:

// tailwind.config.js
let remark = require('remark')
module.exports = {
  purge: {
    content: ['./src/**/*.{html,md}'],
    transform: {
      md: (content) => {
        return remark().process(content)
      }
    }
  },
  // ...
}

Customizing extraction logic

If you need to override the logic Tailwind uses to detect classes in the content of a specific file type, you can use the extract option to provide a function that will be used to detect potential classes in matching files:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.{html,md}'],
    extract: {
      md: (content) => {
        return content.match(/[^<>"'`\s]*/)
      }
    }
  },
  // ...
}

This is an advanced feature and most users won’t need it. The default extraction logic in Tailwind works extremely well for almost all projects.

Preserving HTML elements

By default, Tailwind will preserve all basic HTML element styles in your CSS, like styles for the html, body, p, h1, etc. tags. This is to minimize accidentally over-purging in cases where you are using markdown source files for example (where there is no actual h1 tag present), or using a framework that hides the document shell (containing the html and body tags) somewhere in a vendor directory (like Next.js does).

If you want to disable this behavior, you can set preserveHtmlElements to false:

// tailwind.config.js
module.exports = {
  purge: {
    preserveHtmlElements: false,
    content: ['./src/**/*.html'],
  },
  // ...
}

We generally do not recommend this and believe that the risks outweigh the benefits, but we’re not the cops, do whatever you want.

Purging specific layers

By default, Tailwind will purge all styles in the base, components, and utilities layers. If you’d like to change this, use the layers option to manually specify the layers you’d like to purge:

// tailwind.config.js
module.exports = {
  purge: {
    layers: ['components', 'utilities'],
    content: ['./src/**/*.html'],
  },
  // ...
}

Removing all unused styles

By default, Tailwind will only remove unused classes that it generates itself, or has been explicitly wrapped in a @layer directive. It will not remove unused styles from third-party CSS you pull in to your project, like a datepicker library you pull in for example.

/* These styles will all be purged */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* These styles will be purged */
@layer components {
  .btn { /* ... */ }
}
/* These styles will not be purged */
.flatpickr-innerContainer { /* ... */ }
.flatpickr-weekdayContainer { /* ... */ }
.flatpickr-weekday { /* ... */ }

This is to avoid accidentally removing styles that you might need but are not directly referenced in your templates, like classes that are only referenced deep in your node_modules folder that are part of some other dependency.

If you really want to remove all unused styles, set mode: 'all' and preserveHtmlElements: false and be very careful to provide the paths to all files that might reference any classes or HTML elements:

// tailwind.config.js
module.exports = {
  purge: {
    mode: 'all',
    preserveHtmlElements: false,
    content: [
      './src/**/*.js',
      './node_modules/flatpickr/**/*.js',
    ],
  },
  // ...
}

We do not recommend this, and generally find you get 99% of the file size benefits by sticking with the more conservative default approach.

Removing unused keyframes

PurgeCSS does not remove unused @keyframes rules by default, so you may notice some animation related styles left over in your stylesheet even if you aren’t using them. You can remove these using PurgeCSS’s keyframes option under options:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.html'],
    options: {
      keyframes: true,
    },
  },
  // ...
}

PurgeCSS options

If you need to pass any other options directly to PurgeCSS, you can do so using options:

// tailwind.config.js
module.exports = {
  purge: {
    content: ['./src/**/*.html'],
    // These options are passed through directly to PurgeCSS
    options: {
      safelist: ['bg-red-500', 'px-4'],
      blocklist: [/^debug-/],
      keyframes: true,
      fontFace: true,
    },
  },
  // ...
}

A list of available options can be found in the PurgeCSS documentation.

Alternate approaches

If you can’t use PurgeCSS for one reason or another, you can also reduce Tailwind’s footprint by removing unused values from your configuration file.

The default theme provides a very generous set of colors, breakpoints, sizes, margins, etc. to make sure that when you pull Tailwind down to prototype something, create a CodePen demo, or just try out the workflow, the experience is as enjoyable and fluid as possible.

We don’t want you to have to go and write new CSS because we didn’t provide enough padding helpers out of the box, or because you wanted to use an orange color scheme for your demo and we only gave you blue.

This comes with a trade-off though: the default build is significantly heavier than it would be on a project with a purpose-built configuration file.

Here are a few strategies you can use to keep your generated CSS small and performant.

Limiting your color palette

The default theme includes a whopping 84 colors used for backgrounds, borders, text, and placeholders, all of which also have hover: and focus: variants, as well as responsive variants at the six default screen sizes.

By default, there are thousands of classes generated to accommodate these colors, and it makes up close to half of the final build size.

Very few projects actually need this many colors, and removing colors you don’t need can have a huge impact on the overall file size.

Here’s how using a smaller color palette affects the final size:

Removing unused breakpoints

Since almost every Tailwind utility is copied for every screen size, using fewer screen sizes can have a huge impact on the overall file size as well.

Here’s how defining fewer screens affects the output:

If you only need 3 screen sizes and 35 colors, you’re down to 46.8kB compressed without changing anything else.

Disabling unused core plugins and variants

If you don’t expect to need a certain utility plugin in your project at all, you can disable it completely by setting it to false in the corePlugins section of your config file:

// tailwind.config.js
module.exports = {
  // ...
  corePlugins: {
    float: false
  }
}

If you only need a handful of utilities, you can pass an array to corePlugins with the utility plugins you want to keep.

// tailwind.config.js
module.exports = {
  // ...
  corePlugins: [
    'margin',
    'padding'
  ]
}

The above would disable all utilities except margin and padding.

If you need a utility but don’t need the responsive versions, set its variants to an empty array to generate 83% fewer classes:

module.exports = {
  // ...
  variants: {
    appearance: []
  }
}

These are mostly small wins compared to limiting your color palette or using fewer breakpoints, but they can still add up.

←Using with Preprocessors Browser Support→

Edit this page on GitHub