Migrating Our VitePress Blog to Tailwind CSS Version 4

Since the first episode of this series, Tailwind CSS has released a new major version, bringing numerous new features and enhancements. In this episode, we will migrate our VitePress blog to Tailwind CSS 4.0. This process is simpler than you might think and will enable us to utilize the latest features of Tailwind CSS while keeping our blog up-to-date.

Upgrading Dependencies ​

First, we need to upgrade our dependencies. To do this, I love using taze, but since we are only updating Tailwind CSS, we can do it manually. Open your package.json file and update the following dependencies:

{
  "devDependencies": {
    "tailwindcss": "^4.1.5", 
    "@tailwindcss/vite": "^4.1.5", 
    "autoprefixer": "^10.4.20", 
    "postcss": "^8.5.1"
  }
}

Then, run the following command to install the new dependencies:

pnpm install

There are multiple things to note with this change. First, there is a new dependency called @tailwindcss/vite, which is the new Vite plugin for Tailwind CSS, simplifying the installation process. Additionally, the autoprefixer and postcss dependencies are now unnecessary.

This means that the postcss.config.cjs file can be safely removed, as Tailwind CSS now relies on Vite for CSS processing. This change enhances both performance and developer experience—one of the best features of this new version.

Using the New Vite Plugin ​

A new Vite plugin means we need to update our VitePress configuration to use it. Open your .vitepress/config.mts file and update the following code:

import Tailwind from '@tailwindcss/vite'
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    plugins: [
      Tailwind() 
    ]
  }
})

And that's it!

Updating the Tailwind CSS Usage ​

Now that we've updated our dependencies and VitePress configuration, we need to update the usage of Tailwind CSS in our app.css file. In its latest version, Tailwind CSS has moved to a CSS-based configuration, streamlining the installation process. This means we need to update our app.css file.

From:

@tailwind base;
@tailwind components;
@tailwind utilities;

To:

@import 'tailwindcss';

Instead of relying on custom CSS directives, we can now use the native directive @import to incorporate Tailwind CSS.

Then, we migrate our configuration to the new CSS-based configuration.

@config "../../../../tailwind.config.cjs";

@plugin "@tailwindcss/typography";

@source '../../../../src/**/*.md';
@source '../../**/*.{vue,ts}';

In theory, we could completely remove the current JavaScript configuration file, but since we are using the @tailwindcss/typography plugin, we need to keep it.

However, we can still remove the content and plugins properties from the configuration file.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.md', './.vitepress/theme/**/*.{vue,ts}'], 
  theme: {
    extend: {
      typography: {
        // ...
      },
    },
  },

  plugins: [require('@tailwindcss/typography')], 
}

And that's it! We are now using the latest version of Tailwind CSS in our VitePress blog!

I hope you enjoyed this overview of the migration that ensures our blog stays updated to enable us to use the latest features of Tailwind CSS.