Tailwind CSS 4 setup and differences from v3 — hands-on guide

You just read about Tailwind 4 and wonder what changed from version 3. You've probably seen posts talking about new features but not how to take action. At Meteora Web, we have already upgraded several projects from v3 to v4 and want to share our technical, hands-on perspective. Let's start with the concrete problem: official docs are still evolving, and many tutorials on YouTube rely on beta versions. If you don't want to waste time on configurations that will be outdated next month, this guide is for you.

What really changed in Tailwind 4

Tailwind CSS 4 is not just a feature update. It's a paradigm shift in how the framework runs and is configured. The old PostCSS + heavy tailwind.config.js approach has been replaced by a native Rust engine (Lightning CSS) that speeds up builds and simplifies customization. For us, who have seen clients wait seconds for CSS to regenerate in development, this means real time savings — and time, in our line of work, translates into revenue.

New Lightning CSS engine

Tailwind 4 integrates Lightning CSS instead of PostCSS. The result? 10x faster builds, built-in CSS nesting support, modern CSS imports, and automatic minification. You no longer need to install autoprefixer, postcss-import, or cssnano: everything is included. Speed is not a luxury — it's the difference between iterating quickly on a layout or losing focus while waiting for compilation.

Configuration without a config file

The most disruptive change: no more mandatory tailwind.config.js. Configuration happens directly in CSS via the @theme directive. Want to customize the primary color? Write:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
}

This syntax eliminates duplication between JS and CSS files, reduces errors, and makes the theme portable. For us, managing projects for multiple clients, it means sharing theme pieces across sites without getting tangled in JSON objects.

Utility syntax

Utility classes remain the same — flex, p-4, text-lg — but they have been rewritten to use CSS custom properties instead of hard-coded values. This allows overriding values at runtime via JavaScript or media queries, something that was only possible with advanced CSS tricks in v3.

Setting up a project with Tailwind 4

Here are the concrete steps to start today. Begin with an empty project. If you have an existing v3 project, skip to the differences section later.

Installation with npm

Open your terminal in the project folder and run:

npm install tailwindcss @tailwindcss/cli

Note: in v4 the CLI package is separate. If you use Vite, Next.js, or Laravel, there are dedicated plugins. For a simple project, the standalone CLI is the quickest path.

The main CSS file

Create a src/input.css file with this content:

@import "tailwindcss";

@theme {
  --font-sans: 'Inter', sans-serif;
  --color-brand: #2563eb;
}

Notice: you no longer need @tailwind base; @tailwind components; @tailwind utilities; — a single @import suffices.

Build and watch

Now run the build command:

npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

The --watch flag regenerates CSS on every change. Open dist/output.css and you'll see the result. Done. In under 5 minutes you have a working setup.

Practical differences between v3 and v4

Let's dive into the details of what changes when you write code or customize a theme.

Colors and theme customization

In v3 you had to write in tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#2563eb',
      }
    }
  }
}

In v4 you do it all in CSS:

@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
}

Then in your HTML you use bg-brand or text-brand exactly as before. The difference? The theme is now a set of CSS variables, so you can modify it via JavaScript for dynamic themes (dark mode, user customization).

Variants (hover, focus, responsive)

Variants remain the same – hover:, focus:, md:, dark: – but now you can create custom variants directly in CSS without external plugins. Example: you want a special behavior when the user has a mouse? Write:

@custom-variant pointer (&:hover) {
  /* no extra action needed */
}

Then use pointer:bg-red-500 in your classes. Flexibility without plugins — fewer dependencies, more control.

Plugins and compatibility

Most v3 plugins (typography, forms, aspect-ratio) have already been ported to v4. However, if you use very specific or unmaintained plugins, verify compatibility. At Meteora Web, we noticed that plugins like tailwindcss-forms already work in v4, while some third-party animation plugins require an update. Advice: before migrating a production project, test on a separate branch.

Common mistakes and how to avoid them

We've seen developers encounter these errors during migration:

• Duplicate imports: leaving old @tailwind base in the CSS causes errors. Replace everything with @import "tailwindcss";.
• Custom variables not found: in v4 theme values are CSS custom properties prefixed with --. If you used theme('colors.brand') in JS, now you must read getComputedStyle(element).getPropertyValue('--color-brand').
• Dark mode class: in v4 dark mode via class (class="dark") is enabled by default. No need to configure it anymore. If your project used darkMode: 'class', you can remove it.

Is it worth migrating now?

If your project is new: start with v4 directly, you have nothing to lose and gain speed and simplicity. If you have an existing v3 project: assess it. Migration is mechanical for most cases, but requires testing. We migrated an e-commerce site with 30 pages in about 4 hours, fixing two minor incompatibilities with animation plugins. The return? Faster builds and cleaner CSS code — cheaper future maintenance.

In a nutshell — what to do next

1. Download the latest Node.js version (at least 18.0.0) to support modern features.
2. Create a new test project with npm init -y and install tailwindcss + CLI.
3. Follow the three setup steps above: input.css, build, and try writing a utility.
4. If coming from v3, compare your tailwind.config.js with the @theme directives and migrate one page at a time.
5. Read the official documentation at Upgrade Guide v4 for a full check.

We at Meteora Web already use it in production. If you have doubts, contact us. Technology changes, but our approach remains: we measure every tool by the time saved for the client and the quality of the result. Tailwind 4 is one of those tools that gives a real edge. Don't let it slip away.