Skip to content
tailwind-performance logo

Tailwind CSS - Performance Optimization

tailwind-performance

Use when optimizing Tailwind CSS for production, reducing bundle size, and improving performance. Covers PurgeCSS, JIT mode, and build optimization.

TheBushidoCollective/han0installs199stars

SKILL.md

Full skill instructions

Tailwind CSS - Performance Optimization

Tailwind CSS includes powerful tools for optimizing your CSS for production, ensuring fast load times and minimal bundle sizes.

Key Concepts

Just-In-Time (JIT) Mode

JIT mode (default since Tailwind 3.0) generates styles on-demand as you author your templates:

Benefits:

  • Lightning-fast build times
  • All variants enabled by default
  • Arbitrary value support
  • Smaller development builds
  • No separate production build needed
// tailwind.config.js (JIT is default, no config needed)
module.exports = {
  content: ['./​src/​**/​*.{html,js,jsx,ts,tsx}'],
  // JIT mode is automatic
}

Content Configuration

Proper content paths are critical for performance:

module.exports = {
  content: [
    './​src/​**/​*.{js,jsx,ts,tsx}',
    './​pages/​**/​*.{js,jsx,ts,tsx}',
    './​components/​**/​*.{js,jsx,ts,tsx}',
    './​app/​**/​*.{js,jsx,ts,tsx}',
    // Include any files that contain Tailwind classes
    './​public/​index.html',
  ],
}

Best Practices

1. Optimize Content Paths

Be specific to avoid scanning unnecessary files:

// Good: Specific paths
module.exports = {
  content: [
    './​src/​**/​*.{js,jsx,ts,tsx}',
    './​components/​**/​*.{js,jsx,ts,tsx}',
  ],
}

// Bad: Too broad
module.exports = {
  content: [
    './​**/​*.{js,jsx,ts,tsx}', // Scans node_modules!
  ],
}

2. Use Safelist for Dynamic Classes

When class names are constructed dynamically, use safelist:

module.exports = {
  content: ['./​src/​**/​*.{js,jsx,ts,tsx}'],
  safelist: [
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    // Or use patterns
    {
      pattern: /​bg-(red|green|blue)-(400|500|600)/,
      variants: ['hover', 'focus'],
    },
  ],
}

3. Avoid String Concatenation

Don't construct class names dynamically:

// Bad: These classes won't be detected
<div className={`text-${size}`}>
<div className={`bg-${color}-500`}>

// Good: Use complete class names
<div className={size === 'large' ? 'text-lg' : 'text-sm'}>
<div className={color === 'red' ? 'bg-red-500' : 'bg-blue-500'}>

// Or use safelist for dynamic values

4. Minimize Custom CSS

Rely on utilities to reduce overall CSS size:

/​* Bad: Custom CSS that duplicates utilities */
.my-button {
  background-color: #3b82f6;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
}

/​* Good: Use utilities or @apply */
@layer components {
  .my-button {
    @apply bg-blue-500 text-white px-4 py-2 rounded-md;
  }
}

/​* Better: Component abstraction (no custom CSS) */

5. Enable CSS Minification

Ensure your build process minifies CSS:

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    ...(process.env.NODE_ENV === 'production' ? { cssnano: {} } : {})
  },
}

6. Use CSS Variables Strategically

Combine Tailwind with CSS variables for theme switching without bloat:

:root {
  --color-primary: 59 130 246; /​* RGB */
}

[data-theme='dark'] {
  --color-primary: 96 165 250;
}
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
      },
    },
  },
}

Build Optimization

Vite Configuration

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    postcss: './​postcss.config.js',
  },
  build: {
    cssMinify: 'esbuild', // Fast CSS minification
    rollupOptions: {
      output: {
        manualChunks: {
          // Separate vendor chunks
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
})

Next.js Configuration

// next.config.js
module.exports = {
  experimental: {
    optimizeCss: true, // Enable CSS optimization
  },
  // Next.js automatically optimizes Tailwind
}

Webpack Configuration

// webpack.config.js
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin')

module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin(),
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: '[name].[contenthash].css',
    }),
  ],
}

