Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UnifiedWebpackPluginV5
✓ import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss/webpack';
✗ const UnifiedWebpackPluginV5 = require('weapp-tailwindcss/webpack');
Use this named import for Webpack 5 projects. The `weapp-tailwindcss` ecosystem primarily uses ESM, and a convenient alias `weappTailwindcss` is also exported from v4.11.0.
UnifiedViteWeappTailwindcssPlugin
✓ import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite';
✗ const UnifiedViteWeappTailwindcssPlugin = require('weapp-tailwindcss/vite');
Use this named import for Vite projects. An alias `weappTailwindcss` is also exported from v4.11.0 for unified access.
weappTailwindcss
✓ import { weappTailwindcss } from 'weapp-tailwindcss/webpack';
✗ import weappTailwindcss from 'weapp-tailwindcss/webpack/some-other-path';
This alias was introduced in `weapp-tailwindcss@4.11.0` to provide a unified, simplified import name across all bundler plugin entry points (webpack, vite, gulp). It is a named export.
createPlugins
✓ import { createPlugins } from 'weapp-tailwindcss/gulp';
✗ const createPlugins = require('weapp-tailwindcss/gulp');
Use this named import for Gulp projects. As with other plugins, `weappTailwindcss` is an alias from v4.11.0.
Demonstrates how to integrate the `weapp-tailwindcss` plugin within a Vite project. This quickstart includes essential `vite.config.ts` and `tailwind.config.js` configurations for WeChat Mini Programs, showing setup for `rpx` conversion, PostCSS plugins, and critical `content` path definitions.
/* vite.config.ts */
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { UnifiedViteWeappTailwindcssPlugin as VitePlugin } from 'weapp-tailwindcss/vite';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
vue(),
VitePlugin({
// Enable auto-conversion of `rem` units to `rpx` (WeChat Mini Program units)
rem2rpx: true,
// Define the base viewport width for `rpx` conversion (e.g., 750 for design drafts)
viewportWidth: 750,
// The 'css' option ensures that content is processed correctly
// for mini-program environments and handles specific CSS transformations.
css: true,
// Additional options can be configured here. Refer to the official documentation:
// https://tw.icebreaker.top/docs/configuration-reference/options
}),
],
css: {
postcss: {
plugins: [
require('tailwindcss'),
require('autoprefixer')
],
},
},
});
/* tailwind.config.js */
/** @type {import('tailwindcss').Config} */
module.exports = {
// Crucially, `content` must include all files where Tailwind classes are used.
// This includes templates (.vue, .wxml) and script files (.js, .ts) for dynamic classes.
content: [
'./index.html',
'./src/**/*.{vue,js,ts,jsx,tsx,wxml,wxss}',
],
theme: {
extend: {},
},
plugins: [],
corePlugins: {
// Tailwind's preflight base styles can conflict with mini-program default styles.
// Disabling it often provides a cleaner slate for mini-program development.
preflight: false,
// Ensure essential core plugins for mini-programs are enabled or configured if needed.
},
};
Debug
Known issues
breakingThe `weapp-tailwindcss` core library, which `weapp-tw` relies on, requires Node.js version `^20.19.0 || >=22.12.0` for its 4.x releases. Projects using older Node.js versions must upgrade their environment or opt for an older, compatible version of the plugin.fixUpgrade your Node.js environment to an LTS version within the specified range (e.g., 20.x or 22.x). Alternatively, if using Tailwind CSS v2, you may need to use `weapp-tailwindcss` 1.x and Node.js >=16.6.0.
affects: >=4.0.0 (for weapp-tailwindcss)
gotchaDevelopers might encounter residual or incorrect `:not(#n)` or `:not(#\#)` placeholder selectors in compiled WXSS/CSS. This often occurs with older `weapp-tailwindcss` versions or specific misconfigurations in Taro/Weapp build environments, signifying incomplete CSS processing.fixEnsure `weapp-tailwindcss` (and any related `@weapp-tailwindcss/*` packages) are updated to version `4.11.2` or later. Verify that your PostCSS configuration and the `content` paths in `tailwind.config.js` are exhaustive and correct, covering all relevant template and script files.
affects: <4.11.2 (for weapp-tailwindcss)
breakingMigrating to Tailwind CSS v4 (which `weapp-tailwindcss` supports) introduces significant upstream breaking changes. This includes a shift to CSS-first configuration, replacing `@tailwind` directives with `@import 'tailwindcss'`, and making `tailwind.config.js` less central. These changes necessitate manual adjustments in addition to any automated tooling.fixThoroughly consult the official Tailwind CSS v4 migration guide, along with `weapp-tailwindcss` documentation. Update your `postcss.config.js` to use `@tailwindcss/postcss` (if not already handled) and modify your main CSS entry point accordingly. Consider running `npx @tailwindcss/upgrade` as an initial step for core Tailwind migration.
affects: >=4.0.0 (for Tailwind CSS)
gotchaComplex type comparisons during Vite's dts (declaration file) build phase could lead to TypeScript errors like `TS2321: Duplicate identifier` or `TS2345: Argument of type '...' is not assignable`. This specific issue was addressed in recent `weapp-tailwindcss` patches.fixUpdate your `weapp-tailwindcss` and associated `@weapp-tailwindcss/*` packages to `4.11.0` or a newer version to incorporate the fixes for these TypeScript build issues.
affects: <4.11.0 (for weapp-tailwindcss)
gotchaIf the `content` array in your `tailwind.config.js` does not correctly specify all file paths where Tailwind classes are utilized (especially for dynamic classes generated in JavaScript/TypeScript strings), classes may not be generated in the final output.fixCarefully review and update your `tailwind.config.js` to ensure the `content` array includes all relevant file types and locations. This includes `.js`, `.ts`, `.jsx`, `.tsx`, `.vue`, `.wxml`, and any other extensions where utility classes might appear. Use comprehensive glob patterns for broader coverage.
affects: >=4.0.0 (for weapp-tailwindcss)
Errors
Common errors & fixes
TS2321: Duplicate identifier '...' / TS2345: Argument of type '...' is not assignable to parameter of type '...'.
These TypeScript errors often arise from type inference complexities during Vite's declaration file (dts) build process when `weapp-tailwindcss` plugins are active, typically due to recursive type comparisons or conflicting definitions.
fixUpgrade `weapp-tailwindcss` and its related `@weapp-tailwindcss/*` monorepo packages to the latest available version (e.g., `4.11.0` or higher), as fixes for these specific TypeScript build issues have been released.
Tailwind CSS utility classes are not applying or rendering correctly in my WeChat Mini Program.
Common culprits include an incorrectly configured PostCSS setup, the `content` array in `tailwind.config.js` not comprehensively covering all source files, issues with `rem2rpx` conversion, missing `weapp-tw patch` configurations, or conflicts with the Mini Program's default base styles.
fixEnsure your `postcss.config.js` correctly integrates `tailwindcss` and the `weapp-tailwindcss` plugin. Verify that `tailwind.config.js`'s `content` array is exhaustive. Consider setting `preflight: false` in `corePlugins` if base styles conflict. Properly configure `rem2rpx` and `viewportWidth` if using arbitrary `rem` values.
The compiled WXSS output still contains `:not(#n)` or `:not(#\#)` placeholder selectors.
This error typically indicates that the `weapp-tailwindcss` plugin has not fully processed or purged certain specific CSS selectors. This issue has been particularly observed in certain Taro or general Weapp build environments and was often resolved in patch updates.
fixUpdate your `weapp-tailwindcss` package to the latest patch version (e.g., `4.11.2` or newer) which includes targeted bug fixes for these persistent placeholder selectors in Mini Program scenarios. Ensure your build tool's configuration is also up-to-date and compatible.
Audit
Dependencies
tailwindcssrequiredCore CSS utility framework, required for the plugin's functionality.
postcssrequiredRequired for CSS processing and plugin integration within the build pipeline.
autoprefixeroptionalCommonly used PostCSS plugin for adding vendor prefixes to CSS, often paired with `tailwindcss`.
@weapp-tailwindcss/sharedrequiredShared utilities and types across the `weapp-tailwindcss` monorepo packages, providing common functionalities.
tailwindcss-patchrequiredA dependency explicitly mentioned in `weapp-tw`'s changelog, indicating its role in handling Tailwind CSS patching.