OpenWikitailwindlabs/tailwindcss

Installation

Purpose and Scope

Tailwind CSS installation is best understood as choosing where the compiler runs. The official installation page starts with the product model: Tailwind scans HTML, JavaScript components, and templates for class names, generates the corresponding CSS, and writes that CSS into the page with zero runtime for normal builds. From there, the docs route readers into setup paths for Vite, PostCSS, the standalone Tailwind CLI, framework guides, and the Play CDN. This page explains that routing model and maps it to the repository packages that make the installation choices work.

Sources: packages/tailwindcss/src/index.ts, packages/tailwindcss/package.json

The core package is named tailwindcss and is published as a utility-first CSS framework. Its package metadata exposes a style entry for index.css, TypeScript and runtime entries for the compiler, compatibility exports such as plugin, colors, defaultTheme, and direct CSS layer files including preflight.css, theme.css, and utilities.css. That export shape is why most installation guides can tell users to write a small CSS file with @import "tailwindcss": the import resolves to the framework stylesheet while the integrations use the compiler entry points to process directives, theme variables, variants, utilities, and compatibility hooks.

Sources: packages/tailwindcss/package.json, packages/tailwindcss/src/index.ts

Core Installation Paths

The recommended first path in the official docs is Vite because it is the most seamless integration for many modern frameworks and build-tool environments. The user-facing flow is intentionally short: create a Vite project, install tailwindcss plus the Vite integration, register the Tailwind plugin in vite.config.ts, import Tailwind from CSS, start the dev server, and use utility classes in markup. In repository terms, the important invariant is that Vite is only a host: the same tailwindcss package still supplies the stylesheet exports and compiler behavior behind the integration.

The PostCSS path serves projects that already have a PostCSS pipeline or framework tooling built around PostCSS plugins. Although this page's requested source set does not include the PostCSS package, the installation model remains the same: Tailwind receives CSS input containing imports, directives, functions, theme blocks, or utility requests, and an integration is responsible for loading files and handing the compiler enough context to produce output CSS. The CompileOptions type in the core package reflects this integration boundary with base, from, polyfills, loadModule, and loadStylesheet hooks.

Sources: packages/tailwindcss/src/index.ts

The CLI path is for projects that want a direct command rather than a bundler plugin. The @tailwindcss/cli entry point is an executable Node script that parses command-line arguments, exposes a default build usage of tailwindcss [--input input.css] [--output output.css] [--watch] [options…], and also supports tailwindcss build plus a canonicalize command. Installing the CLI gives users a concrete build process they can run from package scripts while still relying on the same core compiler and CSS package exports.

Sources: packages/@tailwindcss-cli/src/index.ts, packages/tailwindcss/package.json

The Play CDN path is intentionally different: it runs in the browser and is documented for development rather than production. The official docs show a script tag for @tailwindcss/browser@4 and optional custom CSS in <style type="text/tailwindcss">. The browser runtime source matches that model. It gathers style tags with the text/tailwindcss type, injects @import "tailwindcss" when the user did not provide an import, creates a compiler with base: '/', and serves virtual tailwindcss, preflight, theme, and utilities stylesheets from bundled assets.

Sources: packages/@tailwindcss-browser/src/index.ts

Relevant Source Files

  • packages/tailwindcss/src/index.ts — Defines the core compiler surface, compile options, feature flags, CSS parsing path, directive handling, theme processing, imports, variants, utilities, and compatibility hooks used by build-tool integrations.
  • packages/tailwindcss/package.json — Publishes the tailwindcss package name, framework description, style entry, package exports, CSS layer files, compatibility exports, build scripts, and publish-time export map.
  • package.json — Defines monorepo-level scripts and tooling assumptions such as pnpm, turbo, vitest, Cargo tests, package builds, and playground commands used by contributors and local package development.
  • packages/@tailwindcss-browser/src/index.ts — Implements the browser runtime used by the Play CDN workflow, including text/tailwindcss style discovery, virtual stylesheet loading, compiler creation, rebuild scheduling, and instrumentation.
  • packages/@tailwindcss-cli/src/index.ts — Implements the tailwindcss executable entry point, command dispatch, help output, shared options, build command routing, and canonicalization command routing.
  • packages/@tailwindcss-node/src/index.ts — Re-exports Node-facing compile, optimization, source-map, path normalization, instrumentation, and environment APIs, and registers ESM cache hooks when supported.

System-to-Code Mapping

