mini program tailwind
1.5.6
Let your mini program use the original Tailwind/Windi CSS
From Digital Creative, a digital product research, design and development company located in Shanghai.
Get to know us
- What we do
- About us
- Contact us
It is recommended to read the independent document for a better reading experience
Since the applet itself does not support some special escape characters (such as [ ! . etc.) contained in the selector names generated by Tailwind/Windi CSS, this prevents you from using some features that should be used when developing the applet. The flexible syntax and Arbitrary values/Value auto-infer function used in web applications, such as w-[30px] translate-x-1/2 !bg-[#ff0000] , etc. This undoubtedly has a considerable impact on our development efficiency and mental burden.
In order to break through this limitation, we developed this plug-in to help you maintain a highly consistent development experience with developing web applications when using Tailwind/Windi CSS to develop small programs. You no longer need to pay attention to which strings are not used. Instead of supporting the problem of having to change the writing method, continue to write your mini program style according to the official syntax of Tailwind/Windi CSS , and the compatibility work behind it is silently handled by this plug-in.
In addition, this plug-in also integrates the function of automatic conversion of rpx values. This function can automatically convert rem and px unit values we wrote in the Tailwind/Windi CSS configuration file and the source code into rpx unit values in the final generated style file. This allows developers to reuse the same theme configuration used in web projects and allows small programs to continue to use the features brought by responsive pixel.
Learn more about how this plugin works
Let your mini program use the original Tailwind/Windi CSS
Choose one of the mini program types that suits you to install the plug-in
MPX, an enhanced cross-terminal applet framework with excellent development experience and in-depth performance optimization.
Since the MPX framework is a typical enhanced mini program development framework using Webpack as the construction tool, this installation demonstration uses the MPX project as a typical case to demonstrate how to install plug-ins for most Webpack-like mini program projects. The following installation steps are widely applicable in Webpack projects . For most Webpack mini-program projects, you only need to refer to the same steps for installation.
npm i windicss-webpack-plugin -DRefer to Windi CSS official documentation for more details
Windi CSS Webpack integration
npm i @dcasia/mini-program-tailwind-webpack-plugin -DUsing Webpack plugin
//webpack.base.conf.js
const WindiCSSWebpackPlugin = require ( "windicss-webpack-plugin" ) ;
const MiniProgramTailwindWebpackPlugin = require ( "@dcasia/mini-program-tailwind-webpack-plugin" )
module . exports = {
plugins : [
new WindiCSSWebpackPlugin ( ) ,
new MiniProgramTailwindWebpackPlugin ( {
// options
} )
]
} Create a new windi.config.js configuration file in the project root directory
//windi.config.js
export default {
preflight : false ,
prefixer : false ,
extract : {
// 将 .mpx 文件纳入范围（其余 Webpack 类小程序根据项目本身的文件后缀酌情设置）
include : [ 'src/**/*.{css,html,mpx}' ] ,
// 忽略部分文件夹
exclude : [ 'node_modules' , '.git' , 'dist' ]
} ,
corePlugins : {
// 禁用掉在小程序环境中不可能用到的 plugins
container : false
}
}The Tailwind CSS configuration file also applies here
Refer to Windi CSS official documentation for more details
Windi CSS profile compatibility rules
// app.mpx
< style src =" windi.css " > </ style >For other Webpack applets of non-MPX projects, you can refer to a similar method to introduce
windi.cssin the entry file, such as:// main.js import 'windi.css'Refer to Windi CSS official documentation for more details
Introduce Windi CSS style files
Start enjoying the efficient development experience brought by Windi CSS in small program projects?
| name | type | default | describe |
|---|---|---|---|
| enableRpx | Boolean | true | Whether to enable automatic conversion to rpx unit value |
| designWidth | Number | 350 | The pixel width value of the design draft. This size will affect the calculation ratio during the rpx conversion process. |
| utilitiesSettings.spaceBetweenItems | Array<string> | [] | The name of the child component in the container that uses Space Between utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.divideItems | Array<string> | [] | The name of the child component in the container that uses the Divide width utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
Integration Case: MPX Project
Taro, a multi-terminal unified development solution
This plug-in contains the Taro plug-in, which can be easily adapted to the Taro applet through "one-click installation".
The Taro plug-in is compatible with the following front-end frameworks
- React
- Vue 2
- Vue 3
- Preact
It is also compatible with the use of Tailwind/Windi CSS in mixed native component development.
npm i @dcasia/mini-program-tailwind-webpack-plugin -D
// config/index.js
const config = {
plugins : [
[ '@dcasia/mini-program-tailwind-webpack-plugin/dist/taro' , {
// ...options
} ]
]
} Create a new windi.config.js configuration file in the project root directory
// windi.config.js
export default {
prefixer : false ,
extract : {
// 忽略部分文件夹
exclude : [ 'node_modules' , '.git' , 'dist' ]
} ,
corePlugins : {
// 禁用掉在小程序环境中不可能用到的 plugins
container : false
}
}The Tailwind CSS configuration file also applies here
Refer to Windi CSS official documentation for more details
Windi CSS profile compatibility rules
// app.js
import 'windi.css' ; Start enjoying the efficient development experience brought by Windi CSS in Taro?
| name | type | default | describe |
|---|---|---|---|
| enableWindiCSS | Boolean | true | Whether to enable Windi CSS that comes with the plug-in |
| windiCSSConfigFile | String | Read the configuration file in the project root directory | Manually set the path to the Windi CSS configuration file if necessary |
| enableRpx | Boolean | false | Whether to enable automatic conversion to rpx unit value (since Taro comes with this function, it is turned off by default) |
| designWidth | Number | 375 | The pixel width value of the design draft. This size will affect the calculation ratio during the rpx conversion process. |
| utilitiesSettings.spaceBetweenItems | Array<string> | [] | The name of the child component in the container that uses Space Between utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.divideItems | Array<string> | [] | The name of the child component in the container that uses the Divide width utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.customComponents | Array<string> | [] | Developers who use Uno CSS as the Atomic CSS engine need to configure it according to the project situation. By default, all component names that come with mini programs are included, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| enableDebugLog | Boolean | false | Whether to enable printing of the internal running log of this plug-in |
- Integration case: Taro - React project
- Integration case: Taro - Vue 2 project
- Integration case: Taro - Vue 3 project
uni-app, develop once and cover multiple terminals.
This article contains two installation demonstrations of Vue 3 and Vue 2 of uni-app.
Please refer to the next mini program type: regular Vite mini program (taking uni-app as an example)
npm i windicss-webpack-plugin -DRefer to Windi CSS official documentation for more details
Windi CSS Webpack integration
npm i @dcasia/mini-program-tailwind-webpack-plugin -D Create a new vue.config.js configuration file in the project root directory and use the Webpack plug-in
// vue.config.js
const WindiCSSWebpackPlugin = require ( "windicss-webpack-plugin" ) ;
const MiniProgramTailwindWebpackPlugin = require ( "@dcasia/mini-program-tailwind-webpack-plugin" )
module . exports = {
configureWebpack : {
plugins : [
new WindiCSSWebpackPlugin ( ) ,
new MiniProgramTailwindWebpackPlugin ( {
// options
} )
]
}
} Create a new windi.config.js configuration file in the project root directory
//windi.config.js
export default {
preflight : false ,
prefixer : false ,
extract : {
// 忽略部分文件夹
exclude : [ 'node_modules' , '.git' , 'dist' ]
} ,
corePlugins : {
// 禁用掉在小程序环境中不可能用到的 plugins
container : false
}
}The Tailwind CSS configuration file also applies here
Refer to Windi CSS official documentation for more details
Windi CSS profile compatibility rules
// main.js
import 'windi.css' Start enjoying the efficient development experience brought by Windi CSS in small program projects?
| name | type | default | describe |
|---|---|---|---|
| enableRpx | Boolean | true | Whether to enable automatic conversion to rpx unit value |
| designWidth | Number | 350 | The pixel width value of the design draft. This size will affect the calculation ratio during the rpx conversion process. |
| utilitiesSettings.spaceBetweenItems | Array<string> | [] | The name of the child component in the container that uses Space Between utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.divideItems | Array<string> | [] | The name of the child component in the container that uses the Divide width utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.customComponents | Array<string> | [] | Developers who use Uno CSS as the Atomic CSS engine need to configure it according to the project situation. By default, all component names that come with mini programs are included, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
Integration case: uni-app Vue 2 project
uni-app, develop once and cover multiple terminals.
Since the project is built based on Vite when using Vue 3 for mini program development in uni-app, this installation demonstration uses the uni-app Vue 3 project as a typical case to demonstrate how to plug-in most Vite-like mini program projects. Install. The following installation steps are widely applicable to Vite projects . For most Vite-like applet projects, you only need to refer to the same steps for installation.
npm i vite-plugin-windicss windicss -DRefer to Windi CSS official documentation for more details
Windi CSS Vite integration
npm i @dcasia/mini-program-tailwind-webpack-plugin -D Use plugins in vite.config.js configuration file
// vite.config.js
import WindiCSS from 'vite-plugin-windicss' ;
import MiniProgramTailwind from '@dcasia/mini-program-tailwind-webpack-plugin/rollup' ;
export default {
plugins : [
WindiCSS ( ) ,
MiniProgramTailwind ( )
]
} Create a new windi.config.js configuration file in the project root directory
//windi.config.js
export default {
preflight : false ,
prefixer : false ,
extract : {
// 忽略部分文件夹
exclude : [ 'node_modules' , '.git' , 'dist' ]
} ,
corePlugins : {
// 禁用掉在小程序环境中不可能用到的 plugins
container : false
}
}The Tailwind CSS configuration file also applies here
Refer to Windi CSS official documentation for more details
Windi CSS profile compatibility rules
// main.js
import 'virtual:windi.css' Start enjoying the efficient development experience brought by Windi CSS in mini program projects?
| name | type | default | describe |
|---|---|---|---|
| enableRpx | Boolean | true | Whether to enable automatic conversion to rpx unit value |
| designWidth | Number | 350 | The pixel width value of the design draft. This size will affect the calculation ratio during the rpx conversion process. |
| utilitiesSettings.spaceBetweenItems | Array<string> | [] | The name of the child component in the container that uses Space Between utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.divideItems | Array<string> | [] | The name of the child component in the container that uses the Divide width utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.customComponents | Array<string> | [] | Developers who use Uno CSS as the Atomic CSS engine need to configure it according to the project situation. By default, all component names that come with mini programs are included, so in most cases developers do not need to configure this item. If you need to add new ones, you can add new component names in the array. |
Integration case: uni-app Vue 3 project
No matter what bundler or workflow tool your project is developed on, as long as there is a programmable file monitoring and processing service, you can customize it. But one thing that needs to be made clear here is that if we want to integrate the functions of this plug-in based on the native development mode, we must start a set of programmable file monitoring and processing services as the basis for the plug-in's operation . This service is usually provided by The configured third-party tools such as Webpack and Gulp are completed.
Developers using Tailwind/Windi CSS CLI please read
If you develop small program UI through the official CLI of Tailwind/Windi CSS, unfortunately, because the CLI does not support the plug-in mechanism and cannot support the modification of template files, we cannot customize it on this basis. Integrate this plugin.
We have decoupled and packaged the core functions of this plug-in into the universal-handler.js file. If you want to integrate the core functions of this plug-in in a custom build tool, you can introduce universal-handler into the workflow logic:
const { handleTemplate , handleStyle } = require ( '@dcasia/mini-program-tailwind-webpack-plugin/universal-handler' )Process template:
const rawContent = '<view class="w-10 h-[0.5px] text-[#ffffff]"></view>'
const handledTemplate = handleTemplate ( rawContent )Processing style:
const rawContent = '.h-\[0\.5px\] {height: 0.5px;}'
const handledStyle = handleStyle ( rawContent , options )You can then return the processed strings to the original workflow to generate the final file.
Learn more about the practical details of custom implementation
Mini program integrates custom implementation of Windi CSS
| name | type | default | describe |
|---|---|---|---|
| enableRpx | Boolean | false | Whether to enable automatic conversion to rpx unit value |
| designWidth | Number | 350 | The pixel width value of the design draft. This size will affect the calculation ratio during the rpx conversion process. |
| utilitiesSettings.spaceBetweenItems | Array<string> | [] | The name of the child component in the container that uses Space Between utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.divideItems | Array<string> | [] | The name of the child component in the container that uses the Divide width utilities. Four common components, view, button, text, and image, are included by default, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
| utilitiesSettings.customComponents | Array<string> | [] | Developers who use Uno CSS as the Atomic CSS engine need to configure it according to the project situation. By default, all component names that come with mini programs are included, so in most cases developers do not need to configure this item. If you need to add new components, you can add new component names in the array. |
Integration case: Custom implementation based on Gulp
The demonstration steps take integrating Windi CSS as an example (Windi CSS has a better experience and is compatible with Tailwind CSS)
Learn more about Windi CSS
Wind CSS
In order to enable component styles to be affected by Tailwind/Windi's CSS products in the mini program, we need to set the style scope styleIsolation in the JSON configuration file of each component. Otherwise, even if Tailwind/Windi CSS works normally, it cannot be used. Develop component UI.
Taro applet is not affected by this restriction
{
"component" : true ,
"styleIsolation" : " apply-shared "
}Related issues
Issue #1
Since the current hot reload function of WeChat developer tools cannot detect changes in the content of the wxss file imported by @import in the style file, when the hot reload function is enabled for development, the simulator will not follow your changes to Tailwind/Windi CSS. Update the UI based on changes. At present, WeChat officials are aware of the existence of this bug. Before the bug is fixed, we recommend that you turn off hot reloading during development and use traditional automatic page refresh to preview each UI update. Currently, this problem has been fixed in WeChat Developer Tools 1.06.2205231 RC.
Related issues
Issue #3
For the declaration of external style classes externalClasses in native applet, the plug-in only supports the declaration of externalClasses name as 'class' , and does not support other names.
Component ( {
externalClasses : [ 'class' ]
} )Related issues
Issue #44
| grammar | Do not use this plug-in | Use this plug-in |
|---|---|---|
Regular : h-10 text-white | ✅ | ✅ |
Arbitrary values/Value infer : t-[25px] bg-[#ffffff] | ✅ | |
Fraction : translate-x-1/2 w-8.5 | ✅ | |
Important : !p-1 | ✅ | |
RGB value infer : text-[rgb(25,25,25)] | ✅ | |
Space between : space-y-2 space-y-reverse | ✅ | |
Divide width : divide-x-2 divide-y-reverse | ✅ | |
Variants : dark:bg-gray-800 | ✅ | |
Variants groups : hover:(bg-gray-400 font-medium) | ✅ | |
Responsive : md:p-2 | ✅ | |
Universal selector : * | ✅ | |
rpx value transformed from rem and px value | ✅ |
>= 4.0.0>= 3.4.0>= 2.7.5
