How to Integrate Bolt.new with Tailwind CSS

When you create a new Bolt.new project, the project structure already includes everything you need for Tailwind: the tailwind CSS package installed in node_modules, a tailwind.config.js file in the project root with the content array pointing to your source files, a postcss.config.js file that enables Tailwind's PostCSS plugin, and the @tailwind base, @tailwind components, @tailwind utilities directives in your main CSS file (index.css for Vite projects, globals.css for Next.js). Bolt's default Tailwind config extends the base theme with shadcn/ui's color system — CSS custom properties (CSS variables) like --background, --foreground, --primary, --secondary, --muted, --accent, --destructive, and --ring are defined in the CSS file and mapped to Tailwind color utilities. This means shadcn/ui components automatically use your theme. The CSS variable approach is how shadcn/ui handles dark mode — you change the variable values in a .dark class selector and all components switch appearance. When you use Bolt's built-in dark mode toggle, it works through this CSS variable system. To see the current Tailwind configuration, use Bolt's Dev Mode (requires paid plan) to browse the file tree, or ask Bolt's chat: 'Show me my tailwind.config.js file'. Understanding this default setup prevents confusion when you add custom colors and they do not appear — the most common cause is putting custom colors in the wrong place in the config (they must go in theme.extend, not theme, to avoid overwriting the default palette).

1// tailwind.config.js — default Bolt.new structure
2/** @type {import('tailwindcss').Config} */
3module.exports = {
4  darkMode: ['class'],
5  content: [
6    './pages/**/*.{ts,tsx}',
7    './components/**/*.{ts,tsx}',
8    './app/**/*.{ts,tsx}',
9    './src/**/*.{ts,tsx}',
10  ],
11  theme: {
12    container: {
13      center: true,
14      padding: '2rem',
15      screens: { '2xl': '1400px' },
16    },
17    extend: {
18      colors: {
19        // shadcn/ui CSS variable color system
20        border: 'hsl(var(--border))',
21        input: 'hsl(var(--input))',
22        ring: 'hsl(var(--ring))',
23        background: 'hsl(var(--background))',
24        foreground: 'hsl(var(--foreground))',
25        primary: {
26          DEFAULT: 'hsl(var(--primary))',
27          foreground: 'hsl(var(--primary-foreground))',
28        },
29        // ... other shadcn/ui color tokens
30      },
31    },
32  },
33  plugins: [require('@tailwindcss/typography'), require('tailwindcss-animate')],
34};

The most impactful Tailwind customization is adding your brand colors so you can use them as Tailwind utility classes throughout your app. Open your tailwind.config.js (ask Bolt's chat to 'show me tailwind.config.js' or open it in Dev Mode) and add your brand colors inside theme.extend.colors. Use a color scale from 50 (lightest) to 950 (darkest) — tools like uicolors.app or palette generation tools can generate a full scale from a single brand color hex value. Once added, you can use bg-brand-500, text-brand-700, border-brand-200, etc. as Tailwind classes. For typography, add your preferred Google Font by including the font-face import in your CSS file and extending tailwind.config.js's fontFamily. Always use theme.extend for fontFamily to keep the default font stack as a fallback. The defaultTheme import from 'tailwindcss/defaultTheme' provides the default font stacks to spread after your custom font, ensuring a graceful fallback. For text sizes, heading weights, and line heights, you can override Tailwind's defaults in theme.extend.fontSize, theme.extend.fontWeight, and theme.extend.lineHeight. For consistent spacing that goes beyond Tailwind's default scale, add values in theme.extend.spacing using the numeric key equals pixel value convention (e.g., '18': '72px' gives you p-18, m-18, w-18, etc.). Ask Bolt's AI to make these changes — describe what you want in plain English and Bolt will update the config file correctly.

1// tailwind.config.js — with brand customization
2/** @type {import('tailwindcss').Config} */
3const defaultTheme = require('tailwindcss/defaultTheme');
4
5module.exports = {
6  darkMode: ['class'],
7  content: ['./src/**/*.{ts,tsx}', './index.html'],
8  theme: {
9    extend: {
10      colors: {
11        // Keep all shadcn/ui color tokens (do not replace theme.colors!)
12        border: 'hsl(var(--border))',
13        input: 'hsl(var(--input))',
14        ring: 'hsl(var(--ring))',
15        background: 'hsl(var(--background))',
16        foreground: 'hsl(var(--foreground))',
17        primary: {
18          DEFAULT: 'hsl(var(--primary))',
19          foreground: 'hsl(var(--primary-foreground))',
20        },
21        // Add brand colors
22        brand: {
23          50: '#f0f9ff',
24          100: '#e0f2fe',
25          200: '#b9e7fe',
26          300: '#7dd3fc',
27          400: '#38bdf8',
28          500: '#0ea5e9',
29          600: '#0284c7',
30          700: '#0369a1',
31          800: '#075985',
32          900: '#0c4a6e',
33          950: '#082f49',
34        },
35      },
36      fontFamily: {
37        sans: ['Inter', ...defaultTheme.fontFamily.sans],
38      },
39    },
40  },
41  plugins: [require('@tailwindcss/typography'), require('tailwindcss-animate')],
42};

As you build more complex components, you will encounter a common Tailwind problem: merging class names with conditional logic. For example, a Button component that accepts a variant prop ('primary', 'secondary', 'danger') needs to apply different Tailwind classes based on the variant. The naive approach — string concatenation or template literals — often results in duplicate or conflicting classes (e.g., 'p-4 p-2' where the last one wins but both are in the output). Tailwind Merge (the twMerge function from the tailwind-merge package) resolves class conflicts intelligently: it knows that p-4 and p-2 conflict on the same dimension and keeps only the last one. The cn() utility function — which is already included in Bolt's projects via shadcn/ui — combines clsx (for conditional class logic) and twMerge (for conflict resolution). Use cn() wherever you combine Tailwind classes with conditions. The cn() function is typically exported from a lib/utils.ts file in Bolt projects. Arbitrary value syntax (using square brackets like w-[137px] or mt-[calc(100vh-4rem)]) is a powerful Tailwind v3 feature for one-off values that do not fit the standard scale — use sparingly for layout calculations and pixel-perfect adjustments. Important Tailwind v3 vs v4 distinction: in v3, arbitrary values use standard square bracket syntax. In v4, some configurations moved to CSS files using @theme. If Bolt's AI generates v4-style configuration code (using @import 'tailwindcss' or @theme blocks), it will not work in Bolt's default v3 setup.

1// lib/utils.ts — standard Bolt/shadcn/ui utility
2import { type ClassValue, clsx } from 'clsx';
3import { twMerge } from 'tailwind-merge';
4
5export function cn(...inputs: ClassValue[]) {
6  return twMerge(clsx(inputs));
7}
8
9// components/Button.tsx — using cn() for variant merging
10import { cn } from '@/lib/utils';
11import { ButtonHTMLAttributes, forwardRef } from 'react';
12
13interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
14  variant?: 'primary' | 'secondary' | 'danger';
15  size?: 'sm' | 'md' | 'lg';
16}
17
18const variantClasses = {
19  primary: 'bg-brand-600 text-white hover:bg-brand-700 focus:ring-brand-500',
20  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-300',
21  danger: 'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500',
22};
23
24const sizeClasses = {
25  sm: 'px-3 py-1.5 text-sm',
26  md: 'px-4 py-2 text-base',
27  lg: 'px-6 py-3 text-lg',
28};
29
30export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
31  ({ className, variant = 'primary', size = 'md', ...props }, ref) => (
32    <button
33      ref={ref}
34      className={cn(
35        'inline-flex items-center justify-center rounded-md font-medium',
36        'transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2',
37        'disabled:opacity-50 disabled:cursor-not-allowed',
38        variantClasses[variant],
39        sizeClasses[size],
40        className // Allow parent to override via className prop
41      )}
42      {...props}
43    />
44  )
45);
46
47Button.displayName = 'Button';

