weapp-tw CLI Guide

@weapp-tailwindcss/cli independently publishes the equivalent weapp-tw and weapp-tailwindcss commands. The build command emits Web CSS by default and follows the current Tailwind CSS CLI contract for input, output, watching, optimization, and source maps.

The npm 3.x and 4.0.0-alpha.x releases belong to the legacy native mini-program Gulp toolchain. The new Tailwind CSS CLI implementation starts on the 5.x version line. During migration, configure a CSS input as described here instead of using the legacy init, Sass/Less compilation, or project-directory scanning flow.

The CLI directly reuses the Tailwind v4 generator, design system, and source graph provided by weapp-tailwindcss. It does not install or invoke @tailwindcss/cli. Watch mode uses @parcel/watcher native file events by default; use --poll[=ms] for polling on containers, network filesystems, or environments where polling is preferable.

See Quick start: Install dependencies for installation. @weapp-tailwindcss/cli provides the command layer, weapp-tailwindcss provides generation and CSS transformation, and tailwindcss provides the Tailwind CSS v4 version used by the project.

pnpm exec weapp-tw -i src/input.css -o dist/output.css
pnpm exec weapp-tw build -i src/input.css -o dist/output.css

Build options

Option	Alias	Description
--input <file>	-i	Input CSS. Use - for stdin. Without this option the CLI uses @import "tailwindcss";.
--output <file>	-o	Output CSS. The default, or -, writes to stdout.
--watch[=always]	-w	Rebuild when dependencies change. always keeps watching after stdin closes.
--poll[=ms]		Use polling instead of the native watcher. The default interval is 250ms.
--minify	-m	Optimize and minify CSS.
--optimize		Optimize CSS without minifying it.
--cwd <dir>		Set the working directory used for input, output, and dependency resolution.
--map[=<file>]		Inline a source map or write it to the specified file.
--silent		Suppress non-error build output.
--target web|weapp		Select the CSS target. The default is web.

stdin and stdout can be combined:

pnpm exec weapp-tw -i - -o - --minify < src/input.css > dist/output.css

Watch mode:

pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch
pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch --poll=100

Mini-program CSS target

Pass --target weapp explicitly to compile Tailwind CSS and then run the result through the weapp-tailwindcss CSS compatibility pipeline:

pnpm exec weapp-tw -i src/input.css -o dist/app.wxss --target weapp

CSS-only boundary

--target weapp only transforms CSS. It does not scan or rewrite WXML, JavaScript, TypeScript, JSX, or TSX. Use the Vite, Webpack, Rspack, or Gulp integration for complete mini-program projects so templates, scripts, and styles share one classNameSet and build lifecycle.

The transformed CSS no longer has a one-to-one line mapping with the Web output, so --target weapp does not support --map.

canonicalize

canonicalize uses the Tailwind design system to collapse equivalent utilities and emit canonical candidates:

pnpm exec weapp-tw canonicalize "py-3 p-1 px-3"
# p-3

printf 'py-3 p-1 px-3\nmt-2 mr-2 mb-2 ml-2\n' \
  | pnpm exec weapp-tw canonicalize --stream

Use --css <file> to load a custom theme, plugin, or config. Select --format text|json|jsonl for machine-readable output.

Compatibility and helper commands

Command	Purpose
weapp-tw doctor [--json] [--strict]	Inspect the project setup.
weapp-tw vscode-entry --css <file>	Generate a Tailwind IntelliSense helper entry.
weapp-tw patch / install	v5 compatibility no-op; remove it from postinstall.
weapp-tw status [--json]	Return the compatibility status indicating that patching is unnecessary.

Common errors

• The command fails when input and output resolve to the same file.
• --poll must be a positive number of milliseconds.
• --map=- does not mean an inline map; pass --map without a value.
• Filesystem paths are resolved with the current Windows, macOS, or Linux path rules.