Config

Config

rsbuild.config.mjs

Vant CLI uses Rsbuild to build the documentation site. You can create an Rsbuild configuration file in the same directory as vant.config.mjs. The contents of the file will be automatically read by Vant CLI.

// rsbuild.config.mjs or rsbuild.config.ts
export default {
  plugins: [
    // Configure Rsbuild plugins
  ],
  dev: {
    // Options related to local development
  },
  html: {
    // Options related to HTML generation
  },
  // Other options
};

Please refer to Configure Rsbuild for more information.

vite.config.mjs

Vant Cli uses Vite to build component library code. You can create a Vite configuration file in the same directory as vant.config.mjs. In this file, you can add any Vite configuration.

Please refer to Vite Configuration to learn more.

vant.config.mjs

vant.config.mjs includes bundle and documentation site config. Please create this file and place it in your project root directory. Here is a basic example:

export default {
  // component library name
  name: 'demo-ui',
  // bundle config
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
  // documentation site config
  site: {
    // title
    title: 'Demo UI',
    // logo
    logo: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
    // description
    description: '示例组件库',
    // left nav
    nav: [
      {
        title: 'example',
        items: [
          {
            path: 'home',
            title: 'home',
          },
        ],
      },
      {
        title: 'basic components',
        items: [
          {
            path: 'my-button',
            title: 'MyButton',
          },
        ],
      },
    ],
  },
};

name

Type: string
Default: ''

Component library name. kebab-case recommended.

build.css.base

Type: string
Default: 'style/base.less'

Global style file path. Support absolute path and relative path both.

Note: relative path is calculated based on src.

module.exports = {
  build: {
    css: {
      base: 'style/global.scss',
    },
  },
};

build.css.preprocessor

Type: string
Default: 'less'

CSS preprocessor config, support less and sass. Use less by default.

module.exports = {
  build: {
    css: {
      preprocessor: 'sass',
    },
  },
};

build.css.removeSourceFile

Type: boolean
Default: 'false'

Whether to remove the source style files after build.

module.exports = {
  build: {
    css: {
      removeSourceFile: true,
    },
  },
};

build.site.publicPath

Type: string
Default: /

Equivalent to vite build.outDir.

Generally, documentation site will be deployed to subpath of domain. For example: https://my.github.io/demo-ui/, publicPath should be /demo-ui/.

module.exports = {
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
};

build.srcDir

Type: string
Default: src

module.exports = {
  build: {
    srcDir: 'myDir',
  },
};

build.namedExport

Type: boolean
Default: false

Should export components by Named Export.

When set to false, export default from 'xxx' will be used to export module.

When set to true, export * from 'xxx' will be used to export all modules and type definition.

build.configureVite

Type: (config: InlineConfig): InlineConfig | undefined
Default: undefined

Custom vite config, requires @vant/cli>= 4.0.0.

module.exports = {
  build: {
    configureVite(config) {
      config.server.port = 3000;
      return config;
    },
  },
};

If you need to configure some vite plugins, please create a vite.config.ts file in the same directory of vant.config.mjs, in which you can add any vite configuration (this feature requires @vant/cli 5.1.0).

build.packageManager

Type: 'npm' | 'yarn' | 'pnpm' | 'bun'
Default: yarn

npm package manager.

build.bundleOptions

Type: BundleOptions[]

Specify the format of the bundled output.

The type of BundleOptions:

type BundleOption = {
  // Whether to minify code (Tips: es format output can't be minified by vite)
  minify?: boolean;
  // Formats, can be set to 'es' | 'cjs' | 'umd' | 'iife'
  formats: LibraryFormats[];
  // Dependencies to external (Vue is externaled by default)
  external?: string[];
};

Default value：

const DEFAULT_OPTIONS: BundleOption[] = [
  {
    minify: false,
    formats: ['umd'],
  },
  {
    minify: true,
    formats: ['umd'],
  },
  {
    minify: false,
    formats: ['es', 'cjs'],
    external: allDependencies,
  },
];

site.title

Type: string
Default: ''

Documentation site title.

site.logo

Type: string
Default: ''

Documentation site logo.

site.description

Type: string
Default: ''

Documentation site description.

site.nav

Type: object[]
Default: undefined

Documentation site left nav. Each item of nav means a navigation group.

module.exports = {
  site: {
    nav: [
      {
        // group title
        title: 'Development Guide',
        // nav items
        items: [
          {
            // nav router
            path: 'home',
            // nav title
            title: 'title',
            // should hide phone emulator(false by default)
            hideSimulator: true,
          },
        ],
      },
    ],
  },
};

site.versions

Type: object[]
Default: undefined

Documentation site muti-version config.

module.exports = {
  site: {
    versions: [
      {
        label: 'v1',
        link: '/v1/',
      },
    ],
  },
};

site.baiduAnalytics

Type: object
Default: undefined

Documentation site baidu analysis config. The script of Baidu Statistic will be automatically loaded when build documentation website.

module.exports = {
  site: {
    baiduAnalytics: {
      // 打开百度统计 ->『管理』->『代码获取』
      // find the followed URL: "https://hm.baidu.com/hm.js?xxxxx"
      // add `xxxxx` in the seed
      seed: 'xxxxx',
    },
  },
};

site.hideSimulator

Type: boolean
Default: false

Should hide phone emulator, false by default.

site.simulator.url

Type: string
Default: -

Customize iframe URL.

site.htmlMeta

Type: Record<string, string>
Default: undefined

Customize HTML meta tag, key means name, value means content.

site.headHtml

Type: string
Default: undefined

Insert a custom HTML content in the <head> tag.

site.enableVConsole

Type: boolean
Default: false

Whether to enable vConsole debugging in dev, usually used for mobile debugging.

PostCSS

PostCSS can be configured through the postcss.config.js file in the root directory.

Default Config

PostCSS default config:

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

browserslist

Add browserslist field to package.json file is recommended. It's used by autoprefixer to determine the version of target browser, ensuring compatibility of compiled code.

You can add the following config for mobile:

json

{
  "browserslist": ["Chrome >= 51", "iOS >= 10"]
}