Tailwind CSS Academy · Lesson

Analyzing and Reducing Bundle Size

Measure your final CSS output size, identify unused styles slipping through, and tune your content globs for maximum purge efficiency.

Analyzing and Reducing Bundle Size is a free Tailwind CSS Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Tailwind CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Bundle Size Still Matters With JIT

Tailwind's JIT engine eliminates most unused CSS automatically, but bundle size can still grow if you are not careful. An improperly configured content glob can include too many files, a large safelist can add hundreds of classes, or complex arbitrary values can inflate the output.

Even a well-configured Tailwind project benefits from occasional bundle auditing to confirm the output is as small as it should be and to catch configuration issues before they reach production.

Measuring Your CSS Output Size

The first step in analyzing your bundle is knowing its current size. Build your Tailwind CSS in production mode and check the file size before and after minification and compression.

Use wc -c to check raw bytes, and compare the gzip-compressed size which is what browsers actually download. A well-optimized Tailwind production stylesheet is typically 5-15KB uncompressed and 2-5KB gzipped.

# Build production CSS
NODE_ENV=production npx tailwindcss -i input.css -o dist/output.css --minify

# Check uncompressed size
wc -c dist/output.css
# Example output: 12048 dist/output.css (12KB uncompressed)

# Check gzipped size
gzip -c dist/output.css | wc -c
# Example output: 3421 (3.4KB gzipped — excellent)

# If size > 50KB uncompressed, investigate further

Checking Content Glob Coverage

The most common cause of oversized Tailwind output is an overly broad content glob that scans too many files, including vendored libraries or generated output files that happen to contain CSS-class-like strings.

Accidentally including node_modules/** or your compiled output directory can cause JIT to generate thousands of spurious classes. Review each glob in your content array and ensure it only covers your actual source templates.

// BAD: Too broad — scans node_modules (thousands of spurious classes)
module.exports = {
  content: ['**/*.{html,js}'],  // matches ALL files including node_modules!
};

// GOOD: Scoped to your actual source directories
module.exports = {
  content: [
    './src/**/*.{html,js,ts,tsx}',
    './pages/**/*.{js,ts,tsx}',
    './components/**/*.{js,ts,tsx}',
    // Explicitly include specific external packages if needed:
    './node_modules/@headlessui/react/**/*.{js,ts}',
  ],
};

Auditing With PurgeCSS Reports

You can use PurgeCSS in analyze mode (separate from Tailwind's built-in scanning) to generate a report of which CSS selectors are being kept and which would be removed. This helps identify unexpected classes in your output.

Alternatively, search your compiled CSS file for class patterns that should not be there: if you see hundreds of bg- variants including colors you never use, check your safelist patterns — they may be generating more classes than intended.

# Install PurgeCSS CLI
npm install -g purgecss

# Run PurgeCSS on your built CSS
purgecss --css dist/output.css \
         --content './src/**/*.html' \
         --output dist/purged.css \
         --rejected-css dist/rejected.css

# Check rejected.css — classes in this file are in your built CSS
# but not found in your templates.
# If there are many, review your safelist and content configuration.

Identifying Safelist Bloat

A large or broad safelist is a common source of bundle bloat. Each pattern generates many classes. For example, /bg-(red|green|blue|yellow|purple|orange|pink|indigo|violet|teal|cyan|rose)-(50|100|200|300|400|500|600|700|800|900|950)/ generates 132 background color classes alone — even if you only use 10 of them.

Audit your safelist by counting the patterns and estimating how many classes each generates. Remove patterns you added speculatively and only keep those for known dynamic class use cases.

// Bloated safelist (generates hundreds of classes)
safelist: [
  { pattern: /bg-(red|green|blue|yellow|purple|orange|pink)-(100|200|300|400|500|600|700|800|900)/ },
  // ^ generates 63 classes
  { pattern: /text-(red|green|blue|yellow|purple|orange|pink)-(100|200|300|400|500|600|700|800|900)/ },
  // ^ another 63
]
// Total: 126+ extra classes from safelist alone

// Optimized safelist (only what's actually used dynamically)
safelist: [
  { pattern: /bg-(red|green|yellow|blue)-(100|500)/ }, // 8 classes
  { pattern: /text-(red|green|yellow|blue)-(700|800)/ }, // 8 classes
]

Removing Unused Base Styles

Tailwind's preflight (base CSS reset) adds approximately 4KB of base styles. If you are using Tailwind alongside a CSS framework that has its own reset, or if you are incrementally adopting Tailwind, you may want to disable preflight.

Set corePlugins: { preflight: false } in your config to remove the reset. This can save a few KB, especially in projects where the base styles conflict with existing CSS.

// tailwind.config.js — disable preflight
module.exports = {
  corePlugins: {
    preflight: false,
  },
  // OR: disable multiple core plugins to reduce output
  corePlugins: {
    preflight: false,     // Remove reset styles
    container: false,     // Remove .container utility if unused
    float: false,         // Remove float utilities if not used
    clear: false,
    skew: false,          // Remove skew transforms if not used
  },
}

Disabling Unused Core Plugins

You can disable entire groups of utilities that your project never uses to reduce the generated CSS. For example, a project with no CSS grid usage can disable the grid plugins. A project with no transforms can disable rotate, scale, skew, and translate.

Check your templates for utility prefixes you never use. Disabling a core plugin prevents all variants of those utilities from being generated, even if they somehow appear in the content scan (from template strings that resemble class names).

// tailwind.config.js
module.exports = {
  corePlugins: [
    // Whitelist approach: only enable plugins your project uses
    // (Empty array = disable ALL core plugins — not recommended unless you know exactly what you need)
    // Better: use the object form to disable specific ones
  ],
  // Object form: disable only specific plugins
  corePlugins: {
    // If your project doesn't use blur/backdrop-filter at all:
    backdropBlur: false,
    backdropBrightness: false,
    backdropContrast: false,
    backdropGrayscale: false,
    backdropHueRotate: false,
    backdropInvert: false,
    backdropOpacity: false,
    backdropSaturate: false,
    backdropSepia: false,
  },
}

Enabling CSS Compression

Beyond Tailwind's own minification (--minify), configure your build tool to apply additional CSS compression. Vite and webpack both support CSS minification via their built-in or plugin-based pipelines.

For maximum compression, combine CSS minification with Brotli compression on the server level. Brotli achieves 15-25% better compression than gzip on CSS files, reducing your effective payload further.

// vite.config.js — enable CSS minification
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    cssMinify: true,  // default in production mode
    cssCodeSplit: true, // split CSS per page in multi-page apps
  },
});

