Quick Start

This section introduces how to install, configure, and use Wot UI in a uni-app project.

Before Use

Before using, please ensure you have learned the official Vue Quick Start and the learning path provided by uni-app Learning Path.

Installation

About Installation

Wot UI provides two installation methods: uni_modules and npm, choose as needed.

• Using uni_modules installation requires no additional configuration, plug and play, but each update of the component library requires handling code differences (usually just overwriting is fine).
• Using npm installation requires additional configuration, and no code differences need to be handled when updating the component library.

npm Installation

npm

npm i @wot-ui/ui

yarn

yarn add @wot-ui/ui

pnpm

pnpm add @wot-ui/ui

uni_modules Installation

Wot UI supports the uni_modules specification and is available on the uni-app plugin market.

In uni-app plugin market, choose to import using HBuildX, or manually create a uni_modules folder under the src directory and extract Wot UI into uni_modules, with the structure as follows:

- uni_modules
- - - wot-ui

Download link: wot-ui

Sass

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

npm

npm i sass -D

yarn

yarn add sass -D

pnpm

pnpm add sass -D

Configuration

Import Components

Reminder

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

Vite-based Auto-import Configuration Option 1

If you are 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 version 0.0.9 and above has built-in resolver for wot-ui.
• If using this solution, the console prints many Sourcemap for points to missing source files​, you can try upgrading Vite version to 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

Configure easycom Auto-import Option 2

Traditional vue components require three steps: install, reference, and register before they can be used. easycom streamlines this to one step. As long as the component path conforms to the specification (see easycom), you can use components directly in pages without referencing or registering.

Reminder

• uni-app considers compilation speed, directly modifying easycom in pages.json will not trigger recompilation, you need to modify page content to trigger.
• Please ensure there is only one easycom field in your pages.json, otherwise please merge multiple import rules yourself.

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

Volar Support

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

TIP

CLI projects using uni_modules installation do not need configuration, support for Volar is automatically effective. HbuildX projects do not support this configuration, so this step is only required when using npm installation in cli projects.

// tsconfig.json
{
  "compilerOptions": {
    "types": ["@wot-ui/ui/global"]
  }
}

Usage

After Wot UI installation and configuration are complete, it supports automatic component import, so you can use it directly in SFC without importing in the page or declaring in components, and it can be used on any page. It is worth noting that the uni-app platform does not support global mounting of components, so Message, Toast and other components still need to be explicitly used in SFC, for example:

<wd-toast></wd-toast>

Scaffolding

We provide a quick start project wot-starter, which integrates Wot UI 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-starter <your-project-name>

For more scaffolding and templates, please see Scaffolding and Templates.