Standalone packaging
The standalone package turns the Tailwind command-line interface into a self-contained executable. It joins the CLI with Tailwind's compiler, built-in CSS assets, JavaScript APIs, first-party plugins, and the native scanner needed for project builds. A release provides one executable for each supported host target and a checksum file for download checks.
Packaging boundary
The standalone package is the file-based delivery path for users who need the CLI without a separate Node setup. It shares the command behavior of the regular CLI build workflow, but its output is a native executable rather than a package-manager entry point.
The package includes the following product capabilities:
- Read CSS from a file or standard input.
- Scan project files for class candidates.
- Load supported config files and plugins.
- Write CSS to a file or standard output.
- Watch project files and rebuild when they change.
- Expose the Tailwind JavaScript APIs to local plugins and configs.
The standalone package is private in the workspace. Its useful release output is the set of files in its dist directory, not an npm package installed by users. See Runtime delivery for how this path fits with the browser and Node delivery paths.
References: packages/…/package.json• L2-34 packages/…/index.ts• L1-80 packages/…/index.ts• L125-327 packages/…/index.ts• L64-98
Executable assembly
The executable assembly combines the CLI entry point with the runtime resources that a normal package install would resolve at run time. The standalone entry point supplies embedded Tailwind CSS files and maps requests for Tailwind modules to those embedded resources.
The assembly also keeps the CLI's extension boundary useful. The executable carries the Tailwind JavaScript APIs needed by local plugins and includes the supported first-party plugins. Project files remain external input, so a user can run the same build model against a project directory.
This diagram shows how the packaged CLI combines built-in resources with project input to produce CSS.
flowchart LR
A[CLI entry point] --> D[Standalone executable]
B[Tailwind compiler and CSS assets] --> D
C[JavaScript APIs and first-party plugins] --> D
E[Project CSS and content files] --> D
D --> F[Generated CSS file or standard output]
The executable excludes its own file from candidate scanning. This prevents the binary itself from adding unrelated class names when a user runs it from a project or repository.
Embedded resources
The standalone runtime embeds the main Tailwind stylesheet and its preflight, theme, and utilities entry points. It also makes the public JavaScript APIs available to plugin code through static bundle entries, which keeps those APIs present after compilation.
This resource boundary is different from the browser package. The standalone executable can still resolve project files and supported plugins, while the browser path is limited to resources embedded in its browser bundle.
References: packages/…/index.ts• L4-7 packages/…/index.ts• L23-62 packages/…/index.ts• L64-96 packages/…/index.ts• L278-327 packages/…/package.json• L27-54
Native runtime inputs
The standalone build receives platform-specific runtime inputs for the supported host targets. Its package definition includes the platform variants needed for file watching and CSS processing, while the build also includes the native scanner inputs required for the selected target and removes the unused WASI path from the compiled executable. Linux builds receive a fixed libc choice so a glibc build and a musl build do not need to choose between native variants at run time.
The standalone target list is narrower than the full native scanner package matrix. For example, the native package set includes Android, FreeBSD, Windows arm64, and WASI targets, while the standalone release currently publishes Linux arm64 and x64 variants, macOS arm64 and x64 variants, and Windows x64.
References: packages/…/package.json• L36-54 packages/…/build.ts• L53-63 crates/…/package.json• L11-32 crates/…/package.json• L63-75
Platform artifact matrix
The build creates one named executable per supported runtime target. The name is part of the download contract because release users and integration checks use it to select a file before execution.
| Host target | Artifact name | Selection note |
|---|---|---|
| Linux arm64 with glibc | tailwindcss-linux-arm64 | Default Linux arm64 artifact |
| Linux arm64 with musl | tailwindcss-linux-arm64-musl | For musl-based Linux systems |
| Linux x64 with glibc | tailwindcss-linux-x64 | Uses a baseline x64 target for older CPUs |
| Linux x64 with musl | tailwindcss-linux-x64-musl | Uses a baseline x64 target for older CPUs |
| macOS arm64 | tailwindcss-macos-arm64 | For Apple silicon |
| macOS x64 | tailwindcss-macos-x64 | Uses a baseline x64 target |
| Windows x64 | tailwindcss-windows-x64.exe | Windows executable name includes .exe |
The x64 baseline targets favor broad CPU support over newer instruction sets. Linux libc is a compatibility choice as well as a platform choice: a musl system needs the musl artifact, while a glibc system needs the glibc artifact.
References: packages/…/build.ts• L22-34 integrations/…/standalone.test.ts• L6-17
Artifact selection
Selection happens before the executable starts. A launcher, download step, or integration test maps the host operating system and CPU architecture to the matching artifact name. Linux also requires the correct libc variant when the environment is musl-based.
This diagram shows how host details determine the executable that runs the standalone CLI.
flowchart TD
A[Host operating system and CPU] --> B{Supported host?}
B -- no --> C[Stop with unsupported target]
B -- yes --> D{Linux libc}
D -- glibc --> E[Select glibc Linux artifact]
D -- musl --> F[Select musl Linux artifact]
B -- macOS --> G[Select macOS arm64 or x64 artifact]
B -- Windows --> H[Select Windows x64 executable]
E --> I[Run standalone CLI]
F --> I
G --> I
H --> I
The repository's platform checks select macOS by architecture and select Linux by architecture. They do not expose a FreeBSD or Windows arm64 standalone artifact because those targets are not in the standalone executable matrix. Native package support for those environments does not imply standalone binary support.
References: integrations/…/standalone.test.ts• L6-17 integrations/…/index.test.ts• L10-29 packages/…/build.ts• L53-63
Release flow
Release preparation builds the native scanner first and then builds the workspace with those artifacts available. The standalone build produces its executable set and checksum file in packages/@tailwindcss-standalone/dist; the release workflow uploads that directory as a named artifact and attaches the selected files to a draft GitHub release.
When a release is published, the release process also builds and publishes the npm packages. The standalone files remain GitHub release assets because the standalone workspace is private. Version changes keep the CLI and standalone package in sync so the executable and the published CLI describe the same product version.
When the release process runs, it follows this sequence:
- Build native scanner artifacts for the supported targets.
- Make those artifacts available to the workspace build.
- Build the Tailwind packages and the standalone executables.
- Produce sha256sums.txt from the executable contents.
- Upload the standalone directory as a CI artifact.
- Attach the executable files and checksum file to the draft GitHub release when release preparation is not a dry run.
The checksum file records one SHA-256 value for each executable. It lets a user or release tool verify that a downloaded file matches the artifact produced by the build.
Version alignment
The version script treats @tailwindcss/cli and @tailwindcss/standalone as a synced pair. A CLI version update therefore propagates to the standalone package instead of allowing the two command-line delivery forms to drift.
References: scripts/version-packages.mjs• L13-37 scripts/version-packages.mjs• L143-171 .github/…/prepare-release.yml• L234-283 .github/…/prepare-release.yml• L291-307
Checksum artifacts
The standalone build hashes each completed executable after Bun writes it. It writes the results as sha256sums.txt beside the binaries, and the release job includes that file with the executable assets.
The checksum covers the final file bytes. Any rebuild or post-build change creates a different value, so checksum generation must remain after executable creation and before release upload.
References: packages/…/build.ts• L36-48 packages/…/build.ts• L88-106 .github/…/prepare-release.yml• L279-307
Change checklist
When these files or sections are changed, remember to consider these:
- Standalone target names in packages/…/build.ts: keep the Bun target, output name, platform selector, and release asset list aligned.
- Linux libc handling: verify that glibc and musl builds still contain only the native runtime for the selected libc.
- CLI entry points or Tailwind CSS exports: confirm that the executable still carries the CLI, embedded CSS resources, and JavaScript APIs needed by plugins.
- Native scanner target declarations in crates/…/package.json: distinguish native npm package support from standalone executable support.
- Platform-specific package inputs in packages/…/package.json: keep every watcher and CSS processing variant needed by the supported build targets.
- Version synchronization in scripts/version-packages.mjs: keep the CLI package and standalone package on the same release version.
- Checksum generation and release upload: ensure every published executable has one matching line in sha256sums.txt.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A user selects a Linux binary with the wrong libc | The executable may fail to start or fail to load its native scanner | Detect the host libc and select the matching glibc or musl artifact |
| A target name changes in the standalone build but not in the selector or release job | A supported host cannot find its binary or a release omits an artifact | Treat target names as one contract across the build, selectors, tests, and workflow |
| A required native package is removed from standalone build inputs | Bun cannot include the native runtime needed by a compiled executable | Keep the platform packages required for static analysis and target builds in the standalone package inputs |
| A CLI or Tailwind API is not statically included | Local config or plugin code fails when run from the standalone executable | Keep the standalone entry point and its bundled API mappings aligned with CLI and Tailwind exports |
| A checksum is created before the final executable bytes exist | Users cannot verify the downloaded release asset | Generate checksums after all executables are built and before release upload |
| CLI and standalone versions drift | Users see different versions for equivalent command-line delivery paths | Update them through the synced version mapping |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Shows how the CLI, embedded CSS assets, plugin support, and JavaScript APIs meet in the executable |
| packages/…/build.ts | Defines the standalone target matrix, target-specific native choices, executable names, and checksums |
| packages/…/package.json | Defines the private standalone package boundary and the platform inputs used to build it |
| packages/…/index.ts | Shows the command entry point that standalone packaging carries into the executable |
| packages/…/index.ts | Shows how the packaged build command scans project input, excludes its own executable, and supports rebuilds |
| crates/…/package.json | Shows the broader native scanner target set and its separation into platform packages |
| scripts/version-packages.mjs | Shows how CLI and standalone versions stay aligned for releases |
| .github/…/prepare-release.yml | Shows how native artifacts become standalone release assets and checksums |
| integrations/…/standalone.test.ts | Shows that the selected executable runs project builds and supports first-party plugins and JavaScript APIs |