// next.config.js — Next.js minifies CSS automatically in production
// No extra configuration needed

Tree-Shaking Unused JavaScript in Tailwind Projects

In React and Vue projects, tree-shaking eliminates unused JavaScript, but it also affects how classes reach JIT. If a component is tree-shaken from the bundle, its class strings might not appear in the compiled JS, causing JIT to miss them.

The solution is to configure your content globs to point to source files (pre-tree-shake), not compiled output. JIT should always scan your source TypeScript/JavaScript files, not the compiled bundle.

// tailwind.config.js
module.exports = {
  content: [
    // Source files (correct): JIT sees all possible classes
    './src/**/*.{ts,tsx}',
    './src/**/*.{js,jsx}',

    // Compiled output (wrong): some classes may be missing
    // './dist/**/*.js', // Don't scan compiled output
  ],
}

Analyzing Bundle Size Over Time

Bundle size tends to grow gradually as features are added. Set up a CI check that measures CSS bundle size on every pull request and fails if it exceeds a threshold. This catches accidental safelist expansions or overly broad glob additions before they reach production.

Tools like bundlesize, size-limit, or a simple bash script comparing file sizes can integrate into your CI pipeline to enforce size budgets.

# .github/workflows/css-size-check.yml
# Build CSS and fail if it exceeds 20KB
npx tailwindcss -i input.css -o /tmp/tailwind.css --minify
CSS_SIZE=$(wc -c < /tmp/tailwind.css)
echo "CSS size: ${CSS_SIZE} bytes"
if [ ${CSS_SIZE} -gt 20480 ]; then
  echo "ERROR: CSS bundle exceeds 20KB limit (${CSS_SIZE} bytes)"
  exit 1
fi

Final Optimization Checklist

Before shipping a Tailwind project to production, run through this checklist:

NODE_ENV=production is set during the build
Content globs do not include node_modules broadly
Safelist patterns are narrow and documented
Unused core plugins are disabled in config
CSS is minified (Tailwind --minify flag or build tool)
Server compression (gzip or Brotli) is enabled
CSS file size is under your target budget (typically 15KB uncompressed)

# Full production optimization command
NODE_ENV=production npx tailwindcss \
  -i ./src/input.css \
  -o ./dist/tailwind.min.css \
  --minify

# Verify result
echo 'Uncompressed:' $(wc -c < ./dist/tailwind.min.css) 'bytes'
echo 'Gzipped:' $(gzip -c ./dist/tailwind.min.css | wc -c) 'bytes'

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

Lesson Recap

In this lesson you learned: CSS bundle size measurement using the production build with --minify and wc -c plus gzip inspection; content glob scoping to prevent JIT from scanning node_modules or output directories; and safelist auditing to ensure patterns are narrow and only cover genuinely dynamic class use cases. Next up we explore arbitrary values and their cost.

Frequently asked questions

Is the “Analyzing and Reducing Bundle Size” lesson free?

Yes — the full text of “Analyzing and Reducing Bundle Size” is free to read here on the web, and the Tailwind CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Tailwind CSS Academy course, upgrade to CoddyKit PRO.

What will I learn in “Analyzing and Reducing Bundle Size”?

Measure your final CSS output size, identify unused styles slipping through, and tune your content globs for maximum purge efficiency. You practise Tailwind CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Tailwind CSS Academy?

No prior experience is required. Tailwind CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Analyzing and Reducing Bundle Size” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Tailwind CSS Academy lesson?

Yes. Every Tailwind CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Tailwind CSS Academy