Performance Patterns

1. Code Splitting

Split CSS by route or component:

// Using dynamic imports
const HeavyComponent = lazy(() => import('./​HeavyComponent'))

// Tailwind classes in HeavyComponent will be in a separate chunk

2. Critical CSS

Extract critical CSS for above-the-fold content:

<!DOCTYPE html>
<html>
<head>
  <style>
    /​* Inline critical CSS */
    .hero { /​* ... */ }
    .nav { /​* ... */ }
  </​style>
  <!-- Load full CSS async -->
  <link rel="preload" href="/​styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
  <noscript><link rel="stylesheet" href="/​styles.css"></​noscript>
</​head>

3. Lazy Load Non-Critical Styles

// Load additional styles when needed
if (shouldLoadDarkMode) {
  import('./​dark-mode.css')
}

4. Font Optimization

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: [
          'Inter var',
          'system-ui',
          '-apple-system',
          'BlinkMacSystemFont',
          '"Segoe UI"',
          'Roboto',
          'sans-serif',
        ],
      },
    },
  },
}
/​* Use font-display for better loading */
@font-face {
  font-family: 'Inter var';
  font-style: normal;
  font-weight: 100 900;
  font-display: swap; /​* Prevent invisible text */
  src: url('/​fonts/​inter-var.woff2') format('woff2');
}

Monitoring Performance

Bundle Size Analysis

# Analyze CSS bundle size
npx tailwindcss -i ./​src/​input.css -o ./​dist/​output.css --minify

# Check file size
ls -lh dist/​output.css

# Detailed analysis with webpack-bundle-analyzer
npm install --save-dev webpack-bundle-analyzer

Lighthouse Metrics

Target metrics:

  • First Contentful Paint (FCP): < 1.8s
  • Largest Contentful Paint (LCP): < 2.5s
  • Cumulative Layout Shift (CLS): < 0.1
  • CSS Bundle Size: < 50KB (gzipped)

Performance Checklist

✅ Content paths are specific and optimized
✅ JIT mode is enabled (default in Tailwind 3+)
✅ CSS is minified in production
✅ Unused styles are purged
✅ Dynamic classes use safelist
✅ Critical CSS is inlined
✅ Fonts use font-display: swap
✅ CSS is code-split by route/​chunk
✅ Gzip/​Brotli compression enabled
✅ CSS file has content hash for caching

Examples

Production Build Script

// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "build:css": "tailwindcss -i ./​src/​input.css -o ./​dist/​output.css --minify",
    "analyze": "npm run build && webpack-bundle-analyzer dist/​stats.json"
  }
}

Optimized Configuration

// tailwind.config.js
module.exports = {
  content: {
    files: [
      './​src/​**/​*.{js,jsx,ts,tsx}',
      './​components/​**/​*.{js,jsx,ts,tsx}',
    ],
    // Only in dev: watch for changes
    relative: process.env.NODE_ENV === 'development',
  },
  theme: {
    extend: {
      // Only extend what you need
      colors: {
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
      },
    },
  },
  plugins: [
    // Only include plugins you use
    require('@tailwindcss/​forms'),
  ],
  // Disable unused variants
  corePlugins: {
    // Disable unused features
    preflight: true,
    // Only enable what you need
  },
}

CDN vs Bundle Comparison

<!-- Bad: CDN (3.5MB+, not optimized) -->
<link href="https://cdn.jsdelivr.net/​npm/​tailwindcss@3/​dist/​tailwind.min.css" rel="stylesheet">

<!-- Good: Bundled & optimized (typically 5-20KB gzipped) -->
<link href="/​dist/​styles.css" rel="stylesheet">

Common Pitfalls

❌ Using CDN in Production

<!-- Never do this in production -->
<script src="https://cdn.tailwindcss.com"></​script>

The CDN build is 3.5MB+ and includes all utilities. Always use a build process.

❌ Overly Broad Content Paths

// Bad: Scans everything including node_modules
content: ['./​**/​*.html']

