Setup Tailwind Typescript

---
name: setup-tailwind-typescript
locale: caveman
source_locale: en
source_commit: 82c77053
fence_basis_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-05-03"
description: >
  Configure Tailwind CSS with TypeScript in a Next.js or React project.
  Covers installation, configuration, custom theme extensions, component
  patterns, and type-safe styling utilities. Use when adding Tailwind CSS
  to an existing TypeScript project, customizing the Tailwind theme for a
  project's design system, setting up type-safe component styling patterns,
  or configuring Tailwind plugins and extensions.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: web-dev
  complexity: basic
  language: TypeScript
  tags: tailwind, typescript, css, styling, configuration
---

# Set Up Tailwind CSS with TypeScript

Configure Tailwind CSS in TypeScript project with custom theme, utilities, type-safe patterns.

## When Use

- Adding Tailwind CSS to existing TypeScript project
- Customizing Tailwind theme for project's design system
- Setting up type-safe component styling patterns
- Configuring Tailwind plugins + extensions

## Inputs

- **Required**: TypeScript project (Next.js, Vite, standalone React)
- **Optional**: Design system tokens (colors, spacing, fonts)
- **Optional**: Tailwind plugins to include

## Steps

### Step 1: Install Tailwind CSS

```bash
npm install -D tailwindcss @tailwindcss/postcss postcss
```

For Next.js (if not already included).

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

**Got:** `tailwindcss`, `postcss`, `autoprefixer` installed as dev deps. For Next.js, `tailwind.config.ts` + `postcss.config.js` generated by `npx tailwindcss init -p`.

**If fail:** `npx tailwindcss init` fails? Install Tailwind first with `npm install -D tailwindcss`, retry. Monorepo? Run from app's root dir, not workspace root.

### Step 2: Configure tailwind.config.ts

```typescript
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: {
      colors: {
        primary: {
          50: "#eff6ff",
          100: "#dbeafe",
          500: "#3b82f6",
          600: "#2563eb",
          700: "#1d4ed8",
          900: "#1e3a5f",
        },
        secondary: {
          500: "#6366f1",
          600: "#4f46e5",
        },
      },
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      spacing: {
        "18": "4.5rem",
        "88": "22rem",
      },
    },
  },
  plugins: [],
};

export default config;
```

**Got:** `tailwind.config.ts` has `content` array matching project's file locations, custom colors + fonts under `theme.extend`, proper TypeScript typing with `Config` import.

**If fail:** Custom classes do not render? Verify `content` paths match actual dir structure. Paths are glob patterns relative to project root. Missing paths = Tailwind will not scan those files for class usage.

### Step 3: Set Up Global Styles

Edit `src/app/globals.css`.

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html {
    @apply antialiased;
  }

  body {
    @apply bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100;
  }
}

@layer components {
  .btn-primary {
    @apply bg-primary-600 text-white px-4 py-2 rounded-lg
           hover:bg-primary-700 focus:outline-none focus:ring-2
           focus:ring-primary-500 focus:ring-offset-2
           transition-colors duration-200;
  }
}
```

**Got:** `globals.css` contains three Tailwind directives (`@tailwind base`, `@tailwind components`, `@tailwind utilities`) + any custom base + component layer styles. File imported in root layout.

**If fail:** Styles not applied? Verify `globals.css` imported in `layout.tsx` (or `_app.tsx` for Pages Router). Check Tailwind directives present + not commented out.

### Step 4: Create Type-Safe Utility Helpers

Make `src/lib/cn.ts`.

```typescript
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

Install deps.

```bash
npm install clsx tailwind-merge
```

Usage in components.

```tsx
import { cn } from "@/lib/cn";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
}

export function Button({ className, variant = "primary", ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        "px-4 py-2 rounded-lg font-medium transition-colors",
        variant === "primary" && "bg-primary-600 text-white hover:bg-primary-700",
        variant === "secondary" && "bg-secondary-500 text-white hover:bg-secondary-600",
        variant === "outline" && "border border-gray-300 hover:bg-gray-50",
        className
      )}
      {...props}
    />
  );
}
```

**Got:** `src/lib/cn.ts` exports `cn()` function. `clsx` + `tailwind-merge` installed as deps. Components use `cn()` to merge class names without conflicts.

**If fail:** `clsx` or `tailwind-merge` not found? Run `npm install clsx tailwind-merge`. TypeScript reports type errors in `cn.ts`? Verify `ClassValue` type imported from `clsx`.

### Step 5: Add Dark Mode Support

Update `tailwind.config.ts`.

```typescript
const config: Config = {
  darkMode: "class", // or "media" for system preference
  // ... rest of config
};
```

Toggle implementation.

```tsx
"use client";
import { useEffect, useState } from "react";

export function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
  }, [dark]);

  return (
    <button onClick={() => setDark(!dark)}>
      {dark ? "Light" : "Dark"} Mode
    </button>
  );
}
```

**Got:** Dark mode toggles correctly between light + dark themes. `dark` class applied to `<html>` element, `dark:` prefixed utility classes respond accordingly.

**If fail:** Dark mode does not toggle? Verify `darkMode: "class"` set in `tailwind.config.ts`. Ensure `dark` class toggled on `<html>` element (not `<body>`). For system-preference mode, use `darkMode: "media"`.

### Step 6: Add Plugins (Optional)

```bash
npm install -D @tailwindcss/typography @tailwindcss/forms
```

```typescript
// tailwind.config.ts
import typography from "@tailwindcss/typography";
import forms from "@tailwindcss/forms";

const config: Config = {
  // ...
  plugins: [typography, forms],
};
```

**Got:** Plugins installed as dev deps + registered in `plugins` array of `tailwind.config.ts`. Plugin-provided classes (`prose` from typography, styled form elements from forms) available in components.

**If fail:** Plugin classes do not render? Verify plugin both installed (`npm ls @tailwindcss/typography`) + added to `plugins` array. Restart dev server after config changes.

## Checks

- [ ] Tailwind classes render correctly in browser
- [ ] Custom theme values (colors, fonts, spacing) work
- [ ] `cn()` utility merges classes without conflicts
- [ ] Dark mode toggles correctly
- [ ] TypeScript shows no errors in config or components
- [ ] Production build purges unused styles

## Pitfalls

- **Content paths missing**: Classes do not render? Check `content` array in config matches file locations
- **Class conflicts**: Use `tailwind-merge` (via `cn()`) to prevent conflicting utility classes
- **Custom values not working**: Ensure custom values under `extend` (to add) not at theme root (which replaces defaults)
- **Dark mode not toggling**: Check `darkMode` setting + that `dark` class on `<html>` not `<body>`

## See Also

- `scaffold-nextjs-app` - project setup before Tailwind config
- `deploy-to-vercel` - deploy styled application