Tailwind v4 + Astro: Use @tailwindcss/vite

Problem

Plan and documentation referenced @astrojs/tailwind integration and tailwind.config.mjs JavaScript config files. This is the Tailwind v3 approach. Tailwind v4 is fundamentally different.

Root Cause

Tailwind CSS v4 (released 2025) replaced:

• JS config files (tailwind.config.mjs) → CSS-first config (@import "tailwindcss")
• @astrojs/tailwind integration → @tailwindcss/vite Vite plugin

The Astro docs confirm: @astrojs/tailwind is for legacy Tailwind v3 only. Upgrading requires removing the integration and switching to the Vite plugin.

Solution

package.json dependencies:

{
  "devDependencies": {
    "@tailwindcss/vite": "^4",
    "tailwindcss": "^4"
  }
}

astro.config.mjs:

import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

CSS entry point (e.g., src/styles/global.css):

@import "tailwindcss";

/* Your custom CSS below */

No tailwind.config.mjs needed. Tailwind v4 configures everything through CSS.

Prevention

• When using Tailwind in a new project, always check the major version. v3 and v4 have incompatible setup approaches.
• Astro’s astro add tailwind command auto-detects the version and installs the correct integration.
• No JS config files (tailwind.config.mjs, tailwind.preset.js) are needed for Tailwind v4.