content key replaces purge in Tailwind CSS v3 with deprecation warning

In Tailwind CSS v3, the content configuration key replaces the legacy purge key. When both keys are present in tailwind.config.js, Tailwind prioritizes the content key and ignores the purge key for class generation. They are not merged.

Safelist Behavior

Safelist entries defined under the legacy purge key are not honored once you move to v3. To ensure classes are preserved, you must relocate all safelist entries to content.safelist. Any safelist configuration remaining under purge will be ignored and will trigger a deprecation warning.

Recommended Transition Configuration

To avoid duplicate scanning while keeping the deprecation warning visible as a migration reminder, you should move all active globs and safelists to content and leave the purge key empty. This prevents the engine from processing the same files twice while maintaining the terminal alert.

module.exports = {
  content: {
    // 1. Move all file globs here
    paths: ['./src/**/*.{html,js,ts,jsx,tsx}'], 
    // 2. Move safelist entries here
    safelist: ['bg-red-500', 'text-center'],
  },
  // Keep this empty to maintain the deprecation warning
  purge: [], 
}

Verification Steps

To verify your configuration is working correctly without duplicate processing:

1. Run your build command (e.g., npx tailwindcss -o build.css).
2. Confirm the deprecation warning appears in the terminal.
3. Inspect the output CSS to ensure classes from both your content globs and content.safelist are present.
4. Remove the purge key entirely to confirm the warning disappears without affecting the generated styles.

Assumptions and Constraints

This behavior applies to Tailwind CSS v3.x. In very early v3 releases, some users reported spurious warnings regarding duplicate scanning if globs overlapped between both keys; however, the engine still prioritized content. The safest approach across all v3 versions is to keep purge empty or removed.

Diagnostic Detail: Are you using a custom PostCSS plugin that specifically looks for the purge key? If so, moving to content may require updating that plugin's configuration separately.