Set Up Tailwind CSS with TypeScript

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

When to Use

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

Inputs

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

Procedure

Step 1: Install Tailwind CSS

npm install -D tailwindcss @tailwindcss/postcss postcss

For Next.js (if not already included):

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

Expected: tailwindcss, postcss, and autoprefixer are installed as dev dependencies. For Next.js, tailwind.config.ts and postcss.config.js are generated by npx tailwindcss init -p.

On failure: If npx tailwindcss init fails, install Tailwind first with npm install -D tailwindcss and retry. If using a monorepo, run the command from the app's root directory, not the workspace root.

Step 2: Configure tailwind.config.ts

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;

Expected: tailwind.config.ts has a content array matching the project's file locations, custom colors and fonts under theme.extend, and proper TypeScript typing with the Config import.

On failure: If custom classes do not render, verify the content paths match your actual directory structure. Paths are glob patterns relative to the project root. Missing paths mean Tailwind will not scan those files for class usage.

Step 3: Set Up Global Styles

Edit src/app/globals.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;
  }
}

Expected: globals.css contains the three Tailwind directives (@tailwind base, @tailwind components, @tailwind utilities) plus any custom base and component layer styles. The file is imported in the root layout.

On failure: If styles are not applied, verify globals.css is imported in layout.tsx (or _app.tsx for Pages Router). Check that the Tailwind directives are present and not commented out.

Step 4: Create Type-Safe Utility Helpers

Create src/lib/cn.ts:

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

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

Install dependencies:

npm install clsx tailwind-merge

Usage in components:

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}
    />
  );
}

Expected: src/lib/cn.ts exports a cn() function. clsx and tailwind-merge are installed as dependencies. Components use cn() to merge class names without conflicts.

On failure: If clsx or tailwind-merge are not found, run npm install clsx tailwind-merge. If TypeScript reports type errors in cn.ts, verify the ClassValue type is imported from clsx.

Step 5: Add Dark Mode Support

Update tailwind.config.ts:

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

Toggle implementation:

"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>
  );
}

Expected: Dark mode toggles correctly between light and dark themes. The dark class is applied to the <html> element, and dark: prefixed utility classes respond accordingly.

On failure: If dark mode does not toggle, verify darkMode: "class" is set in tailwind.config.ts. Ensure the dark class is toggled on the <html> element (not <body>). For system-preference mode, use darkMode: "media" instead.

Step 6: Add Plugins (Optional)

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

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

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

Expected: Plugins are installed as dev dependencies and registered in the plugins array of tailwind.config.ts. Plugin-provided classes (e.g., prose from typography, styled form elements from forms) are available in components.

On failure: If plugin classes do not render, verify the plugin is both installed (npm ls @tailwindcss/typography) and added to the plugins array. Restart the dev server after config changes.

Validation

• Tailwind classes render correctly in the 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

Common Pitfalls

• Content paths missing: If classes don't render, check content array in config matches your file locations
• Class conflicts: Use tailwind-merge (via cn()) to prevent conflicting utility classes
• Custom values not working: Ensure custom values are under extend (to add) not at theme root (which replaces defaults)
• Dark mode not toggling: Check darkMode setting and that the dark class is on <html> not <body>

Related Skills

• scaffold-nextjs-app - project setup before Tailwind configuration
• deploy-to-vercel - deploy the styled application