Tailwind Impl Build Postcss CLI

Tailwind CSS PostCSS + Standalone CLI Build

Two non-Vite ways to compile Tailwind : the PostCSS plugin (drops into any bundler that runs PostCSS) and the standalone CLI (a Node script or a single binary, used when there is no bundler at all).

This skill covers BOTH Tailwind v3 and v4 because the package names, config-file shapes, and CSS entry-point syntax all differ between versions. Pick the right combination or compilation silently produces empty CSS.

Companion skills :

• tailwind-impl-build-vite : the Vite plugin path (preferred for SPAs)
• tailwind-impl-config-v3 : the v3 JS-config surface
• tailwind-impl-config-v4 : the v4 CSS-first config surface
• tailwind-core-v3-vs-v4 : every breaking change across the API
• tailwind-errors-build : when builds fail or output is empty

Quick Reference : Which Path Do You Need

Have a Vite project ?              -> tailwind-impl-build-vite
Have any other JS bundler ?         -> PostCSS plugin (this skill)
   (Webpack, Rollup, esbuild, Parcel, Laravel Mix, Encore)
Have Next.js (any version) ?        -> PostCSS plugin (this skill)
Have Remix, Nuxt, Astro (pre-v4) ?  -> PostCSS plugin (this skill)
No JS bundler at all ?              -> Standalone CLI (this skill)
   (Rails, Laravel Blade, Django, Flask, Go html/template,
    Phoenix, plain HTML, static sites)
No Node.js installed ?              -> Standalone CLI binary (this skill)

Quick Reference : Minimum v4 PostCSS Setup

npm install tailwindcss @tailwindcss/postcss postcss

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

/* src/app.css */
@import "tailwindcss";

No tailwind.config.js. No autoprefixer. No postcss-import. The v4 plugin embeds Lightning CSS, which handles vendor prefixing, @import inlining, and modern-CSS lowering internally.

Quick Reference : Minimum v3 PostCSS Setup

npm install -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}"],
  theme: { extend: {} },
  plugins: [],
};

/* src/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Note : v3 plugin name is bare tailwindcss. v4 plugin name is @tailwindcss/postcss. Mixing these (e.g. tailwindcss: {} in a v4 project) yields PostCSS error Cannot find module 'tailwindcss/postcss'.

Quick Reference : Minimum v4 CLI Setup

npm install tailwindcss @tailwindcss/cli

/* src/input.css */
@import "tailwindcss";

npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

Production build (one-shot, minified) :

npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

Quick Reference : Minimum v3 CLI Setup

npm install -D tailwindcss@3
npx tailwindcss init

