Skip to main content

1. Install and configure Tailwind CSS

Preface​

This tutorial demonstrates how to connect the native WeChat applet JS template to tailwindcss@4 and weapp-tailwindcss. The key points are two things: the source code must enter the Tailwind scanning range, and the mini program target translation must be handed over to weapp-tailwindcss.

The current documentation only maintains Tailwind CSS 4 access instructions.

Running environment​

The current release line requires Node.js ^22.18.0 || >=24.11.0. When the Node version is not satisfactory, it is not recommended to use --ignore-engines hard installation, and subsequent build errors will be more difficult to troubleshoot.

If the project runs uni-app or uni-app x through HBuilderX, you also need to upgrade to HBuilderX >=5.11 to ensure that the IDE's built-in Node can correctly load the current ESM dependencies.

Create project​

Open the WeChat developer tools, click + to create a project, and select:

  1. AppID uses test number
  2. Development mode: Mini program
  3. Backend service: Not using cloud services
  4. Template selection: Second selection Base
  5. Select JS Basic template

Projects created using JS basic templates can still use Typescript

Prepare the entrance to Tailwind CSS first, and then register weapp-tailwindcss and weapp-vite on the next page.

0. Initialize package.json​

If you use a native JS template to create a project, there is usually no package.json in the project directory.

At this time, you need to execute:

npm init -y, create package.json under the project.

1. Install Tailwind CSS​

# Install tailwindcss and weapp-tailwindcss
npm i -D tailwindcss weapp-tailwindcss

weapp-tailwindcss will take over Tailwind CSS generation, do not create Tailwind-specific postcss.config.js. If the project already has PostCSS configuration, only keep the business's own non-Tailwind plug-ins.

2. Configure scan range​

Tailwind CSS 4 writes the scan range in the CSS entry:

app.css
@import "tailwindcss";
@source "./components/**/*.{wxml,js,ts}";
@source "./pages/**/*.{wxml,js,ts}";
@source "./app.{js,ts,json}";
@source not "./node_modules";
@source not "./dist";

Please put the entry of Tailwind 4 in a pure .css file. Do not write directly into the less, scss, sass entries.

3. Introduce Tailwind CSS​

Write the Tailwind entry in the mini program project entry style file, using the @import "tailwindcss"; and @source above.

After adding this piece of code to the entry CSS, the WeChat developer tools may report an error first. This is usually because the weapp-tailwindcss plug-in has not been registered yet.

Next step is to continue installing and registering weapp-tailwindcss.