Registry / web-framework / weapp-tw

weapp-tw

JSON →
library0.0.1jsnpmunverified

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.

npm install weapp-tw
INSTALL
IMPORT
SIG · WEAPP-TW
W
weapp-tw
web-frameworkjavascriptv0.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Upgrade
Version history
0.0.1latest on npm
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.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources