{"id":14325,"library":"weapp-tw","title":"Tailwind CSS for WeChat Mini Programs","description":"weapp-tailwindcss is a comprehensive solution for integrating Tailwind CSS into WeChat Mini Programs (weapp), including multi-platform frameworks like uni-app, Taro, and native mini-programs. Currently stable at version 4.11.2, the core `weapp-tailwindcss` library receives frequent patch updates, often multiple times a week, reflecting active development and maintenance. Its key differentiators include converting Tailwind utility classes to WXSS/CSS via PostCSS, on-demand class extraction (purging) to optimize bundle size, class-name mapping to handle cross-platform differences, and robust support for responsive design and dark mode within the Mini Program environment. It addresses specific challenges such as rpx unit conversion, dynamic class string parsing in JS/TS, and ensures compatibility across various build tools like Webpack, Vite, and Gulp. The project supports Tailwind CSS v3 and v4, and even v2 JIT mode, making it adaptable to different project needs. The `weapp-tw` package itself is a utility within this ecosystem, currently at 0.0.1, likely serving as an internal helper or template that utilizes the core `weapp-tailwindcss` functionalities.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/sonofmagic/weapp-tailwindcss","tags":["javascript","typescript"],"install":[{"cmd":"npm install weapp-tw","lang":"bash","label":"npm"},{"cmd":"yarn add weapp-tw","lang":"bash","label":"yarn"},{"cmd":"pnpm add weapp-tw","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core CSS utility framework, required for the plugin's functionality.","package":"tailwindcss","optional":false},{"reason":"Required for CSS processing and plugin integration within the build pipeline.","package":"postcss","optional":false},{"reason":"Commonly used PostCSS plugin for adding vendor prefixes to CSS, often paired with `tailwindcss`.","package":"autoprefixer","optional":true},{"reason":"Shared utilities and types across the `weapp-tailwindcss` monorepo packages, providing common functionalities.","package":"@weapp-tailwindcss/shared","optional":false},{"reason":"A dependency explicitly mentioned in `weapp-tw`'s changelog, indicating its role in handling Tailwind CSS patching.","package":"tailwindcss-patch","optional":false}],"imports":[{"note":"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.","wrong":"const UnifiedWebpackPluginV5 = require('weapp-tailwindcss/webpack');","symbol":"UnifiedWebpackPluginV5","correct":"import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss/webpack';"},{"note":"Use this named import for Vite projects. An alias `weappTailwindcss` is also exported from v4.11.0 for unified access.","wrong":"const UnifiedViteWeappTailwindcssPlugin = require('weapp-tailwindcss/vite');","symbol":"UnifiedViteWeappTailwindcssPlugin","correct":"import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite';"},{"note":"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.","wrong":"import weappTailwindcss from 'weapp-tailwindcss/webpack/some-other-path';","symbol":"weappTailwindcss","correct":"import { weappTailwindcss } from 'weapp-tailwindcss/webpack';"},{"note":"Use this named import for Gulp projects. As with other plugins, `weappTailwindcss` is an alias from v4.11.0.","wrong":"const createPlugins = require('weapp-tailwindcss/gulp');","symbol":"createPlugins","correct":"import { createPlugins } from 'weapp-tailwindcss/gulp';"}],"quickstart":{"code":"/* vite.config.ts */\nimport { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport { UnifiedViteWeappTailwindcssPlugin as VitePlugin } from 'weapp-tailwindcss/vite';\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n  plugins: [\n    vue(),\n    VitePlugin({\n      // Enable auto-conversion of `rem` units to `rpx` (WeChat Mini Program units)\n      rem2rpx: true,\n      // Define the base viewport width for `rpx` conversion (e.g., 750 for design drafts)\n      viewportWidth: 750,\n      // The 'css' option ensures that content is processed correctly\n      // for mini-program environments and handles specific CSS transformations.\n      css: true,\n      // Additional options can be configured here. Refer to the official documentation:\n      // https://tw.icebreaker.top/docs/configuration-reference/options\n    }),\n  ],\n  css: {\n    postcss: {\n      plugins: [\n        require('tailwindcss'),\n        require('autoprefixer')\n      ],\n    },\n  },\n});\n\n/* tailwind.config.js */\n/** @type {import('tailwindcss').Config} */\nmodule.exports = {\n  // Crucially, `content` must include all files where Tailwind classes are used.\n  // This includes templates (.vue, .wxml) and script files (.js, .ts) for dynamic classes.\n  content: [\n    './index.html',\n    './src/**/*.{vue,js,ts,jsx,tsx,wxml,wxss}',\n  ],\n  theme: {\n    extend: {},\n  },\n  plugins: [],\n  corePlugins: {\n    // Tailwind's preflight base styles can conflict with mini-program default styles.\n    // Disabling it often provides a cleaner slate for mini-program development.\n    preflight: false,\n    // Ensure essential core plugins for mini-programs are enabled or configured if needed.\n  },\n};\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade 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.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0 (for weapp-tailwindcss)"},{"fix":"Ensure `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.","message":"Developers 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.","severity":"gotcha","affected_versions":"<4.11.2 (for weapp-tailwindcss)"},{"fix":"Thoroughly 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.","message":"Migrating 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.","severity":"breaking","affected_versions":">=4.0.0 (for Tailwind CSS)"},{"fix":"Update 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.","message":"Complex 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.","severity":"gotcha","affected_versions":"<4.11.0 (for weapp-tailwindcss)"},{"fix":"Carefully 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.","message":"If 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.","severity":"gotcha","affected_versions":">=4.0.0 (for weapp-tailwindcss)"}],"env_vars":null,"search_vec":"'0.0.1':170 '4.11.2':42 'across':127 'activ':59 'adapt':151 'address':110 'app':31 'build':129 'bundl':83 'challeng':112 'class':70,78,86,119 'class-nam':85 'compat':126 'comprehens':12 'convers':117 'convert':67 'core':44,182 'cross':92 'cross-platform':91 'css':2,17,140 'current':38,168 'dark':102 'demand':77 'design':100 'develop':60 'differ':94,153 'differenti':65 'dynam':118 'ecosystem':167 'ensur':125 'environ':108 'even':145 'extract':79 'framework':27 'frequent':50 'function':186 'gulp':135 'handl':90 'helper':176 'includ':23,66 'integr':15 'intern':175 'javascript':187 'jit':147 'js/ts':123 'key':64 'librari':48 'like':28,131,171 'mainten':62 'make':149 'map':88 'mini':5,20,36,106 'mini-program':35 'mode':103,148 'multi':25 'multi-platform':24 'multipl':54 'name':87 'nativ':34 'need':155 'often':53 'on-demand':75 'optim':82 'packag':160 'pars':121 'patch':51 'platform':26,93 'postcss':74 'program':6,21,37,107 'project':137,154 'purg':80 'receiv':49 'reflect':58 'respons':99 'robust':96 'rpx':115 'serv':172 'size':84 'solut':13 'specif':111 'stabl':39 'string':120 'support':97,138 'tailwind':1,16,68,139 'tailwindcss':9,47,185 'taro':32 'templat':178 'time':55 'tool':130 'tw':159 'typescript':188 'uni':30 'uni-app':29 'unit':116 'updat':52 'util':69,164,180 'v2':146 'v3':141 'v4':143 'various':128 'version':41 'via':73 'vite':133 'weapp':8,22,46,158,184 'weapp-tailwindcss':7,45,183 'weapp-tw':157 'webpack':132 'wechat':4,19 'week':57 'within':104,165 'wxss/css':72","created_at":"2026-04-20T01:59:07.560278+00:00","updated_at":"2026-04-20T01:59:07.560278+00:00","problems":[{"fix":"Upgrade `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.","cause":"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.","error":"TS2321: Duplicate identifier '...' / TS2345: Argument of type '...' is not assignable to parameter of type '...'."},{"fix":"Ensure 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.","cause":"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.","error":"Tailwind CSS utility classes are not applying or rendering correctly in my WeChat Mini Program."},{"fix":"Update 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.","cause":"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.","error":"The compiled WXSS output still contains `:not(#n)` or `:not(#\\#)` placeholder selectors."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://weapp-tailwindcss.com","github":"https://github.com/sonofmagic/weapp-tailwindcss","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/weapp-tw","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}