Installation & Setup
Knowing the classes is one thing — getting Tailwind running in your project is another. There are four ways to install Tailwind depending on your setup: the instant Play CDN for learning, the Tailwind CLI for standalone projects, Vite for React/Vue/Svelte, and Next.js for full-stack apps. This chapter walks you through every method step-by-step with real terminal commands and working config files.
tailwind.config.js
— content, theme, darkMode, plugins
Prerequisites — What You Need First
The CDN method has zero prerequisites — just an HTML file. Every other method requires Node.js (which comes with npm). Tailwind v3 needs Node ≥ 14. Check your version before starting, then install the VS Code extensions that make Tailwind development dramatically faster.
Choose Your Installation Method
Pick the method that matches your project type. If you're unsure, start with the CDN to learn, then switch to the CLI or Vite for real projects.
- Instant — 30 seconds to working
- No Node.js required at all
- Great for CodePen / learning
- Not for production (3MB JS)
- No custom config support
- No framework dependency
- Full config file support
- Tiny output CSS (tree-shaking)
- Requires Node.js
- Manual watcher needed
- Lightning-fast HMR
- Works with any framework
- Production-ready pipeline
- More setup files
- Needs PostCSS config
- Official first-class support
- Auto-configured in wizard
- SSR + Tailwind seamlessly
- Tied to React ecosystem
- Heavier project scaffold
| Method | Node Required | Config File | Production | Best For |
|---|---|---|---|---|
| CDN | ✗ No | ✗ No | ✗ No | Learning, prototyping, CodePen |
| CLI | ✓ Yes | ✓ Yes | ✓ Yes | Plain HTML/JS, static sites |
| Vite | ✓ Yes | ✓ Yes | ✓ Yes | React, Vue, Svelte SPAs |
| Next.js | ✓ Yes | ✓ Yes | ✓ Yes | Full-stack React with SSR |
Method A — Play CDN
The Play CDN is a browser-based Tailwind that runs entirely in JavaScript — it detects your class names and injects the CSS on the fly. No build step, no installation. Just add one script tag and every Tailwind class works instantly. Do not use in production — it loads ~3MB on every page.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>My Tailwind Page</title>
<!-- ✅ Tailwind Play CDN — one line, zero setup -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- Optional inline config — dark mode, custom colours -->
<script>
tailwind.config = {
darkMode: 'class',
theme: {
extend: {
colors: { brand: '#06b6d4' }
}
}
}
</script>
</head>
<body class="bg-gray-50 min-h-screen flex items-center justify-center p-8">
<div class="bg-white rounded-2xl shadow-xl p-8 max-w-md w-full">
<h1 class="text-2xl font-bold text-gray-900 mb-3">Hello, Tailwind! 🎉</h1>
<p class="text-gray-500 leading-relaxed mb-6">
Running Tailwind CSS from CDN — no build step needed.
</p>
<button class="w-full bg-cyan-500 hover:bg-cyan-600 text-white
font-semibold py-3 rounded-xl transition-colors duration-200">
Get Started
</button>
</div>
</body>
</html>
Method B — Tailwind CLI (Recommended)
The Tailwind CLI is the simplest production-ready setup. It scans your HTML and JS files for class names and outputs a minified CSS file containing only the classes you actually use — often under 10KB. No webpack, no Vite, no PostCSS required.
npm init -y to generate package.json.
npm install -D tailwindcss. The
-D flag saves it as a dev dependency — not needed at runtime.
npx tailwindcss init to create a blank
config file in your project root.src/input.css and add the three
@tailwind directives — base, components, utilities.
--watch mode. Tailwind rebuilds
dist/output.css every time you save. Link it in your HTML head.
# 1 — Create project folder
mkdir my-tailwind-project
cd my-tailwind-project
# 2 — Initialise npm
npm init -y
# 3 — Install Tailwind CSS
npm install -D tailwindcss
# 4 — Generate config file (creates tailwind.config.js)
npx tailwindcss init
# 5 — Start the watcher (run this while developing)
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch
# 6 — Build for production (minified, optimised)
npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify
/** @type {import('tailwindcss').Config} */
module.exports = {
// Tell Tailwind which files to scan for class names
content: [
"./src/**/*.{html,js}", // all HTML & JS inside src/
"./*.html", // any HTML in the root folder
],
theme: {
extend: {},
},
plugins: [],
};
/* ── src/input.css ───────────────────────────────── */
@tailwind base;
/* Injects Preflight — a modern CSS reset based on normalize.css.
Removes browser defaults for margins, headings, lists, and more. */
@tailwind components;
/* Reserved for component-layer styles (@layer components { ... }).
Empty by default unless you add custom component classes. */
@tailwind utilities;
/* Injects ALL utility classes — p-4, flex, text-xl, bg-cyan-500…
This must come LAST so utilities can override component styles. */
/* Your own custom CSS goes after these three directives */
Your project folder should look like this after setup:
{
"scripts": {
"dev": "tailwindcss -i ./src/input.css -o ./dist/output.css --watch",
"build": "tailwindcss -i ./src/input.css -o ./dist/output.css --minify"
}
}
# Now you can simply run:
npm run dev # development — watches and rebuilds on change
npm run build # production — minified, optimised output
Method C — Vite + Tailwind CSS
Vite is the modern build tool for React, Vue, and Svelte projects. Tailwind integrates via PostCSS — Vite runs this automatically. The setup takes under two minutes and gives you instant hot module replacement (HMR): your browser updates in milliseconds as you type classes.
# 1 — Scaffold a Vite project (choose your template)
npm create vite@latest my-app -- --template vanilla # plain JS
npm create vite@latest my-app -- --template react # React
npm create vite@latest my-app -- --template vue # Vue
cd my-app
# 2 — Install project dependencies
npm install
# 3 — Install Tailwind + PostCSS + Autoprefixer
npm install -D tailwindcss postcss autoprefixer
# 4 — Generate both config files at once (-p flag)
npx tailwindcss init -p
# Creates: tailwind.config.js AND postcss.config.js
# 5 — Start the dev server
npm run dev
/** @type {import('tailwindcss').Config} */
export default {
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}", // scan all React/TS files
],
theme: {
extend: {},
},
plugins: [],
};
export default {
plugins: {
tailwindcss: {}, // runs Tailwind as a PostCSS plugin
autoprefixer: {}, // adds vendor prefixes for browser compatibility
},
};
/* src/index.css — import this in main.js or main.jsx */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* Your global CSS below */
Vite + React + Tailwind project structure:
Method D — Next.js (Auto-Configured)
Next.js has first-class Tailwind support. When you create a new
project with create-next-app, the wizard asks
if you want Tailwind — say yes and everything is auto-configured. No manual steps.
# Create a new Next.js app — wizard will ask about Tailwind
npx create-next-app@latest my-next-app
# The interactive prompt:
# ✔ Would you like to use TypeScript? → Yes/No
# ✔ Would you like to use ESLint? → Yes
# ✔ Would you like to use Tailwind CSS? → ✅ Yes ← choose this
# ✔ Would you like to use src/ dir? → Yes
# ✔ Would you like App Router? → Yes
cd my-next-app
npm run dev # open http://localhost:3000
# ── Adding Tailwind to an EXISTING Next.js project ──────
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
import type { Config } from 'tailwindcss'
const config: Config = {
content: [
'./src/pages/**/*.{js,ts,jsx,tsx,mdx}',
'./src/components/**/*.{js,ts,jsx,tsx,mdx}',
'./src/app/**/*.{js,ts,jsx,tsx,mdx}',
],
theme: {
extend: {},
},
plugins: [],
}
export default config
@tailwind base;
@tailwind components;
@tailwind utilities;
/* Custom CSS variables / overrides below */
:root {
--foreground-rgb: 0, 0, 0;
}
Understanding tailwind.config.js
The config file is the control centre of every Tailwind project. It tells Tailwind which files to scan, extends the design system, enables dark mode, and registers plugins. Getting it right is essential.
theme directly to keep built-in utilities.'media' (OS preference) or
'class' (toggled via JS on the <html> element).
@tailwindcss/forms, @tailwindcss/typography.
'tw-' makes
tw-flex. Useful when integrating into existing projects.
/** @type {import('tailwindcss').Config} */
module.exports = {
/* ── Content — required ──────────────────────────────── */
content: [
"./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}",
"./public/index.html",
],
/* ── Dark Mode ───────────────────────────────────────── */
darkMode: 'class', // 'media' | 'class'
/* ── Theme ───────────────────────────────────────────── */
theme: {
extend: {
/* Custom colour tokens */
colors: {
brand: {
50: '#ecfeff',
500: '#06b6d4', // use: bg-brand-500
900: '#164e63',
},
},
/* Custom font families */
fontFamily: {
sans: ['Inter', 'system-ui', 'sans-serif'],
display: ['Clash Display', 'sans-serif'],
mono: ['JetBrains Mono', 'monospace'],
},
/* Custom spacing tokens */
spacing: {
'sidebar': '280px', // use: w-sidebar
},
/* Custom breakpoints */
screens: {
'xs': '480px', // use: xs:flex
},
/* Custom animations */
keyframes: {
fadeUp: {
'0%': { opacity: '0', transform: 'translateY(20px)' },
'100%': { opacity: '1', transform: 'translateY(0)' },
},
},
animation: {
'fade-up': 'fadeUp 0.5s ease-out', // use: animate-fade-up
},
},
},
/* ── Plugins ─────────────────────────────────────────── */
plugins: [
require('@tailwindcss/forms'), // styled form elements
require('@tailwindcss/typography'), // prose class for markdown
require('@tailwindcss/aspect-ratio'), // responsive aspect ratios
],
};
Verify Your Setup & Fix Common Errors
Add a few Tailwind classes and check they render. If they don't, the table below covers the most common errors and exactly how to fix them.
| Problem | Likely Cause | Fix |
|---|---|---|
| No styles at all | Output CSS not linked in HTML, or watcher not running | Add <link rel="stylesheet" href="dist/output.css">
and run the watcher |
| Output CSS is empty (0 bytes) | Content paths wrong — Tailwind found no classes | Fix content array in
tailwind.config.js to point to your actual files |
| Some classes work, others don't | Dynamic class names built with string concatenation | Always write complete class names — never `text-${color}-500`
|
| Styles don't update on save | Watcher process stopped or crashed | Re-run npm run dev in
the terminal |
| Cannot find module 'tailwindcss' | npm install not run, or wrong directory | Run npm install in
the project root folder |
| VS Code no autocomplete | IntelliSense extension missing or no config file | Install Tailwind CSS IntelliSense and ensure tailwind.config.js is
in root |
- Four methods: CDN (prototyping), CLI (recommended standalone), Vite + PostCSS (React/Vue/Svelte SPAs), and Next.js (full-stack React with built-in support).
- CDN is zero-setup but never for production — it loads ~3MB of JavaScript in the browser with no tree-shaking.
- Tailwind CLI:
npm install -D tailwindcss→npx tailwindcss init→ set content paths → run watcher. Simple and powerful. - Vite: install
tailwindcss postcss autoprefixertogether and use the-pflag to auto-generate both config files at once. - Next.js auto-configures Tailwind when you select "Yes" in the
create-next-appwizard — no manual steps for new projects. - The content array is the most critical config setting — wrong paths = empty CSS output. Always verify it points to your actual source files.
- Three directives:
@tailwind base(reset),@tailwind components(component layer),@tailwind utilities(all utilities — must be last). - Use theme.extend, not theme directly — overriding theme replaces all defaults; extend merges your values with them.
Quick Check — Questions & Answers
Click each question to reveal the detailed answer.
1. Performance — the CDN loads ~3MB of JavaScript that runs in the browser to detect classes and inject CSS at runtime. This causes a Flash of Unstyled Content (FOUC) — the page briefly appears unstyled before CSS is injected.
2. No tree-shaking — the CDN delivers every possible Tailwind class. A CLI build scans your files and only outputs the classes you actually use — typically 5–15KB, not 3MB.
3. Limited config support — the CDN only supports basic inline config. It can't use plugins, custom variants, or the full JIT engine.
dist/output.css will contain only the Preflight base reset and zero
utility classes. Your HTML will look completely unstyled even though
Tailwind ran successfully.Common mistakes:
• Wrong folder:
"./pages/**/*.html" instead of
"./src/**/*.html"• Missing extension:
*.js instead of *.{js,jsx} for
React• Not including
index.html in the rootQuick check: if
dist/output.css is under 5KB, your content paths are
wrong.
-p flag generates two files instead of
one:Without
-p: creates only
tailwind.config.jsWith
-p: creates tailwind.config.js AND
postcss.config.jsThe
postcss.config.js is required when using Vite or any PostCSS-based
build system — it registers Tailwind and Autoprefixer as PostCSS plugins so they run
during the build step. When using the standalone CLI without Vite, you don't need
the -p flag.
theme — completely replaces Tailwind's
defaults for that key. If you set
theme: { colors: { brand: '#06b6d4' } }, you lose ALL 22 default colour
palettes (gray, blue, red, etc.) and only have brand.theme.extend — merges your values with the
defaults. Setting theme: { extend: { colors: { brand: '#06b6d4' } } }
adds bg-brand / text-brand while keeping all default
colours intact.Rule: always use
theme.extend unless you deliberately
want to replace Tailwind's entire design system.
text-cyan-500.If you write
`text-${color}-500`, the scanner sees the literal string
`text-${color}-500` — not a Tailwind class — and does NOT include any
text-*-500 utilities in the output.Fix: always write the complete class name as a static string. Use object maps instead:
const colors = { cyan: 'text-cyan-500', red: 'text-red-500' }const cls = colors[color] // 'text-cyan-500' — safe!
MCQ Quiz — Test Yourself
Select the best answer. The correct option is revealed after you click.
content array in tailwind.config.js?colors: { brand: '#06b6d4' }
directly inside theme: (not theme.extend). What happens?
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.