Tailwind 3.x config: should the legacy purge key be kept or fully replaced by content

The Short Answer

In Tailwind CSS 3.x, you should fully replace the purge key with the content key. The purge key is a legacy artifact from version 2.x and is deprecated in version 3.x. New projects should standardize on content only to ensure configuration clarity and avoid potential debugging hurdles during production builds.

Technical Explanation

The shift from purge to content represents a fundamental change in how Tailwind handles CSS generation. In version 2.x, Tailwind generated a massive set of all possible utilities and then used PurgeCSS (via the purge key) to remove unused ones. In version 3.x, the Just-in-Time (JIT) engine is the default; it scans your files and generates only the CSS you actually use.

Behavior When Both Keys Are Present

While Tailwind 3.x may maintain some backward compatibility to prevent immediate build failures during migrations, the JIT engine prioritizes the content array for generating the CSS bundle. If both keys are present with different globs, you risk creating a "split source of truth." This can lead to scenarios where a developer updates the purge array but notices no change in the production build because the engine is ignoring it in favor of the content array.

Standardization Steps

1. Audit: Compare the globs in your purge array against your content array. Ensure all paths to templates, components, and JavaScript files are captured in content.
2. Remove: Delete the purge key entirely from tailwind.config.js.
3. Verify: Run a production build using the Tailwind CLI to confirm that no critical styles are missing.

// tailwind.config.js
module.exports = {
  // ✅ Use this
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
  ],
  // ❌ Remove this
  // purge: ['./src/**/*.html'], 
  theme: { 
    extend: {},
  },
  plugins: [],
}

Verification Command

To verify that your content configuration is working as expected, run a production build and check the output file size:

npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify

Diagnostic Detail Needed: Are you using any custom PurgeCSS plugins or a highly non-standard build pipeline (e.g., a legacy Webpack wrapper) that specifically expects the purge key for external post-processing?