How to Set Up Tailwind CSS v4 in an Astro Project (2026)

Tailwind CSS v4 changed enough about its setup that a lot of guides still floating around the internet are quietly wrong for the version you are about to install. There is no tailwind.config.js by default anymore, no @astrojs/tailwind package, and no npx tailwindcss init. If you followed an older tutorial and hit a confusing error about a missing PostCSS config, this is why.

Here is the setup that actually matches Tailwind v4, plus a few things about theming and utility conflicts that the official docs mention only in passing.

The quick path

Astro can wire this up for you:

npx astro add tailwind

On Astro 5.2 or newer, this installs tailwindcss and @tailwindcss/vite, adds the plugin to your Vite config, and creates a starter stylesheet with the one line Tailwind v4 actually needs. It is a reasonable default if you want to skip straight to writing utility classes.

The manual setup

If you would rather see every step, or you are adding Tailwind to a project that already has opinions about its Vite config, here is what astro add does under the hood.

1. Install the packages.

npm install tailwindcss @tailwindcss/vite

2. Add the Vite plugin in astro.config.mjs.

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

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

That is the entire Astro-side configuration. There is no separate tailwind.config.js to create and no astro.config.mjs integrations entry - Tailwind v4 plugs directly into Vite.

3. Import Tailwind in your global stylesheet.

@import "tailwindcss";

4. Import that stylesheet once, in your base layout.

---
import "~/styles/global.css";
---

Run astro dev, and Tailwind’s utility classes work anywhere in your components. No build step to remember, no watch process to keep alive separately - it rides along with Vite’s own dev server.

CSS-first theming: the @theme block

The bigger change in v4 is where your design tokens live. In v3, colors, fonts and spacing lived in a JavaScript tailwind.config.js. In v4, they live in CSS, inside an @theme block in the same stylesheet where you imported Tailwind:

@import "tailwindcss";

@theme {
  --font-sans: "Geist Variable", Arial, sans-serif;
  --font-mono: "Geist Mono Variable", monospace;
  --color-ink: #080808;
  --color-paper: #f1f1ef;
  --color-accent: #b9402a;
}

Every variable in that block generates a matching utility automatically. --color-ink gives you bg-ink, text-ink and border-ink with no extra step, and --font-sans becomes the default font-sans stack. You can also reference the same variables directly in hand-written CSS with var(--color-ink), which keeps your design tokens in exactly one place instead of duplicated between a config file and your stylesheet.

A JavaScript config file still works if you need it - a Tailwind plugin, or configuration logic too complex for CSS variables - but for a typical marketing site or theme, the @theme block is the whole design system.

The gotcha most guides skip: prefixing against another CSS framework

If your project is Astro-only from a clean start, you can stop here. But if you are dropping Tailwind v4 into a project that already ships another CSS framework - Bootstrap is the common case when working from an HTML template - unprefixed Tailwind utilities and the existing framework’s classes will collide, and it fails silently. A class like flex might already mean something slightly different in the other framework’s CSS, and the one that loads last wins with no warning.

Tailwind v4 has a built-in fix: prefix every utility it generates.

@import "tailwindcss" prefix(tw);

With that in place, flex becomes tw:flex, gap-4 becomes tw:gap-4, and so on for every utility Tailwind generates. It costs you a few extra characters per class, but it means Tailwind and an inherited framework can share a codebase with zero collisions instead of a debugging session spent figuring out why a layout looks subtly wrong. Worth reaching for the moment you are integrating Tailwind into an existing template rather than a blank Astro project.

What you get for free with a theme

Every current AeroLaunch theme, including the two newest, Axial and Form Lab, ships with this exact setup already done - the Vite plugin wired in, the @theme block populated with the theme’s real palette and fonts, and prefixing applied on the themes that need it. If you would rather start from a finished design than an empty global.css, that setup work is one of the things you are buying.

Upgrading an existing Tailwind v3 project

Moving an older project from v3 to v4 is a bigger job than this guide covers on its own - v4 also changes some utility names and default values - but the CSS-first direction is the same: move your tailwind.config.js theme values into an @theme block, drop @astrojs/tailwind in favor of @tailwindcss/vite, and replace the old @tailwind base; @tailwind components; @tailwind utilities; trio with a single @import "tailwindcss";. Tailwind’s own upgrade tool (npx @tailwindcss/upgrade) handles most of the mechanical parts of that move automatically.