Skip to main content

2. Install this plugin and run it

Install plugin​

In the project directory, execute:

npm i -D weapp-tailwindcss weapp-vite

This way weapp-tailwindcss and weapp-vite will be installed on your local machine

Execute initialization command​

Run from command line

npx weapp-vite init

This command will initialize weapp-vite for the existing native applet project.

After execution, you will find that there are many file changes. CLI mainly does 3 things:

  • Create the vite.config.ts file, which is the configuration file for weapp-vite and vite
  • Modify package.json, add dev and build development and build scripts, as well as build npm and open WeChat developer tools
  • Modify the content of project.config.json to adapt to the built product
  • Added dts and tsconfig.json adapted to vite

Install all dependency packages​

After executing the weapp-vite init initialization command, we need to execute the installation command in the project:

npm i

Register plugin​

Register the plugin in your vite.config.ts:

vite.config.ts
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    WeappTailwindcss({
      cssEntries: [
        resolve(projectRoot, 'app.css'),
      ],
      cssOptions: {
        rem2rpx: true,
      },
    }),
  ],
})

The scanning range of Tailwind CSS 4 is written in @source of the CSS entry. There is no need to register the Tailwind official build plug-in in build mode, and there is no need to execute weapp-tw patch. The current documentation only maintains Tailwind CSS 4 access instructions.

Tailwind CSS 4 projects should configure cssEntries explicitly. cssEntries is only responsible for allowing WeappTailwindcss to stably read the entry CSS. The entry CSS still has to be actually introduced through the project entrance; if there are multiple Tailwind CSS entries, they are all written into the array:

vite.config.ts
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    WeappTailwindcss({
      cssOptions: {
        rem2rpx: true,
      },
      cssEntries: [
        resolve(projectRoot, 'app.css'),
      ],
    }),
  ],
})

Start running​

Use npm run dev to enter development mode. This mode comes with hot updates and is mainly used for development.

Build using npm run build

Whether it is npm run dev or npm run build, their build products are in the dist directory under the project directory

Use WeChat developer tools to directly import the project directory and then preview the effect!

Be careful not to import the dist directory, but the root directory of your project! It is usually the parent directory of dist, don’t make a mistake!

Configured template​

If the configuration is unsuccessful, you can use the following template to compare the configuration files:

weapp-vite-tailwindcss-template

Or execute the command directly:

npx weapp-vite create my-app

This command will create an my-app + weapp-vite integration template named weapp-tailwindcss in the current directory.

Isolation of native component styles​

tip

I found that many users, when using native development, often ask why the tailwindcss style does not take effect on custom components.

There may be several reasons for this:

  1. The code file is not within the scanning range of @source
  2. Component style isolation is enabled by default for native mini program components. By default, the style of custom components is only affected by the custom component wxss. The tool classes generated by tailwindcss are all in the global style file app.wxss. If it does not belong to the component, it will naturally not take effect.

At this time, you can set the following line json in the styleIsolation file configuration of your component to enable style sharing:

custom-component.json
{
  "styleIsolation": "apply-shared"
}

apply-shared means that the page wxss style will affect the custom component, but the style specified in the custom component wxss will not affect the page;

To allow the component to apply the styles in app.wxss.

For more documents, please see: WeChat Mini Program Related Development Documents

Want to know more weapp-vite​

For more scenarios and configurations, please check weapp-vite documentation website