weapp-tailwindcss
Bring Tailwind CSS to mini programs and multi-platform apps.
简体中文 | English
## What It Is
`weapp-tailwindcss` adapts Tailwind CSS for mini program ecosystems. It transforms Tailwind-generated selectors, utility classes, and selected CSS capabilities into forms that mini programs and multi-platform frameworks can consume more reliably.
It is designed for:
- Using Tailwind CSS in WeChat, Alipay, Douyin, and other mini program environments.
- Sharing atomic CSS conventions across `uni-app` / `uni-app x`, Taro, Mpx, native mini programs, weapp-vite, and related stacks.
- Handling mini program class escaping, selector compatibility, rpx arbitrary values, CSS fallbacks, and H5/Web output differences in Tailwind CSS v4 projects.
- Building multi-platform apps that target mini programs, H5/Web, and App WebViews.
## Current Support
| Area | Support |
| ----------------- | ------------------------------------------------------------------------------------------ |
| Tailwind CSS | Tailwind CSS v4 |
| Build tools | Vite, Webpack 5, Rspack, Rollup, Rolldown, Gulp, and Node API |
| Frameworks | uni-app / uni-app x, Taro, Mpx, native mini programs, weapp-vite, and related integrations |
| Output targets | Mini programs, H5/Web, App WebView, and related platform differences |
| Runtime ecosystem | merge, variants, cva, runtime, typography, theme-transition, ui, and related packages |
| Node.js | Node.js `>=22.12.0` is required starting with `weapp-tailwindcss@5.2.0` |
Starting with `weapp-tailwindcss@5.2.0`, the minimum Node.js version is `22.12.0`, where loading ESM from CommonJS is enabled by default. Projects using HBuilderX with `uni-app` or `uni-app x` must also upgrade to HBuilderX `5.11` or later so the IDE runtime can load ESM dependencies correctly.
## Documentation
- [Official website](https://tw.icebreaker.top)
- [Quick start](https://tw.icebreaker.top/docs/quick-start/install)
- [Tailwind CSS v4 setup](https://tw.icebreaker.top/docs/quick-start/v4)
- [Framework integration](https://tw.icebreaker.top/docs/quick-start/frameworks/uni-app-vite)
- [uni-app x guide](https://tw.icebreaker.top/docs/uni-app-x)
- [Multi-platform guide](https://tw.icebreaker.top/docs/multi-platform)
- [Configuration reference](https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions)
- [FAQ](https://tw.icebreaker.top/docs/issues)
- [Mirror documentation](https://ice-tw.netlify.app/)
## Core Packages
| Package | Purpose |
| --------------------------------- | ------------------------------------------------------------------ |
| `weapp-tailwindcss` | Core transform and bundler integration entry |
| `@weapp-tailwindcss/postcss` | CSS AST processing, selector compatibility, and platform fallbacks |
| `@weapp-tailwindcss/postcss-calc` | Safe reduction for `calc()` expressions |
| `@weapp-tailwindcss/reset` | Reset stylesheet assets for mini program frameworks |
| `tailwindcss-config` | Tailwind CSS config loading |
| `tailwindcss-injector` | Tailwind directive injection and WXML dependency tracking |
| `weapp-style-injector` | Style entry injection for mini program build artifacts |
## Runtime And UI Ecosystem
| Package | Purpose |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `@weapp-tailwindcss/runtime` | Shared runtime layer for escape/unescape, caching, and rpx transforms |
| `@weapp-tailwindcss/merge` | Mini program runtime wrapper for Tailwind Merge v3 |
| `@weapp-tailwindcss/variants` | Mini program runtime wrapper for tailwind-variants |
| `@weapp-tailwindcss/cva` | Mini program runtime wrapper for class-variance-authority |
| `@weapp-tailwindcss/typography` | Mini program adapted version of Tailwind Typography |
| `theme-transition` | Theme transition runtime and Tailwind plugin |
| `@weapp-tailwindcss/ui` | Atomic UI runtime layer for mini programs |
Each package now uses Chinese as its default `README.md` and provides an English `README.en.md`.
## AI Skill
The official skills are now split by task: setup, migration, troubleshooting, runtime classes, custom builds, and React Native. The original `weapp-tailwindcss` name remains as a compatibility router. Install the complete suite with:
```bash
npx skills add sonofmagic/skills \
--skill weapp-tailwindcss \
--skill weapp-tailwindcss-setup \
--skill weapp-tailwindcss-migrate \
--skill weapp-tailwindcss-troubleshoot \
--skill weapp-tailwindcss-runtime \
--skill weapp-tailwindcss-custom-build \
--skill weapp-tailwindcss-react-native \
-y
```
The previous single-skill command remains available and routes requests to the appropriate specialized skill:
```bash
npx skills add sonofmagic/skills --skill weapp-tailwindcss
```
Read more in the [Skill documentation](https://tw.icebreaker.top/docs/ai/basics/skill).
## Contributing
Issues and pull requests are welcome:
- Report reproducible problems.
- Improve framework examples or documentation.
- Improve transforms, compatibility behavior, runtime packages, or test coverage.
Before contributing, read the repository `AGENTS.md` and the closest `AGENTS.md` under the target directory.
## License
[MIT](./LICENSE)
## Star History
[](https://star-history.com/#sonofmagic/weapp-tailwindcss&Date)