Installation guide choices map to a small set of shared primitives rather than separate frameworks. The first primitive is CSS input, usually a file containing @import "tailwindcss". The second is a host integration, such as Vite, PostCSS, CLI, browser runtime, or a framework guide that wraps one of those. The third is the compiler, which parses CSS into an internal AST, substitutes imports, handles @apply, evaluates CSS functions, builds the design system, and compiles class candidates into rules. The public package exports make the same CSS layers available whether the host is a bundler, command, or browser script.

Sources: packages/tailwindcss/src/index.ts, packages/tailwindcss/package.json

The Node-facing package exists for integrations that need filesystem-aware compilation, optimization, source maps, normalization, instrumentation, and environment helpers. Its index re-exports those modules and configures module resolution hooks for ESM cache behavior in supported Node versions, while avoiding that hook path in Bun. This matters during installation because most production workflows are Node-based even when users interact with a framework command. The framework or build tool may hide Tailwind's internals, but it still needs stable Node APIs to load CSS, plugins, config modules, dependencies, and source maps consistently.

Sources: packages/@tailwindcss-node/src/index.ts

At the repository level, installation packages are developed in a monorepo managed with pnpm and turbo. The root scripts define broad workflows such as build, dev, test, test:integrations, and playground shortcuts like vite and nextjs. These scripts are not end-user installation commands, but they explain how maintainers validate the installation surfaces together. A change to the core compiler, browser runtime, or CLI can be built and tested alongside Rust crates, integration tests, and package-specific test suites before it becomes part of the published installation experience.

Sources: package.json

Execution Flow

A production installation typically begins when the user installs tailwindcss and one host integration, then creates an input CSS file. When the host starts, it resolves the CSS export from the package, invokes the compiler with a project base path, and supplies loader callbacks when external stylesheets, plugins, or config files must be resolved. The compiler records which major Tailwind features appear in the CSS, including imports, JavaScript plugin or config compatibility, theme functions, utilities, variants, and theme blocks. The host then writes generated CSS to the bundler pipeline, an output file, or a development server response.

Sources: packages/tailwindcss/src/index.ts

A browser installation through the Play CDN compresses that flow into the page itself. The runtime creates a style element for compiled output, observes Tailwind style blocks, concatenates their content, and skips compiler recreation when the CSS text has not changed. It tracks classes already seen on the page so incremental builds can pass only new candidates to the compiler. This design is suitable for experiments and documentation examples because the browser can react to page content and custom CSS immediately, but the official docs mark it as development-only instead of a production deployment path.

Sources: packages/@tailwindcss-browser/src/index.ts

Command and Package Reference

Use this compact reference when deciding which installation page to follow. For the default Vite route, install tailwindcss plus the Vite integration and import Tailwind from CSS. For an existing PostCSS pipeline, install tailwindcss with the PostCSS integration and let PostCSS call into Tailwind as part of CSS processing. For direct builds, install the CLI and run the executable with input, output, and watch flags. For throwaway browser experiments, add the @tailwindcss/browser@4 script and optional text/tailwindcss styles. For framework-specific conventions, start with the official framework guides before dropping down to CLI, Vite, or PostCSS.

npm install tailwindcss
npm install tailwindcss @tailwindcss/vite
tailwindcss --input input.css --output output.css --watch
tailwindcss build --input input.css --output output.css

Important exported package names and paths include tailwindcss, tailwindcss/plugin, tailwindcss/colors, tailwindcss/defaultTheme, tailwindcss/index.css, tailwindcss/preflight.css, tailwindcss/theme.css, and tailwindcss/utilities.css. Important CLI command names include build, canonicalize, and --help. Important browser conventions include the @tailwindcss/browser@4 script URL shown in the official docs and the text/tailwindcss style type implemented by the runtime. These are the installation-level handles readers should recognize before moving into the detailed Vite, PostCSS, CLI, Play CDN, or framework pages.

Sources: packages/tailwindcss/package.json, packages/@tailwindcss-cli/src/index.ts, packages/@tailwindcss-browser/src/index.ts

Next Steps

If you are starting a new app with a supported modern toolchain, continue to the Vite installation page first. If your framework has its own documented setup, use the framework guide because it may handle stylesheet inclusion, dev-server integration, and production builds differently. If you are integrating Tailwind into an existing CSS pipeline, read the PostCSS page. If you need a minimal command that writes CSS files, read the CLI reference. If you only want to try utilities in one HTML file, use the Play CDN page, then migrate to a build-time installation before production.

Ask a question...