Tailwind v4 + Vite: Complete Setup Template in 5 Minutes

Introduction

Last year, while configuring Tailwind for a new project, I spent half an hour tweaking the content paths in tailwind.config.js. I couldn’t help thinking: can this be simpler?

Turns out, Tailwind v4 delivered exactly that this year.

Now you can get a fully functional Tailwind project running with just three lines of code—no PostCSS configuration, no tailwind.config.js, and no need to manually specify which files to scan. When I first saw this change, honestly, I was a bit skeptical.

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

This article will save you that half-hour of frustration. I’ll give you a complete template, plus a directory structure I’ve been using for six months that works really well.

1. Why Choose Tailwind v4 + Vite?

1.1 Is v4 Really That Fast?

The official claim is a 10x improvement in build speed. I tested it myself—a medium-sized project went from 8 seconds to under 1 second. This improvement comes from the new Oxide engine—written in Rust, need I say more?

But what made me happier is the simplified configuration. Before, when I started a new Tailwind project, I had to modify three or four files: tailwind.config.js, postcss.config.js, Vite config, plus the @tailwind directives in my CSS files. Now? Just one file is enough.

1.2 Vite’s Speed Is No Joke

Vite’s dev server starts almost instantly. Hot module replacement (HMR) is also super fast—changing CSS and refreshing the page feels practically seamless. This improvement in daily development experience is, honestly, something you can’t go back from once you’ve tried it.

1.3 v3 vs v4: A Clear Comparison

Hold on, let’s look at this table first:

See the pattern? v4’s core philosophy is moving configuration from JS to CSS. What does this mean? You can tweak settings while writing styles without jumping back and forth between files.

2. 5-Minute Quick Setup Template

Ready? Let’s begin.

2.1 Project Initialization

Open your terminal and run these commands:

# Create a new Vite project with TypeScript template
npm create vite@latest my-project -- --template vanilla-ts

# Navigate into the project directory
cd my-project

# Install dependencies
npm install

This step takes about 30 seconds.

2.2 Install Tailwind v4

# Install Tailwind CSS and the official Vite plugin
npm install tailwindcss @tailwindcss/vite

That’s it. No postcss, no autoprefixer—v4 has them built-in.

2.3 Configure Vite

Open vite.config.ts and modify it like this:

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  // Just add the Tailwind plugin
  plugins: [tailwindcss()],
})

Three lines of code. Really, it’s that simple.

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

2.4 Create CSS File

Create main.css in src/styles/:

/* src/styles/main.css */

/* Import Tailwind — this single line handles all base styles */
@import "tailwindcss";

/* Custom theme configuration (optional) */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
}

The @theme block is v4’s new syntax. You can define your own colors, fonts, spacing, and more inside it using CSS variables. It’s much more intuitive than writing tailwind.config.js.

2.5 Import CSS

Open src/main.ts and add this line at the top:

// src/main.ts
import './styles/main.css'

// Your existing code...

2.6 Test It Out

Try this in your index.html or a page component:

<div class="bg-primary text-white p-4 rounded-lg">
  Tailwind v4 is running!
</div>

Then run:

npm run dev

Open your browser—if you see a blue card, configuration is successful. I’ve timed it, and it really does run within 5 minutes.

3. Recommended Directory Structure

Once your project is running, I recommend organizing your files like this:

3.1 Complete Directory Structure

my-project/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # Base UI components
│   │   │   ├── Button.ts
│   │   │   └── Input.ts
│   │   └── layout/           # Layout components
│   │       ├── Header.ts
│   │       └── Footer.ts
│   ├── styles/
│   │   ├── main.css         # Main entry point (imports Tailwind)
│   │   ├── components.css   # Component-related styles
│   │   └── utilities.css    # Custom utility classes
│   ├── utils/
│   │   └── helpers.ts
│   ├── pages/               # Page files (for multi-page apps)
│   ├── assets/              # Static assets
│   │   ├── images/
│   │   └── fonts/
│   ├── main.ts
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

3.2 Why Organize This Way?

components/ui/ holds base components—buttons, inputs, modals, and so on. These are highly reusable and don’t depend on specific business logic.

components/layout/ holds layout components—Header, Footer, Sidebar. These components handle the page skeleton, which has a different purpose than UI components.

