Quick Start

This section introduces how to install, configure, and use Wot Design Uni in your uni-app project.

Before Using

Before using, please make sure you have learned Vue's official Quick Start and uni-app's Learning Path.

Installation

About Installation

Wot Design Uni provides two installation methods: uni_modules and npm. Choose according to your needs.

• Using uni_modules installation requires no additional configuration, it's plug-and-play, but updating the component library requires handling code differences (generally just overwriting is fine).
• Using npm installation requires additional configuration, but updating the component library doesn't require handling code differences.

npm Installation

npm

npm i wot-design-uni

yarn

yarn add wot-design-uni

pnpm

pnpm add wot-design-uni

uni_modules Installation

Wot Design Uni supports the uni_modules specification and is available in the uni-app plugin market.

In the uni-app plugin market, choose to import using HBuildX, or manually create a uni_modules folder in the src directory and extract Wot Design Uni into uni_modules, with the following structure:

- uni_modules
- - - wot-design-uni

Download link: wot-design-uni

Sass

Wot Design Uni depends on sass, so before using it, you need to confirm whether sass is already installed in your project. If not, you can install it using the following command:

npm

npm i sass -D

yarn

yarn add sass -D

pnpm

pnpm add sass -D

Reminder

Dart Sass 3.0.0 has deprecated a batch of APIs, and the component library hasn't been compatible yet, so please ensure your sass version is 1.78.0 or earlier. See Common Problems.

Configuration

Import Components

Reminder

When using uni_modules installation, Wot Design Uni components naturally support the easycom specification, requiring no additional configuration for automatic component import. When using npm installation, you need to follow this step. Choose one of the following two solutions.

Configure easycom for Automatic Component ImportSolution 1

Traditional Vue components require three steps: installation, import, and registration before they can be used. easycom simplifies this to one step. As long as the component path follows the specification (see easycom), you can use it directly in the page without importing and registering.

Reminder

• For compilation speed, uni-app won't trigger recompilation when directly modifying easycom in pages.json. You need to modify page content to trigger it.
• Please ensure you only have one easycom field in your pages.json, otherwise please merge multiple import rules yourself.

// pages.json
{
 "easycom": {
  "autoscan": true,
  "custom": {
    "^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"
  }
 },
 
 // This is the existing content
 "pages": [
  // ......
 ]
}

Configure Automatic Component Import Based on viteSolution 2

If you're not familiar with easycom, you can also achieve automatic component import through @uni-helper/vite-plugin-uni-components.

Reminder

• Recommended to use @uni-helper/vite-plugin-uni-components@0.0.9 and above, as it includes the built-in resolver for wot-design-uni starting from version 0.0.9.
• If you see many Sourcemap for points to missing source files​ in the console when using this solution, try upgrading Vite to version 4.5.x or above.

npm

npm i @uni-helper/vite-plugin-uni-components -D

yarn

yarn add @uni-helper/vite-plugin-uni-components -D

pnpm

pnpm add @uni-helper/vite-plugin-uni-components -D

// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";

import Components from '@uni-helper/vite-plugin-uni-components'
import { WotResolver } from '@uni-helper/vite-plugin-uni-components/resolvers'


export default defineConfig({
  plugins: [
    // make sure put it before `Uni()`
    Components({
    resolvers: [WotResolver()]
  }), uni()],
});

If you use pnpm, please create a .npmrc file in the root directory, see Issue.

// .npmrc
public-hoist-pattern[]=@vue*
// or
// shamefully-hoist = true

Volar Support

If you use Volar, please specify global component types through compilerOptions.type in tsconfig.json.

TIP

For cli projects using uni_modules installation, no configuration is needed as Volar support is automatically enabled. HbuildX projects don't support this configuration, so this step is only needed when using npm installation in cli projects.

// tsconfig.json
{
  "compilerOptions": {
    "types": ["wot-design-uni/global"]
  }
}

Usage

After installing and configuring Wot Design Uni, it supports automatic component import, so you can use it directly in SFC without importing in the page or declaring in components. It's worth noting that the uni-app platform doesn't support global component mounting, so components like Message, Toast, etc., still need to be explicitly used in SFC, for example:

<wd-toast></wd-toast>

Scaffolding

We provide a quick start project wot-demo, which integrates Wot Design Uni and many excellent plugins, you can clone this project directly.

You can also use create-uni to quickly create a starter project through the following command:

pnpm create uni@latest -t wot-demo <your project name>