Setup and Configuration in Tailwind v4

Installing Tailwind CSS v4

Tailwind CSS v4 requires Node.js 18+. There are three installation paths depending on your build tool.

Option 1: Vite (recommended)

This covers React (Vite), Vue (Vite), SvelteKit, and Angular with the Vite-based Application Builder.

# Install Tailwind and the Vite plugin
npm install -D tailwindcss @tailwindcss/vite

Create your main CSS file and register it in your entry point:

/* src/styles.css */
@import "tailwindcss";

Register the plugin in vite.config.ts:

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

Import the CSS file in your app entry point:

// src/main.ts (or main.tsx / main.js)
import "./styles.css";

That is the entire setup. No tailwind.config.js, no postcss.config.js, no autoprefixer. The Oxide engine handles everything.

Option 2: PostCSS (webpack / Angular classic builder)

For projects using webpack or Parcel:

npm install -D tailwindcss @tailwindcss/postcss postcss

Create postcss.config.js:

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Then import Tailwind in your CSS:

/* src/styles.css */
@import "tailwindcss";

Option 3: CLI (no build tool)

For plain HTML projects or when you want a standalone build step:

npm install -D @tailwindcss/cli

# Watch mode — rebuilds on every file change
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

# One-time build (production)
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

The @import "tailwindcss" directive

The single line @import "tailwindcss" replaces the three-line v3 syntax:

/* v3 (old) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 (new) */
@import "tailwindcss";

This import includes three layers:

1. Base layer — normalizes browser defaults (similar to modern-normalize).
2. Components layer — reserved for component class definitions.
3. Utilities layer — all the utility classes (bg-, text-, p-*, etc.).

You can import individual layers if you need more control:

@import "tailwindcss/preflight";   /* only the base reset */
@import "tailwindcss/utilities";   /* only utilities */

CSS-first configuration with @theme

The @theme directive is the v4 replacement for tailwind.config.js's theme section. You define CSS custom properties that follow a naming convention, and Tailwind generates utilities from them automatically.

@import "tailwindcss";

@theme {
  /* Colors → bg-brand, text-brand, border-brand, ring-brand */
  --color-brand: #6366f1;
  --color-brand-light: #a5b4fc;
  --color-brand-dark: #3730a3;

  /* Font families → font-sans, font-display */
  --font-sans: "Inter", ui-sans-serif, sans-serif;
  --font-display: "Cal Sans", "Inter", sans-serif;

  /* Font sizes → text-2xs */
  --text-2xs: 0.625rem;
  --text-2xs--line-height: 1rem;

  /* Breakpoints → sm:, md:, lg: etc. */
  --breakpoint-xs: 480px;

  /* Shadows → shadow-glow */
  --shadow-glow: 0 0 20px rgba(99, 102, 241, 0.4);

  /* Border radius → rounded-2xl is built-in, add custom: */
  --radius-4xl: 2rem;
}

Every token you define in @theme generates corresponding utility classes with no additional configuration.

Controlling which files Tailwind scans

By default, Tailwind v4 auto-detects files in your project by scanning for class names in common file types. You can be explicit with @source:

@import "tailwindcss";

/* Scan specific directories and file types */
@source "../src/**/*.{html,ts,tsx,jsx,vue,svelte}";

/* Also scan a third-party component library for class names */
@source "../node_modules/@my-ui/components/dist/**/*.js";

@source accepts glob patterns relative to the CSS file's location.

Angular integration in detail

Angular 18+ with the application builder (esbuild) uses Vite under the hood. The integration is:

# In an existing Angular project
npm install -D tailwindcss @tailwindcss/vite

Add the plugin to angular.json (if using the Angular CLI's Vite integration) or to a custom vite.config.ts. For the standard Application Builder, you add it to the plugins field in angular.json:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:application",
          "options": {
            "styles": ["src/styles.css"]
          }
        }
      }
    }
  }
}

Then your src/styles.css starts with @import "tailwindcss" and any @theme customizations follow.

React integration

# Create a new Vite + React project
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install -D tailwindcss @tailwindcss/vite

Edit vite.config.ts to add the plugin, then replace the contents of src/index.css with @import "tailwindcss";. Import the CSS in src/main.tsx:

import "./index.css";

Start the dev server with npm run dev and Tailwind utilities are available immediately.

Verifying the setup

Create a test element to verify utilities are working:

<!-- If this renders as a blue rounded button, your setup is correct -->
<button class="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded transition-colors">
  Tailwind works!
</button>

If the button appears without any styling, check that:

1. Your CSS file is being imported in the app entry point.
2. The Vite plugin or PostCSS plugin is registered correctly.
3. The dev server was restarted after installing the packages.

VS Code setup

Install the Tailwind CSS IntelliSense extension (ID: bradlc.vscode-tailwindcss). It provides:

• Autocomplete for every utility class as you type
• Documentation preview on hover over any class
• Syntax highlighting inside @theme blocks
• Linting for misspelled or unknown class names

// .vscode/settings.json — enable class sorting on save (optional)
{
  "editor.defaultFormatter": "bradlc.vscode-tailwindcss",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

Practice

1. Create a new Vite project (npm create vite@latest) and install Tailwind v4 following the steps above. Verify the setup with the test button.
2. Add a @theme block that defines a custom --color-brand and use it in a paragraph: <p class="text-brand">Hello</p>.
3. Define a custom breakpoint --breakpoint-xs: 480px and test it with xs:text-red-500 on a heading.