Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Animation and Advanced Features

Build Tools, Optimization and Upgrading from v3

Set up Tailwind CSS v4 with Vite, the CLI or PostCSS, understand automatic content detection and @source, and upgrade from v3 with the official tool and renamed utilities.

Every example on this site loads Tailwind through a single <script> tag. That is wonderful for learning and prototyping, but it compiles CSS inside the visitor's browser, which is not what you want on a real website. For production you use a build step that scans your files, generates one small CSS file containing only the utilities you used, and minifies it. This lesson explains the options, what the build does for you, and how to move an older Tailwind v3 project to v4.

The code blocks in this lesson are read-only: they run in a terminal and a code editor, not in a web page.

Three ways to use Tailwind

flowchart TD
  A["How will you build?"] --> B["A bundler such as Vite<br/>(Laravel, React, Vue, Svelte, Astro)"]
  A --> C["No bundler<br/>(static HTML, any backend)"]
  A --> D["Already using PostCSS"]
  B --> B1["@tailwindcss/vite"]
  C --> C1["@tailwindcss/cli"]
  D --> D1["@tailwindcss/postcss"]

All three run the same engine and read the same CSS file.

Terminal
npm install tailwindcss @tailwindcss/vite
JavaScript
// vite.config.js
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});
CSS
/* resources/css/app.css */
@import "tailwindcss";

Then load the stylesheet from your entry point or layout (in Laravel: @vite(['resources/css/app.css', 'resources/js/app.js'])). Run npm run dev for a fast hot-reloading server and npm run build for the optimized production files. The official starter kits for Laravel, Next.js and others are already set up this way.

The standalone CLI

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

--watch rebuilds on every change. For production add --minify. Link the output file in your HTML with an ordinary <link rel="stylesheet" href="/dist/output.css">. There is also a single-file standalone executable that needs no Node at all.

PostCSS

Terminal
npm install tailwindcss @tailwindcss/postcss
JavaScript
// postcss.config.mjs
export default {
  plugins: { '@tailwindcss/postcss': {} },
};

The one CSS file

In v4 your CSS file is the whole configuration. A typical app.css looks like this:

CSS
@import "tailwindcss";

@source "../views";                    /* extra folders to scan */
@plugin "@tailwindcss/typography";     /* optional plugin */
@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --color-brand-500: oklch(0.62 0.19 259);
}

@layer components {
  .prose-lite a { @apply underline; }
}

That is everything from the previous lessons in one place: imports, sources, plugins, variants, theme, custom layers. Because it is plain CSS, any CSS tooling (formatters, editors, @import bundling) works.

How the build finds your classes

Tailwind scans your project files as plain text and collects anything that looks like a class name, in any language: HTML, Blade, JSX, Vue, Markdown, PHP, even strings in JavaScript. Then it generates CSS only for the classes found. This is why dynamic names (bg-${color}-500) fail, as covered in Arbitrary Values and Resolving Conflicts.

Version 4 detects files automatically: it skips everything in .gitignore, binary files, CSS files and lock files. You only need to intervene when:

  • Classes live in a package under node_modules or in a folder outside the project: @source "../node_modules/my-ui-lib";
  • You must exclude something: @source not "../legacy";
  • Classes are never written out literally: @source inline("bg-{red,green,blue}-500");
  • You want to turn automatic detection off: @import "tailwindcss" source(none); then list sources yourself.

Optimizing for production

You get most optimizations by default:

  • Only used CSS ships. A typical site ends up with 5 to 15 KB of CSS after gzip, whatever its size.
  • Minification and vendor prefixes are handled by Lightning CSS, built into v4. There is no separate autoprefixer or postcss-import to install.
  • Caching: let your bundler add a content hash to the file name, and serve it with a long Cache-Control: max-age.
  • Fonts and images are separate: self-host fonts, use font-display: swap, and give images width and height or an aspect-* class.

