Tailwind CSS Academy · Lección

Escalar Tailwind en monorepositorios

Comparta un único tailwind.config.js entre varios paquetes de un monorepositorio, utilice presets para compartir tokens y gestione extensiones específicas de cada espacio de trabajo.

Escalar Tailwind en monorepositorios es una lección gratuita de Tailwind CSS Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Tailwind CSS Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Tailwind CSS Academy incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

Monorepo Basics for Tailwind

A monorepo is a single repository containing multiple packages or applications, managed with tools like Turborepo, Nx, or pnpm workspaces. When multiple apps in a monorepo use Tailwind, sharing configuration becomes important. Without sharing, each app duplicates color tokens, fonts, and plugin configurations — diverging gradually until the UI is inconsistent across products.

monorepo/
├── apps/
│   ├── web/          # Next.js marketing site
│   └── dashboard/    # React admin app
├── packages/
│   ├── ui/           # Shared component library
│   └── tailwind-config/  # ← Shared Tailwind config
├── package.json      # Workspace root
└── turbo.json

Creating a Shared Config Package

Extract the Tailwind configuration into a dedicated package, typically called @repo/tailwind-config or @acme/tailwind-config. This package exports a base configuration object that each consuming app imports and extends. The shared package lives in packages/tailwind-config/ with its own package.json marking it as an internal dependency.

// packages/tailwind-config/package.json
{
  "name": "@acme/tailwind-config",
  "version": "0.0.1",
  "private": true,
  "main": "./tailwind.config.js",
  "devDependencies": {
    "tailwindcss": "^3.4.0"
  }
}

// packages/tailwind-config/tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: { 500: '#3b82f6', 900: '#1e3a8a' },
      },
    },
  },
  plugins: [],
};

Consuming the Shared Config

Each app imports the shared config using require and spreads or merges it with app-specific overrides. The app's tailwind.config.js adds its own content paths (since content paths are always app-specific) and any extensions unique to that application. The shared config handles all common theme tokens and plugins.

// apps/web/tailwind.config.js
const sharedConfig = require('@acme/tailwind-config');

/** @type {import('tailwindcss').Config} */
module.exports = {
  // Merge shared config
  ...sharedConfig,
  // App-specific content paths (NEVER shared — paths differ per app)
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './public/**/*.html',
  ],
  theme: {
    ...sharedConfig.theme,
    extend: {
      ...sharedConfig.theme.extend,
      // App-specific extensions
      backgroundImage: {
        'hero-gradient': 'linear-gradient(to bottom, #eff6ff, #ffffff)',
      },
    },
  },
};

Using Tailwind Presets

Tailwind's preset system is the officially supported mechanism for sharing configs. A preset is an object passed to the presets array in the consuming config. Unlike spreading the config object, presets are merged intelligently by Tailwind — theme extensions are deep-merged, plugins are concatenated, and content arrays are combined without manual spreading.

// packages/tailwind-config/tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: { brand: { 500: '#3b82f6' } },
    },
  },
  plugins: [require('@tailwindcss/forms')],
};

// apps/dashboard/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],  // ← official preset
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      // Deep-merged with preset's theme.extend automatically
      spacing: { 18: '4.5rem' },
    },
  },
};

Shared UI Package Content Paths

A critical monorepo pitfall: if you have a shared packages/ui component library that exports Tailwind-classed components, the consuming app must include that package's files in its content array. Otherwise the JIT engine does not scan the shared components, and the classes used there get purged from the production build.

// apps/web/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],
  content: [
    // App's own files
    './src/**/*.{js,ts,jsx,tsx}',
    // ⬇ CRITICAL: include shared UI package files
    '../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Workspace Dependencies Setup

In a pnpm or npm workspace monorepo, add the shared config package as a dev dependency using the workspace protocol. This creates a symlink to the local package without publishing it to npm. The consuming app's package.json lists @acme/tailwind-config: workspace:* and the build tools resolve it to the local package automatically.

// apps/web/package.json
{
  "name": "web",
  "devDependencies": {
    "@acme/tailwind-config": "workspace:*",
    "tailwindcss": "^3.4.0"
  }
}

// Install all workspace packages from the monorepo root:
pnpm install
# or
npm install --workspaces

Turborepo Caching for Tailwind Builds

In a Turborepo monorepo, configure the turbo.json pipeline to cache Tailwind build outputs. Because the shared config is a dependency of each app's build, changes to packages/tailwind-config correctly invalidate the build cache for all consuming apps. This prevents stale cached CSS from shipping when the design system updates.

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"]
    },
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

