Skip to main content

uni-app x

Runtime requirements

The current release line requires Node.js ^22.18.0 || >=24.11.0 and HBuilderX >=5.11. The Node.js runtime bundled with older HBuilderX versions may not be able to load the current dependencies.

uni-app x uses HBuilderX and @dcloudio/vite-plugin-uni. It is recommended to use it with the built-in uniAppX preset.

This page is the complete uni-app x entry point. It covers the verified demo, manual installation, CSS-first configuration, multi-platform validation, editor setup, and native App limitations.

Who this is for​

  • Developers who want to use Tailwind CSS in a uni-app x project
  • Teams that need one atomic styling workflow across Web, mini programs, Android, iOS, and HarmonyOS
  • HBuilderX users who run or publish uni-app x projects

Current support range​

The current documentation targets Tailwind CSS 4. The uniAppX() preset delegates Tailwind generation and mini-program/App transformation to weapp-tailwindcss.

Tailwind versionEntry methodScan methodCurrent verification
Tailwind CSS 4@import "tailwindcss" source(none);@source rules in the CSS entryHBuilderX Web, WeChat Mini Program, Android, iOS, and HarmonyOS

The repository's local HBuilderX E2E suite covers uni-app x on the Web, WeChat Mini Program, Android, iOS, and HarmonyOS. Mini Program and App E2E runs depend on local HBuilderX, developer tools, or simulators, so they only run locally.

Capability Boundary

uvue Do not rely on gap, gap-x-*, and gap-y-* on the native app. These layout capabilities are currently not supported.

space-x-*, space-y-* should also not be used in uni-app x. Please use child explicit mt-* / ml-* directly instead, or encapsulate a fixed-structure spacing component.

Quickest start​

Use the verified uni-app x + Tailwind CSS 4 demo and follow its README. Do not use the old icebreaker-template/uni-app-x-hbuilderx as the starting point for a new project.

npm run e2e:hbuilderx:local
npm run e2e:hbuilderx:local:web
npm run e2e:hbuilderx:local:mp
npm run e2e:hbuilderx:local:android
npm run e2e:hbuilderx:local:ios
npm run e2e:hbuilderx:local:harmony

Manual integration​

Create a new uni-app x project in HBuilderX and initialize a package.json in the project root:

npm init -y
npm install -D tailwindcss weapp-tailwindcss

Register plugin​

uniAppX is exported from weapp-tailwindcss/presets; pass cssEntries explicitly.

vite.config.ts
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import { uniAppX } from 'weapp-tailwindcss/presets'

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

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss(
      uniAppX({
        base: projectRoot,
        cssEntries: [resolve(projectRoot, 'main.css')],
        rem2rpx: true,
      }),
    ),
  ],
})

Tailwind CSS generation is handled by weapp-tailwindcss. Do not also register tailwindcss, @tailwindcss/postcss, or @tailwindcss/vite.

The current documentation only maintains Tailwind CSS 4 access instructions.

Web and App Debugging Notes

cssEntries is used to tell weapp-tailwindcss the entry file of Tailwind CSS 4. The entry should still be a real CSS file that HBuilderX / Vite can process. Web/H5, Android and iOS all need to maintain appType: 'uni-app-x'. Do not manually close uniAppX when running on the web side, otherwise any value class name in the .uvue template will not be converted into a safe selector.

rem2rpx, unitsToPx, and unitConversion are top-level options of the uniAppX() preset. Do not put them under cssOptions.

Tailwind CSS entry​

Tailwind CSS 4 uses the CSS-first entry, @source to cover pages, components, and script directories that may produce class names:

main.css
@import "tailwindcss" source(none);
@source "./App.uvue";
@source "./pages/**/*.{uts,uvue}";
@source "./components/**/*.{uts,uvue}";
@source "./stores/**/*.{uts,uvue}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";

Do not put unpackage into the scan range, otherwise the HBuilderX product will in turn interfere with the development build.

Import the entry in App.uvue​

cssEntries tells weapp-tailwindcss where the entry is, but it does not automatically add the CSS to the HBuilderX / Vite module graph. Import it from the global style block:

App.uvue
<style>
@import './main.css';
</style>

If this import is missing, Tailwind can scan for the .uvue candidate, but the web, applet, and app pages will not load the generated styles.

Verify any value class name​

Write a minimal use case on any page:

<view class="p-4">
  <text class="bg-[#102938] text-[#f7fbff] w-[173px]">Tailwind CSS</text>
</view>

Run the project on the Web, WeChat Mini Program, and each target App platform, then confirm the styles are applied. On native App targets, use <text> for text and apply text styles directly to that element.

Reference template​

Development suggestions​

  • Use VS Code for editing and HBuilderX for running and building.
  • Prefer Android for the first native debugging pass; its feedback loop is usually more accessible than iOS or HarmonyOS.
  • Native App text must be placed in <text> and text styles must be applied directly to that element.
  • When a style is limited on App, stabilize Android first and add conditional adaptations for mini programs or Web as needed.

FAQ​

VS Code support for uvue and uts​

Install dcloud-ide.hbuilderx-language-services for language hints, navigation, references, and validation. To enable Tailwind IntelliSense mappings, add this to .vscode/settings.json:

.vscode/settings.json
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}

Running the project​

HBuilderX remains the source of truth for uni-app x running and building. For command-line automation, use the HBuilderX CLI; this repository's local E2E suite launches Web, mini-program, and App targets through hbuilderx launch.