Building Modern React Projects with Tailwind CSS

Why Tailwind CSS for React Development?

Tailwind's utility-first philosophy means composing interfaces directly in your markup using pre-built classes. Instead of switching between HTML and CSS files to maintain class names and naming conventions, you apply utilities directly where you need them. This approach eliminates the cognitive overhead of naming things while ensuring consistency through design tokens that are built into the framework.

For React developers specifically, this model complements component-based architecture perfectly. Styles live right alongside component logic, making it easier to understand, modify, and test individual components. The co-location improves maintainability and reduces the file navigation that slows down development in traditional CSS setups.

The performance characteristics are equally compelling. Tailwind's atomic CSS approach means that common styles share CSS rules--when multiple components use flex, items-center, or p-4, they all reference the same declarations in the compiled output. This sharing maximizes compression efficiency, especially when using gzip or Brotli compression on your production server.

Vite + React Setup

Vite has become the go-to build tool for React single-page applications due to its exceptional startup speed and hot module replacement. Setting up Tailwind CSS v3 with Vite involves installing the required dependencies and configuring your content paths. PostCSS and Autoprefixer handle the CSS transformation pipeline that enables Tailwind's utility classes to work correctly in any browser.

The content array in your configuration tells Tailwind which files to scan for class names during the build process. This scanning is essential--if a path is missing, the classes in that file won't be included in your production CSS. Proper content configuration is the most common source of setup issues, so double-check your glob patterns against your actual file structure.

Next.js v3 Configuration

Next.js projects require content paths that cover both the App Router structure and any components directory. The Pages Router and App Router have different directory structures, so your configuration must include paths for both if you're migrating or using hybrid approaches. The content array is the most critical part of this configuration--Tailwind scans these paths during the build to determine which utility classes are actually used.

After running npx tailwindcss init -p, you'll have two essential files: tailwind.config.js and postcss.config.js. Add the Tailwind directives (@tailwind base, @tailwind components, @tailwind utilities) to your global CSS file, typically app/globals.css in App Router projects. The PostCSS configuration is handled automatically by Next.js's built-in PostCSS support.

Next.js v4 Configuration

Tailwind v4, released in late 2024, introduces significant architectural changes that simplify the setup process. The most notable difference is the CSS-first configuration method using @theme directives, which reduces configuration complexity and improves performance. Version 4's intelligent engine automatically detects your content files without explicit configuration in most cases.

The new approach removes PostCSS as a required dependency for many use cases. Instead of managing a tailwind.config.js file with extensive content arrays, you define your theme directly in CSS using the @theme block. This approach is particularly powerful for teams who want their design tokens closer to their styles, making it easier to understand and modify the visual design of an application.

Button Component Usage

The Button component demonstrates a scalable pattern for Tailwind-powered React components. By mapping props to class combinations, you create a single component that handles multiple visual variations. The forwardRef pattern ensures compatibility with component composition libraries and animation libraries like Framer Motion.

This same pattern extends naturally to other components in your library. An Input component can have error and success states, a Card component can have hover effects and padding variants, and a Badge component can have color schemes. The key insight is that prop-driven styling scales better than class-driven styling as your application grows.

Card Component Pattern

Cards represent a fundamental container pattern in modern UI development. The Card component example shows how to use slots and children for flexibility, allowing any content to be passed into the card while maintaining consistent styling. The hover prop enables interactive states without duplicating card definitions for different use cases.

Notice how the component handles dark mode through the dark: prefix, responsive layouts through default classes, and maintains accessibility with semantic HTML structure. This approach creates cards that are visually consistent yet content-agnostic--a pattern that serves everything from dashboards to content-heavy marketing pages.

Dark Mode Configuration

To configure Tailwind for dark mode in v3, set darkMode: 'class' in your tailwind.config.js. This configuration allows you to control dark mode by adding or removing the dark class on the <html> element. The recommended approach for persisting user preference uses localStorage to remember the user's choice across sessions.

A critical best practice is preventing the flash of unstyled content (FOUC) that occurs when the page loads before JavaScript executes. Add an inline script to your document <head> that checks localStorage and applies the appropriate class before React hydrates. This ensures users see the correct theme immediately on page load.

Using Dark Variants

Writing dark mode styles uses the dark: prefix pattern, which applies classes only when the dark class exists on the HTML element. This approach keeps light and dark styles together in your component, making it easier to maintain and understand theme variations. For complex nested components, semantic color usage that adapts to theme changes without duplicating values keeps your code DRY.

Tailwind v4 introduces CSS custom property support that can simplify theming further. By defining colors as CSS variables and using Tailwind's var() syntax, you create themes that are easier to modify at runtime without rebuilding your CSS.

Optimization Strategies

Maintaining small bundle sizes in growing projects requires attention to a few key areas. First, configure your content paths to include only the directories that actually contain source code--exclude build directories, node_modules, and other non-source locations. Second, use arbitrary values sparingly since they can't always be optimized by the JIT compiler.

The @apply directive should be used judiciously. While it helps extract repetitive patterns into semantic class names, overusing it defeats Tailwind's purpose. The Tailwind documentation recommends reserving @apply for patterns used across multiple components (more than 3-4 times). Single-use classes should remain inline in your JSX for maximum flexibility and tree-shaking benefits. Use the Tailwind Analyzer to identify unused styles and optimize your content scanning configuration.

Issue Resolution Guide

Styles not applying: Verify your content paths in tailwind.config.js include all file extensions your project uses. If you've added new file types (like .mdx for Markdown components), ensure they're included in the glob patterns. Missing content paths are the single most common cause of missing styles.

Changes not showing: Clear your build cache and restart the development server. Vite and Next.js both cache build artifacts that sometimes become stale. In development mode, Tailwind watches for changes, but certain configuration edits require a full restart.

Dark mode flicker: This occurs when the theme prevention script isn't running early enough. Ensure the inline script is in the <head>, not after the body or loaded as a separate JavaScript file. For Next.js App Router, use next/script with strategy="beforeInteractive".

Large CSS file: The development build includes all possible classes for hot reloading. Run a production build to see the actual bundle size--production builds with JIT compilation typically generate much smaller CSS than development mode.