styles/ keeps CSS separate. Since Tailwind v4, I prefer centralizing styles because all configuration lives in CSS, making it convenient to edit together.

utils/ holds utility functions—pure functions for date formatting, string processing, and the like.

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

3.3 How to Organize CSS Files

/* src/styles/main.css — Entry file */

/* Import Tailwind */
@import "tailwindcss";

/* Import other style files */
@import "./components.css";
@import "./utilities.css";

/* Global base styles */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }

  /* Default link styles */
  a {
    @apply text-primary hover:underline;
  }
}

@layer base is Tailwind’s layering mechanism for defining foundational styles. The advantage over writing body { ... } directly is that Tailwind handles specificity issues for you.

4. v3 Migration Checklist

If you have existing v3 projects to upgrade, just follow this checklist. I upgraded several projects recently and marked all the pitfalls I encountered.

4.1 Configuration File Migration

• Delete tailwind.config.js (if it only contains Tailwind configuration)
• Delete postcss.config.js (if only used for Tailwind)
• Add @import "tailwindcss" to your CSS file
• Update vite.config.ts to use the @tailwindcss/vite plugin

4.2 Dependency Updates

# Uninstall old dependencies
npm uninstall postcss autoprefixer tailwindcss

# Install new dependencies
npm install tailwindcss @tailwindcss/vite

• Run the uninstall command
• Run the install command
• Check package.json to confirm version numbers

4.3 Style Adjustments

• Replace @tailwind base; @tailwind components; @tailwind utilities; with @import "tailwindcss";
• Migrate theme configuration from tailwind.config.js to CSS @theme block
• Confirm custom utility classes still work properly

Theme Configuration Migration Example:

/* v3's tailwind.config.js */
module.exports = {
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

/* v4's main.css */
@theme {
  --color-primary: #3b82f6;
}

4.4 Testing and Validation

• Run npm run dev to check if dev environment works
• Run npm run build to check if production build succeeds
• Open pages to confirm no styles are missing
• Edit a CSS file and verify hot reload works

5. Common Issues and Solutions

These are the problems I encounter most frequently during upgrades and configuration.

5.1 Styles Not Applying

You wrote class="bg-primary" but the page is blank. What’s going on?

Troubleshooting Steps:

1. Open browser dev tools and check if the CSS file loaded successfully
2. Confirm you actually imported the CSS file in main.ts
3. Check if the plugin in vite.config.ts is configured correctly

I once ran into this because I forgot import './styles/main.css' in main.ts. A rookie mistake, but easy to overlook.

5.2 Hot Reload Not Working

Changed CSS, but the page doesn’t budge.

Troubleshooting Steps:

1. Confirm Vite version >= 5.0 (older versions have compatibility issues)
2. Try restarting the dev server
3. Clear browser cache or open an incognito window

If it still doesn’t work, check the console for errors. Sometimes other plugins cause conflicts.

5.3 CSS Bundle Too Large After Build

In production builds, the CSS file can end up being hundreds of KB.

Troubleshooting Steps:

1. Confirm you’re using the latest v4 version—older versions don’t tree-shake as cleanly
2. Check if you imported an entire icon library or other large dependencies
3. Use @layer to organize styles—Tailwind will handle specificity and deduplication better

Honestly, in most cases, v4’s output is already quite lean. If it’s still too large, chances are you’re writing too much in your CSS.

Summary

After all that, here are the core takeaways:

1. Install: npm install tailwindcss @tailwindcss/vite
2. Configure Vite: Add the tailwindcss() plugin
3. Write CSS: @import "tailwindcss" + @theme for theme configuration
4. Run it: npm run dev

The biggest change in v4 compared to v3 is moving configuration from JS to CSS. It might feel unfamiliar at first, but after using it for a while, I found it more intuitive—you tweak configuration while writing styles, no need to jump between files.

If you’re migrating from v3, remember to translate your tailwind.config.js theme configuration to CSS @theme syntax. While it takes some time, you get faster builds and a cleaner project structure in return—it’s a trade-off that’s worth it every time.

7 min read · Published on: Mar 25, 2026 · Modified on: Mar 25, 2026

Easton

Technology