Never ship the browser script (@tailwindcss/browser) to production. It compiles in the visitor's browser, delays rendering, and is meant for demos, documentation and quick experiments.

Upgrading from v3 to v4

The official upgrade tool does most of the work. It needs Node.js 20 or newer, so run it on a clean git branch:

Terminal
npx @tailwindcss/upgrade

It updates dependencies, migrates tailwind.config.js into CSS where possible, replaces the three @tailwind directives with @import "tailwindcss";, and renames changed utilities in your templates. Review the diff, then test the pages.

What changed

v3 v4
@tailwind base; @tailwind components; @tailwind utilities; @import "tailwindcss";
tailwind.config.js @theme in CSS (still loadable with @config)
content: [...] globs automatic detection; @source for extras
shadow-sm, shadow shadow-xs, shadow-sm (same for blur, rounded, drop-shadow)
outline-none outline-hidden (outline-none now truly removes the outline)
ring (3px blue) ring-3; plain ring is 1px and uses currentColor
bg-gradient-to-r bg-linear-to-r
flex-shrink-0, flex-grow shrink-0, grow
bg-opacity-50 bg-black/50 (opacity modifier)
!text-sm text-sm!
theme(colors.red.500) var(--color-red-500)
variant stack first:*:pt-0 (right to left) left to right

Behavior changes to watch:

  • The default border color is now currentColor instead of gray-200; add border-gray-200 where you relied on the default.
  • Buttons use cursor: default, like native apps. Add cursor-pointer if you want a hand.
  • hover: only applies on devices that support hover, which fixes sticky hover on phones.
  • Browser support: v4 targets Safari 16.4+, Chrome 111+ and Firefox 128+, because it uses @property, cascade layers and color-mix(). If you must support older browsers, stay on v3.4.

Keeping a legacy config

You can migrate gradually. Load the old config from CSS:

CSS
@import "tailwindcss";
@config "../../tailwind.config.js";

Options such as corePlugins, safelist and separator are not supported in v4.

A stand-in: seeing the build's job in the browser

The browser script performs, in your page, the same steps the build performs once on your machine: scan for class names, generate CSS, inject it. The demo below lists the CSS rules it generated for a tiny snippet, which is roughly what your built file would contain.

What the generator produced

You will see a short list of selectors, one for each class used by the button and the paragraph, plus a few internal helpers. That is the principle behind small production CSS: if you never use a class, it is never generated.

A deployment checklist

  1. Install dependencies and run the production build in CI (npm ci && npm run build).
  2. Commit the lock file; do not commit the generated CSS unless your platform requires it.
  3. Serve the hashed CSS file with long-lived caching and compression (gzip or Brotli).
  4. Check the built CSS size; a sudden jump means a very broad @source or a safelist that is too large.
  5. Remove the browser script from every page.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which package connects Tailwind v4 to a Vite project?

    @tailwindcss/vite is the first-party plugin; @tailwindcss/browser is only for demos.
  2. 2. Why must a production site not use the browser script?

    A build compiles once ahead of time and ships a small static stylesheet.
  3. 3. What replaces the three @tailwind directives in v4?

    A single CSS import pulls in theme, base and utilities.
  4. 4. How do you make Tailwind scan a folder outside your project root?

    @source adds extra paths to the automatic detection.
  5. 5. Which run command performs most of an upgrade from v3?

    The official upgrade tool migrates dependencies, CSS directives, config and renamed utilities.

Summary

  • Production uses a build: @tailwindcss/vite, @tailwindcss/cli or @tailwindcss/postcss, with one CSS file that begins @import "tailwindcss";.
  • Tailwind scans files as text and generates only the classes it finds; v4 detects sources automatically, and @source adds or removes folders and safelists names.
  • Lightning CSS handles minification and prefixes; ship the hashed file with long caching and never the browser script.
  • Upgrade with npx @tailwindcss/upgrade, then check renamed utilities, default border color, buttons and browser support.

Next: Project: A Landing Page