ForgeTailwind

A build-time tool your app uses to compile its Tailwind CSS. It manages the Tailwind CLI binary so you can build and watch styles without reaching for a Node setup.

Overview

Tailwind is a utility-first CSS framework: you style directly in your markup with classes, and a build step scans your templates to emit only the CSS you use. ForgeTailwind is the piece that wires that build into your app.

It is a command-line capability — it registers no request middleware and no runtime services. All it does is run the Tailwind CLI for you: fetch the standalone binary, build your styles on demand, and watch for changes while you develop.

What it gives you

  • Two CLI commands: build + watch
  • Standalone binary management
  • Minified production output
  • Multi-platform binary support
  • A hot-reload script helper

A note on scope: ForgeTailwind only compiles CSS. Your classes, the Tailwind config, and the design system all live in your app — this capability is just the build pipeline around them.

Installation 

php forge.php package:install-module --module=ForgeTailwind

That adds the two CLI commands and the helper function to your app. There is no runtime setup — the module only needs to be present for the build commands to exist.

Building

To compile your styles once, run the build command. On the first run it downloads the Tailwind binary automatically; after that it just files your source into the output: 

php forge.php modules:tailwind:build

# custom input/output
php forge.php modules:tailwind:build --input=app/UI/assets/css/tailwind.css --output=public/assets/css/app.css

By default it reads app/UI/assets/css/tailwind.css and writes public/assets/css/app.css, minified. Point --input and --output anywhere you like.

Watching & Hot Reload

During development you'll usually keep a watch running so styles rebuild every time your markup changes: 

php forge.php modules:tailwind:watch

# on a specific platform's binary
php forge.php modules:tailwind:watch --platform=linux-x64

Normally your app just links the compiled CSS. When you want instant reflection of markup changes, the forgetailwind() helper emits the hot reload script — but only when it's safe to:

  • APP_HMR is enabled, and
  • the environment is not production or staging, and
  • the request host is a local one (localhost / 127.0.0.1).

In every other situation the helper returns an empty string, so your production markup stays clean.

Binary Management

ForgeTailwind uses the official standalone Tailwind CLI, downloaded on demand and cached locally — no Node or npm required. The first time you build or watch, it:

  1. Checks for a binary at storage/bin/ (skipping download if one already exists).
  2. Downloads the right release from Tailwind's official GitHub releases into a temp file.
  3. Makes it executable and moves it into place.

The build command always targets the macos-arm64 binary, while the watch command lets you pick your platform explicitly.

Paths & Platform Support

Item Default
Input CSS app/UI/assets/css/tailwind.css
Output CSS public/assets/css/app.css
Binary directory storage/bin/
Hot reload flag APP_HMR

The watch command recognises every binary Tailwind publishes, so you can run the same setup across machines:

  • macos-arm64, macos-x64
  • windows-x64
  • linux-arm64, linux-arm64-musl
  • linux-x64, linux-x64-musl