// Good: Specific to your source files
content: ['./​src/​**/​*.{html,js,jsx,ts,tsx}']

❌ Not Using Safelist for Dynamic Classes

// Bad: Class won't be included in build
const colors = ['red', 'blue', 'green']
<div className={`bg-${colors[index]}-500`} />

// Good: Use safelist or conditional classes

❌ Importing Full Tailwind in Components

// Bad: Imports all of Tailwind
import 'tailwindcss/​tailwind.css'

// Good: Import only what you built
import './​styles.css'

Anti-Patterns

❌ Don't Disable Purge in Production

// Bad: Never do this
module.exports = {
  content: [], // Empty = no purging!
}

❌ Don't Use @apply Excessively

/​* Bad: Defeating the purpose of utilities */
.btn { @apply px-4 py-2 bg-blue-500 text-white rounded; }
.card { @apply p-6 bg-white shadow-lg rounded-lg; }
.header { @apply flex items-center justify-between p-4; }
/​* ...hundreds of components */

/​* This negates Tailwind's optimization benefits */

❌ Don't Ignore Build Warnings

# Pay attention to warnings like:
# "The content option in your Tailwind CSS configuration is missing or empty"
# "No utility classes were detected in your source files"

Related Skills

  • tailwind-configuration: Customizing Tailwind config and theme
  • tailwind-utility-classes: Using Tailwind's utility classes effectively
  • tailwind-responsive-design: Building responsive designs efficiently

More skills from TheBushidoCollective

typescript-utility-types logo
TheBushidoCollective/han

typescript-utility-types

Use when typeScript utility types, mapped types, and advanced type manipulation. Use when creating flexible, type-safe TypeScript code.

199 0
View
shell-portability logo
TheBushidoCollective/han

shell-portability

Use when writing shell scripts that need to run across different systems, shells, or environments. Covers POSIX compatibility and platform differences.

199 0
View
figma-generate-component logo
TheBushidoCollective/han

figma-generate-component

Generate production-ready code from a Figma component or frame using the Figma MCP server

199 0
View
dialyzer-integration logo
TheBushidoCollective/han

dialyzer-integration

Use when integrating Dialyzer into development workflows and CI/CD pipelines for Erlang/Elixir projects.

199 0
View
rubocop-configuration logo
TheBushidoCollective/han

rubocop-configuration

Use when ruboCop configuration including YAML config, departments, inheritance, and customization.

199 0
View
elixir-otp-patterns logo
TheBushidoCollective/han

elixir-otp-patterns

Use when Elixir OTP patterns including GenServer, Supervisor, Agent, and Task. Use when building concurrent, fault-tolerant Elixir applications.

199 0
View
ameba-custom-rules logo
TheBushidoCollective/han

ameba-custom-rules

Use when creating custom Ameba rules for Crystal code analysis including rule development, AST traversal, issue reporting, and rule testing.

199 0
View
Swift Optionals Patterns logo
TheBushidoCollective/han

Swift Optionals Patterns

Use when swift's optional handling patterns including optional binding, chaining, nil coalescing, and modern approaches to safely working with optional values while avoiding common pitfalls and force unwrapping.

199 0
View
code-annotation-patterns logo
TheBushidoCollective/han

code-annotation-patterns

Use when annotating code with structured metadata, tags, and markers for AI-assisted development workflows. Covers annotation formats, semantic tags, and integration with development tools.

199 0
View
Scala Collections logo
TheBushidoCollective/han

Scala Collections

Use when scala collections including immutable/mutable variants, List, Vector, Set, Map operations, collection transformations, lazy evaluation with views, parallel collections, and custom collection builders for efficient data processing.

199 0
View
reactflow-custom-nodes logo
TheBushidoCollective/han

reactflow-custom-nodes

Use when creating custom React Flow nodes, edges, and handles. Covers custom node components, resizable nodes, toolbars, and advanced customization.

199 0
View
junit-fundamentals logo
TheBushidoCollective/han

junit-fundamentals

Use when jUnit fundamentals including annotations, assertions, and test lifecycle for Java testing.

199 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View