Skip to main content

packages-runtime overview

packages-runtime is a set of runtime capabilities of weapp-tailwindcss, which is used to extend compile-time class name rules to the applet to solve problems such as "dynamic class name conflicts", "illegal character escaping" and "multi-terminal consistency". They provide escape/unescape and factory capabilities based on @weapp-tailwindcss/runtime, and the current documentation is for Tailwind CSS 4.

The current documentation only maintains Tailwind CSS 4 access instructions.

Runtime matrix​

Package nameTailwind versionApplicable scenariosDescription
@weapp-tailwindcss/mergev4Mini program / multi-terminal projecttailwind-merge@3 compatible implementation, default entry
@weapp-tailwindcss/cvav4Component variant factoryclass-variance-authority runtime packaging
@weapp-tailwindcss/variantsv4Component variants + slotstailwind-variants runtime packaging

@weapp-tailwindcss/runtime is a base package, which is usually automatically installed as an indirect dependency and does not need to be introduced separately.

Version selection​

  • Tailwind v4: Prioritize @weapp-tailwindcss/merge + @weapp-tailwindcss/variants; add @weapp-tailwindcss/cva when variant factory is required.

pnpm + uni-app Notes​

uni-app's Vite turns on preserveSymlinks by default and will resolve dependencies from the symlink path in the package; pnpm's isolation layout will not put transitive dependencies under this path, so "XXX not found" will appear repeatedly (for example, @vueuse/shared is a transitive dependency of @vueuse/core). npm/yarn is not affected.

There are two ways to solve it "completely":

  1. Change node-linker to hoisted (the most thorough, close to npm/yarn classic)

After setting it in the root directory .npmrc (or the workspace configuration of pnpm-workspace.yaml) and then re-pnpm install, the dependencies will be flatter, and transitive dependencies can also be resolved under preserveSymlinks.

node-linker=hoisted
  1. Maintain isolated and continue to supplement hoist/direct dependencies (not complete, high maintenance costs)

For example, append to .npmrc:

public-hoist-pattern[]=@weapp-tailwindcss/*
public-hoist-pattern[]=tailwind-merge
public-hoist-pattern[]=@weapp-core/*

Later, when new missing dependencies (such as @vueuse/shared) are encountered, they need to be filled in as direct dependencies.

Multi-terminal mental model (small program + Web)​

The applet needs escape/unescape to keep the class name legal; the web side wants to keep the original class name. Each package's create(...) factory allows you to generate isolated instances for different ends:

import { create } from '@weapp-tailwindcss/merge'

// For cross-platform frameworks, please determine whether it is built with H5. It can usually be read from environment variables.
const isH5 = false
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})

This mode is also applicable to variant tools such as cva, tv, and

Chapter quick overview​