/* src/input.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

Production build :

npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify

Note : v3 CLI runs as npx tailwindcss. v4 CLI runs as npx @tailwindcss/cli. The binary name is different because v4 split the CLI into its own npm package.

Decision Tree : Picking PostCSS vs CLI

Are you using a JS bundler that ALREADY runs PostCSS ?
  ├── YES (Next.js, Webpack, Rollup, Parcel, esbuild-with-postcss-plugin,
  │        Laravel Mix, Symfony Encore, Astro pre-Vite, Nuxt v3)
  │   -> Use PostCSS plugin. Add it to the existing postcss.config.
  │
  └── NO bundler at all, or non-Node backend
      ├── Have Node.js available ?
      │   ├── YES -> Use npx CLI from package.json scripts
      │   └── NO  -> Download standalone executable from GitHub releases
      │              (see `references/methods.md` § Standalone Binary)
      ├── Rails / Laravel / Django / Phoenix / Go / .NET ?
      │   -> Standalone CLI is the official recommendation
      └── Static HTML site, plain CSS workflow ?
          -> Standalone CLI with --watch in development

Decision Tree : Picking v3 vs v4

New project, no existing Tailwind code ?
  -> v4 (CSS-first config, faster builds, modern CSS features)

Existing v3 project ?
  ├── Critical browsers IE 11 or Safari < 16.4 ?
  │   -> Stay on v3 (v4 targets Safari 16.4+, Chrome 111+, Firefox 128+)
  ├── Heavy JS-plugin ecosystem (typography custom variants, complex
  │   theme functions in tailwind.config.js) ?
  │   -> Stay on v3 OR migrate gradually with @config back-compat
  └── Otherwise
      -> Migrate to v4 (see `tailwind-impl-migration-v3-v4`)

CLI Flags : Complete Reference

Both v3 and v4 CLIs share the same core flags. Listed long form first, short form second where present.

In v4 the CLI auto-detects sources in the current working directory and in directories referenced by @source directives in the entry CSS. There is no --content flag because v4 has no JS config file by default.

Decision Tree : @import "tailwindcss" vs @tailwind Trio

Tailwind v4 project ?
  -> Use ONE @import directive : @import "tailwindcss";

Tailwind v3 project ?
  -> Use THREE @tailwind directives :
       @tailwind base;
       @tailwind components;
       @tailwind utilities;

Mixing these is the most common cause of "Tailwind compiles but no utility classes appear". v3 ignores @import "tailwindcss". v4 emits warnings for @tailwind base and produces partial output.

Autoprefixer Rule (CRITICAL)

Adding autoprefixer: {} to a v4 PostCSS pipeline DOUBLE-PREFIXES properties and breaks :where(), :is(), and container query output. Removing it from v3 strips -webkit-, -moz-, -ms- from display: flex, transform, position: sticky and crashes layouts on Safari < 14, older Edge, and older Firefox.

Framework Integration Cheatsheet

Astro-with-v4 pin a known-good release : per upstream issue 16733 some Astro patch versions regress on Vite plugin compatibility.

When to Use the Standalone CLI Binary (no Node)

The standalone executable is a single self-contained binary published on GitHub releases. Use it when :

• You have no Node.js installed in your environment.
• You ship a Docker image where adding Node + node_modules is undesired (a Rails image with a single binary is smaller than one with Node).
• Your CI pipeline can download a binary faster than running npm install.
• Your team is Ruby/PHP/Python/Go/Rust and Node is not an existing dependency.

Both v3 and v4 publish standalone binaries. Download URL pattern : https://github.com/tailwindlabs/tailwindcss/releases/latest and pick the platform-matching asset (linux-x64, linux-arm64, macos-x64, macos-arm64, windows-x64). Make it executable and invoke it the same way as npx tailwindcss (v3) or npx @tailwindcss/cli (v4) but with the binary name : ./tailwindcss -i input.css -o output.css --watch.

See references/methods.md § Standalone Binary for the exact download and install steps for Linux, macOS, Windows.

Build-Script Patterns (package.json)

{
  "scripts": {
    "build:css": "npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify",
    "dev:css":   "npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch"
  }
}

For v3, swap @tailwindcss/cli for bare tailwindcss.

For a non-Node project (Rails/Django/PHP), drive the binary directly from the project's build tool. Example Rake task :

task :tailwind do
  sh "./bin/tailwindcss -i app/assets/stylesheets/application.tailwind.css " \
     "-o app/assets/builds/application.css --minify"
end

See references/examples.md for Rails, Django, Laravel Blade, and Go end-to-end patterns.

Watch Mode Mechanics

--watch does TWO things :

1. Recompiles when the input CSS file changes.
2. Re-scans content files for class names and recompiles when they change.

In v4 the watcher is the Oxide engine (Rust). In v3 it is chokidar plus the JIT compiler. Both are fast enough for sub-second incremental rebuilds on typical projects (under 200 ms in v4, 100-500 ms in v3).

CRITICAL : watch mode does NOT detect new files outside the content paths configured in v3 (content array in tailwind.config.js) or in v4 (the default scan + @source directives). If a new .html or .jsx file appears in a previously-uncovered directory, restart the watcher.

Minify Mode

--minify strips whitespace, comments, and uses shortest-form syntax. Output size reduction is typically 50-80% of unminified for a production-ready bundle. ALWAYS combine --minify with the production build, NEVER use it for --watch development.

In v4 minification ALSO triggers Lightning CSS's -Os mode :

• merges duplicate selectors
• normalises shorthand properties
• removes dead CSS

In v3 minification is cssnano-equivalent. Both versions produce deterministic output (same input -> same byte-for-byte output).

PostCSS Plugin Ordering (v3)

When the v3 PostCSS pipeline includes other plugins, ordering matters :

module.exports = {
  plugins: {
    "postcss-import": {},     // 1. inline @import statements
    "tailwindcss/nesting": {}, // 2. resolve nested rules (Tailwind's nesting plugin)
    tailwindcss: {},          // 3. expand @tailwind / utility classes
    autoprefixer: {},         // 4. add vendor prefixes
    cssnano: {},              // 5. minify in production
  },
};

v4 has NO ordering concerns because Lightning CSS replaces all of these steps internally. The v4 PostCSS config has exactly ONE plugin : "@tailwindcss/postcss": {}.

Common First-Run Errors (Quick Diagnosis)

Full anti-pattern catalogue in references/anti-patterns.md.

What This Skill Does NOT Cover

• Vite plugin setup (use tailwind-impl-build-vite)
• CSS-first config syntax (@theme, @source, @utility directives) belong in tailwind-impl-config-v4.
• JS config syntax (tailwind.config.js shape) belongs in tailwind-impl-config-v3.
• Why builds produce wrong output (debugging belongs in tailwind-errors-build).
• Migration from v3 to v4 (use tailwind-impl-migration-v3-v4).

References

• references/methods.md : Every CLI flag, every PostCSS config shape, framework-specific code, standalone binary install.
• references/examples.md : End-to-end working setups for Next.js, Remix, Astro, SvelteKit, Rails, Laravel Blade, Django, Phoenix, Go, plain HTML.
• references/anti-patterns.md : The traps : wrong plugin name, autoprefixer double-prefix, @tailwind vs @import mix-up, missing init, watch-mode pitfalls.

Official Source Links

• v4 PostCSS : https://tailwindcss.com/docs/installation/using-postcss
• v4 CLI : https://tailwindcss.com/docs/installation/tailwind-cli
• v3 PostCSS : https://v3.tailwindcss.com/docs/installation/using-postcss
• v3 install : https://v3.tailwindcss.com/docs/installation
• Standalone CLI releases : https://github.com/tailwindlabs/tailwindcss/releases