How to upgrade an Astro JS project from Tailwind CSS v3 to Tailwind CSS v4

It’s been a while since the Tailwind Labs team anounced the release of Tailwind CSS v4, so let’s take a look on how yto upgrade and Astro JS project to Tailwind CSS v4 ( Alpha ). At least, with what we know so far.

What do we know so far

Tailwind CSS 4.0 offers big improvements for faster, easier web development with the new Oxide engine.

Tailwind CSS 4.0 brings several improvements for faster, more flexible development. It emphasizes a CSS-first approach, simplifying design system management without relying on JavaScript. With composable variants, you can easily combine styles, and automatic content detection applies styles without manual setup.

The new Oxide engine, built with Rust, improves performance with faster compilation times. Tailwind also supports modern features like cascade layers and container queries, while the integration of Lightning CSS simplifies setup and reduces complexity.

Let’s upgrade

Disclaimer: This is how I personally approach it, if you like or want to do it in different steps, go ahead and do so

1. First of all we are going to remove the @astrojs/tailwind package because it’s not compatible with Tailwind CSS v4.

npm uninstall @astrojs/tailwind

2. Let’s install Tailwind CSS and vite official plugin:

Install with npm

npm install --save-dev tailwindcss@next @tailwindcss/vite@next

Install with yarn

yarn add --dev tailwindcss@next @tailwindcss/vite@next

Install with pnpm

pnpm add -D tailwindcss@next @tailwindcss/vite@next

3. Now, we move on the the astro.config.mjs

Let’s make use of the plugin by adding it to our Astro configuration.

1. First, remove the import for the Tailwind CSS Integration (@astro/tailwind).
2. Then, inside the integrations, delete the tailwind() part.
3. If you have other integrations, keep them intact; only remove the Tailwind CSS integration.

import { defineConfig } from 'astro/config';
import tailwind from "@astrojs/tailwind"; 
import tailwindcss from '@tailwindcss/vite';  
export default defineConfig({  
  vite: {  
    plugins: [tailwindcss()],
  },
  integrations: [tailwind()] 
});

Now, we have all added on this file, we should go ahead and move on the the CSS file.

4. Working on the CSS file

No we are going to have to import Tailwind CSS in our CSS file, so we will do that in the src/styles/global.css file for example.

@tailwind base;
@tailwind components;
@tailwind utilities;
@import "tailwindcss";

Now that we have import Tailwind, we might have to make sure to import the plugins we are using, if we are. On the case of the forms and typography plugins we are goidn to do like this.

@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "tailwind-scrollbar-hide";

Just like how we defined them on the tailwind.config.js file, but only as one line for each import. You can now translate the tailwind.config.js to css and after that remove the file. From now on, we start using Tailwind CSS on our project.

Hope this helps, and you can get your project upgrade. But, hey, watch out because it’s on alpha, and there’s many changes coming up. For example, 2xl:width might be deprecated, and we might have to use 2xl:max-w-[var(--breakpoint-2xl)] instead, like Admam Wathan said on this comment

/Michael Andreuzza