# Build only what has changed since last run:
npx turbo build
# Turbo caches CSS output and invalidates when tailwind-config changes

Handling Content Path Differences

Content paths are the one configuration that cannot be shared — they must be local to each app. Different apps have different directory structures. Avoid temptation to put content paths in the shared config; doing so would either miss files or scan too broadly. The shared config should export only theme, plugins, and presets. Content is always defined locally in each consuming app's config.

// packages/tailwind-config/tailwind.config.js
// ⚠ DO NOT include content paths here
module.exports = {
  // content: []  ← Leave this OUT of the shared config
  theme: {
    extend: { colors: { brand: { 500: '#3b82f6' } } },
  },
  plugins: [],
};

// Each app defines its own content:
// apps/web: './src/**/*.{js,ts,jsx,tsx}'
// apps/dashboard: './pages/**/*.tsx', './components/**/*.tsx'

Versioning the Shared Config

Even though the shared config package is private (never published to npm), treat it with version discipline. Bump its version in package.json on every breaking change — removing a color, renaming a token, removing a plugin. Consumers of the preset can then pin to a version and upgrade deliberately rather than having breaking changes silently propagate to all apps at once.

// packages/tailwind-config/package.json
{
  "name": "@acme/tailwind-config",
  "version": "1.3.0",   // ← bump on breaking changes
  "private": true,
  "main": "./tailwind.config.js"
}

// apps/dashboard/package.json — pin to a specific version
{
  "devDependencies": {
    "@acme/tailwind-config": "workspace:^1.2.0"  // pin minor version
  }
}

Testing Shared Config Changes

Before merging changes to the shared Tailwind config, run a visual regression test on all consuming apps. A change to a brand color or a removed spacing value affects every app simultaneously. Build all apps in CI (turbo build) and run screenshot comparison on key pages. Treat config changes as cross-app breaking changes and communicate them in changelogs.

# Run all affected builds when tailwind-config changes
npx turbo build --filter='...[origin/main]'
# Turborepo detects which apps depend on the changed package
# and builds only those apps

# Run visual regression on changed apps:
npx playwright test --project=web
npx playwright test --project=dashboard

Storybook Integration in Monorepos

If you use Storybook in the shared UI package to document components, configure Storybook to use the same shared Tailwind preset. Add the Storybook Tailwind addon (@storybook/addon-styling-webpack or framework equivalent) and point it to the shared config. This ensures components render in Storybook with the same tokens they use in the apps.

// packages/ui/.storybook/main.js
module.exports = {
  addons: ['@storybook/addon-styling-webpack'],
  framework: '@storybook/react-webpack5',
};

// packages/ui/.storybook/preview.js
import '../src/styles/globals.css'; // imports Tailwind

// packages/ui/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
};

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

Lesson Recap

In this lesson you learned: creating a shared Tailwind config package using the official preset system for intelligent deep-merging, including shared UI package files in content paths to prevent class purging, and treating config changes as cross-app breaking changes with versioning and visual regression tests. Next up we plan a complete Tailwind design system for the capstone project.

Preguntas frecuentes

¿La lección «Escalar Tailwind en monorepositorios» es gratis?

Sí — el texto completo de «Escalar Tailwind en monorepositorios» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Tailwind CSS Academy, actualiza a CoddyKit PRO. El curso de Tailwind CSS Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Escalar Tailwind en monorepositorios»?

Comparta un único tailwind.config.js entre varios paquetes de un monorepositorio, utilice presets para compartir tokens y gestione extensiones específicas de cada espacio de trabajo. Practicas Tailwind CSS Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Tailwind CSS Academy?

No se requiere experiencia previa. Tailwind CSS Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Escalar Tailwind en monorepositorios»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Tailwind CSS Academy?

Sí. Cada lección de Tailwind CSS Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a Tailwind CSS Academy