Documentation menu
On this page
Packages · v2.x
Tailwind
The Tailwind package (src/packages/Tailwind) runs the official Tailwind CSS v4 standalone CLI: no Node.js, no npm.
It downloads the CLI, prepares the CSS file and compiles it into the assets published by the Assets component.
Module
| Manager | NeoPHP\Package\Tailwind\TailwindManager (final) |
| Interface | NeoPHP\Package\Tailwind\TailwindManagerInterface |
| Attribute | #[Package(provider: TailwindProvider::class)] |
| Requires | nothing |
Inject TailwindManagerInterface in a service, a command or a controller:
use NeoPHP\Package\Tailwind\TailwindManagerInterface;
public function __construct(private TailwindManagerInterface $tailwind)
{
}
The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):
NeoPHP\Package\Tailwind\TailwindManager::class => false,
The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.
Quick start
php bin/neo tailwind:install
php bin/neo tailwind:run --watch
php bin/neo tailwind:run --minify
tailwind:installasks the CSS file (css/app.css), downloads the CLI and prepares the file.tailwind:run --watchrecompiles while developing (Ctrl+C to stop).tailwind:run --minifybuilds the final CSS before deploying.
Installing
tailwind:install [input] [--tailwind-version=4.1.13] (plus the global --force):
- downloads the CLI of the operating system (Windows, macOS, Linux, x64 / arm64, musl) from the GitHub releases into
var/tailwind/tailwindcss(.exeon Windows) and writes the installed version invar/tailwind/VERSION;--forcedownloads it again - creates
assets/<input>with@import "tailwindcss";, or adds this import at the top of an existing file - checks the SHA-256 checksum of the download with
sha256sums.txtof the release - saves the file name and the installed version in
config/packages/tailwind.yaml
input is relative to assets/ (default: the configured input, else css/app.css).
Compiling
tailwind:run [input] [--watch|-w] [--minify|-m] compiles assets/css/app.css into var/tailwind/css/app.css, then publishes it with the assets (public/builds/css/app-{hash}.css).
| Option | Description |
|---|---|
input |
the CSS file relative to assets/ (default: input of tailwind.yaml) |
--watch, -w |
recompiles on every change of the templates or the CSS |
--minify, -m |
minifies the CSS |
Tailwind v4 finds the classes itself by scanning the project (the files ignored by .gitignore, such as vendor/ and var/, are skipped). Add @source for other directories and customize the theme with @theme:
@import "tailwindcss";
@source "../../other/path";
@theme {
--color-brand: #4f46e5;
}
Using the CSS
The templates keep the usual asset() helper (see the Assets documentation):
<link rel="stylesheet" href="{{ asset('css/app.css') }}">
<link rel="stylesheet" href="<?= $this->e($this->asset('css/app.css')) ?>">
- With
--watchin debug (auto_compile),asset()serves the new file on the next request. - In production, run
tailwind:run --minify(thenasset:reloadif needed) on every deployment. - When the file was never compiled,
asset()publishes the source file.
The compiled file replaces the source of the asset through AssetManagerInterface::setSourceFile().
Configuration
config/packages/tailwind.yaml:
input: css/app.css
version: latest
binary: ~
verify_checksum: true
| Key | Description |
|---|---|
input |
Tailwind CSS file, relative to assets/ |
version |
version downloaded by tailwind:install (latest or e.g. 4.1.13); tailwind:install replaces latest by the installed version |
binary |
path of an existing Tailwind CLI (absolute or relative to the project): nothing is downloaded |
verify_checksum |
true by default; false skips the checksum check, for a release without sha256sums.txt |
TailwindManagerInterface
Inject NeoPHP\Package\Tailwind\TailwindManagerInterface (implemented by NeoPHP\Package\Tailwind\TailwindManager) to drive Tailwind from code:
<?php
declare(strict_types=1);
namespace App\Service;
use NeoPHP\Package\Tailwind\TailwindManagerInterface;
class CssBuilder
{
public function __construct(private TailwindManagerInterface $tailwind)
{
}
public function build(): int
{
if (!$this->tailwind->isInstalled()) {
$this->tailwind->install();
}
return $this->tailwind->run($this->tailwind->getInput() ?? TailwindManagerInterface::DEFAULT_INPUT, minify: true);
}
}
| Method | Description |
|---|---|
getInput(): ?string / setInput(string $input): static |
the configured CSS file |
getVersion(): string |
the configured version |
getBinary(): string |
path of the CLI |
isInstalled(): bool / getInstalledVersion(): ?string |
installation state |
getPlatform(): string |
the release file name of the CLI (e.g. tailwindcss-linux-x64) |
getDownloadUrl(?string $version = null): string |
URL of the CLI release |
install(?string $version = null, bool $force = false): array |
downloads the CLI and checks its checksum |
getSourceFile(string $input): string / getOutputFile(string $input): string |
source (assets/) and compiled (var/tailwind/) paths |
initSource(string $input): string |
creates the file or adds the import |
getCommand(string $input, bool $watch = false, bool $minify = false): array |
the CLI command line |
run(string $input, bool $watch = false, bool $minify = false): int |
runs the CLI, returns its exit code |
saveConfig(): string |
writes config/packages/tailwind.yaml |
Constants: TailwindManagerInterface::DEFAULT_INPUT (css/app.css), DEFAULT_VERSION (latest); TailwindManager::RELEASES_URL, DIRECTORY (var/tailwind), CONFIG_FILE, IMPORT (@import "tailwindcss";), CHECKSUM_FILE (sha256sums.txt).
Errors throw NeoPHP\Package\Tailwind\Exception\TailwindException (extends FrameworkException).
Requirements
tailwind:installneedsallow_url_fopenand theopensslextension.tailwind:runneedsproc_open().var/must stay out of Git (neo installadds it to.gitignore).
Changelog
- v2.12.0 —
tailwind:installchecks the checksum of the download (verify_checksum) and saves the installed version instead oflatest. - v2.0.0 —
TailwindManageris thefinalentry point of the module, declared with#[Package];TailwindManagerInterfacereplacesContract\TailwindInterface;Contract\AbstractTailwindis merged into the manager; the internal classes are marked@internal. - v1.18.0 — Tailwind package:
tailwind:installdownloads the Tailwind CSS v4 standalone CLI and prepares the CSS file,tailwind:run [--watch] [--minify]compiles it intovar/tailwind/and publishes it with the assets,config/packages/tailwind.yaml.