The single most confusing Tailwind issue in Bolt.new is the version difference: Bolt uses Tailwind v3, but Tailwind v4 was released in early 2025. Tailwind v4 is a major rewrite that changes how Tailwind is configured and used. In v4, configuration moves from tailwind.config.js to a CSS file using the @theme directive. In v4, plugins use a new JavaScript API. Some class name behaviors changed. The create-next-app default now scaffolds Tailwind v4, which means code snippets from Next.js tutorials or AI-generated code that references v4 patterns will not work in Bolt's v3 setup. The most common symptoms of v3/v4 confusion in Bolt: Bolt generates code using @import 'tailwindcss' in a CSS file (v4 syntax) and the styles do not apply; class names like text-balance or field-sizing-content appear (v4-specific utilities not in v3); or someone follows a Next.js 15 tutorial that installs Tailwind v4 and the tailwind.config.js format no longer works. If you encounter this, check package.json for the tailwindcss version. If it shows ^4.x, you have v4 and need to use v4's CSS-based config format. If it shows ^3.x, you have v3 and use tailwind.config.js. Another common gotcha: Tailwind's JIT (just-in-time) compiler purges classes not found in the content array. If you generate Tailwind class names dynamically in JavaScript (e.g., `bg-${color}-500`), the purger does not see the static class names and removes them. Add dynamically generated classes to the safelist in tailwind.config.js. Finally, Tailwind's @tailwindcss/typography prose classes apply sensible styling to arbitrary HTML — useful for blog content, documentation, or any HTML you do not control. Use prose, prose-lg, and dark:prose-invert in your layout components.

1// tailwind.config.js — with safelist for dynamic classes
2/** @type {import('tailwindcss').Config} */
3module.exports = {
4  darkMode: ['class'],
5  content: [
6    './src/**/*.{js,ts,jsx,tsx}',
7    './pages/**/*.{js,ts,jsx,tsx}',
8    './components/**/*.{js,ts,jsx,tsx}',
9    './app/**/*.{js,ts,jsx,tsx}',
10  ],
11  safelist: [
12    // Dynamically generated status colors — must be safelisted
13    { pattern: /bg-(red|green|yellow|blue|brand)-(100|500|600)/ },
14    { pattern: /text-(red|green|yellow|blue|brand)-(700|800)/ },
15    { pattern: /border-(red|green|yellow|blue|brand)-(300|500)/ },
16  ],
17  theme: {
18    extend: {
19      // your custom extensions here
20    },
21  },
22  plugins: [
23    require('@tailwindcss/typography'),
24    require('tailwindcss-animate'),
25  ],
26};