From 2c17abf7f5c8be9986edb3ef104f53f94f37cbfc Mon Sep 17 00:00:00 2001 From: wChenonly <37658262+wChenonly@users.noreply.github.com> Date: Sat, 2 Sep 2023 16:48:16 +0800 Subject: [PATCH] feat(auto-import-resolver): add auto-import-resolver package (#12227) --- packages/auto-import-resolver/LICENSE | 10 ++ packages/auto-import-resolver/README.md | 133 ++++++++++++++++++ packages/auto-import-resolver/README.zh-CN.md | 129 +++++++++++++++++ packages/auto-import-resolver/build.js | 1 + packages/auto-import-resolver/package.json | 44 ++++++ packages/auto-import-resolver/src/index.ts | 58 ++++++++ packages/auto-import-resolver/tsconfig.json | 9 ++ packages/auto-import-resolver/vant.config.mjs | 5 + .../vant/docs/markdown/quickstart.en-US.md | 61 +++++--- .../vant/docs/markdown/quickstart.zh-CN.md | 27 ++-- pnpm-lock.yaml | 23 +++ 11 files changed, 467 insertions(+), 33 deletions(-) create mode 100644 packages/auto-import-resolver/LICENSE create mode 100644 packages/auto-import-resolver/README.md create mode 100644 packages/auto-import-resolver/README.zh-CN.md create mode 100644 packages/auto-import-resolver/build.js create mode 100644 packages/auto-import-resolver/package.json create mode 100644 packages/auto-import-resolver/src/index.ts create mode 100644 packages/auto-import-resolver/tsconfig.json create mode 100644 packages/auto-import-resolver/vant.config.mjs diff --git a/packages/auto-import-resolver/LICENSE b/packages/auto-import-resolver/LICENSE new file mode 100644 index 000000000..26ef2dcc9 --- /dev/null +++ b/packages/auto-import-resolver/LICENSE @@ -0,0 +1,10 @@ +MIT License + +Copyright (c) Youzan +Copyright (c) Chen Jiahan and other contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/packages/auto-import-resolver/README.md b/packages/auto-import-resolver/README.md new file mode 100644 index 000000000..e1e3052df --- /dev/null +++ b/packages/auto-import-resolver/README.md @@ -0,0 +1,133 @@ +# Vant Auto Import Resolver + +@vant/auto-import-resolver For Vant on-demand introduction, parser based on `unplugin-vue-components` + +🇨🇳 查看中文版介绍 + +--- + +### Features + +- Supports `Vite`, `Webpack`, `Rspack`, `Vue CLI`, `Rollup`, `esbuild` and more, powered by unplugin-vue-components + +- Support css style `VantResolver()` default + +- Support less style `VantResolver({ importStyle: false | 'less' })` + + > Tip: Vant 4.0 the less file has been removed from the above npm package + +- Support ssr `VantResolver({ ssr: true })` + +### Install Manually + +```shell +# via npm +npm i @vant/auto-import-resolver unplugin-vue-components -D + +# via yarn +yarn add @vant/auto-import-resolver unplugin-vue-components -D + +# via pnpm +pnpm add @vant/auto-import-resolver unplugin-vue-components -D + +# via Bun +bun add @vant/auto-import-resolver unplugin-vue-components -D +``` + +
+Vite
+ +```ts +// vite.config.ts +import Components from 'unplugin-vue-components/vite'; +import { VantResolver } from '@vant/auto-import-resolver'; + +export default defineConfig({ + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}); +``` + +
+ +
+Rollup
+ +```ts +// rollup.config.js +import Components from 'unplugin-vue-components/rollup'; +import { VantResolver } from '@vant/auto-import-resolver'; + +export default { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}; +``` + +
+ +
+Webpack
+ +```ts +// webpack.config.js +import Components from 'unplugin-vue-components/webpack'; +import { VantResolver } from '@vant/auto-import-resolver'; + +module.exports = { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}; +``` + +
+ +
+Vue CLI
+ +```ts +// vue.config.js +import Components from 'unplugin-vue-components/webpack'; +import { VantResolver } from '@vant/auto-import-resolver'; + +module.exports = { + configureWebpack: { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], + }, +}; +``` + +
+ +
+esbuild
+ +```ts +// esbuild.config.js +import { build } from 'esbuild'; +import Components from 'unplugin-vue-components/esbuild'; +import { VantResolver } from '@vant/auto-import-resolver'; + +build({ + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}); +``` + +
diff --git a/packages/auto-import-resolver/README.zh-CN.md b/packages/auto-import-resolver/README.zh-CN.md new file mode 100644 index 000000000..a6696bc93 --- /dev/null +++ b/packages/auto-import-resolver/README.zh-CN.md @@ -0,0 +1,129 @@ +# Vant Auto Import Resolver + +@vant/auto-import-resolver 用于 Vant 按需引入，基于 unplugin-vue-components 的解析器 + +### 特性 + +- 支持 `Vite`, `Webpack`, `Rspack`, `Vue CLI`, `Rollup`, `esbuild` 等, 基于 unplugin-vue-components + +- 支持自动引入 css 样式 `VantResolver()` 默认 + +- 支持自动引入 less 样式 `VantResolver({ importStyle: false | 'less' })` + + > 提示：Vant 4.0 以上 npm 包内移除了 less 文件 + +- 支持 ssr `VantResolver({ ssr: true })` + +### 安装 + +```shell +# via npm +npm i @vant/auto-import-resolver unplugin-vue-components -D + +# via yarn +yarn add @vant/auto-import-resolver unplugin-vue-components -D + +# via pnpm +pnpm add @vant/auto-import-resolver unplugin-vue-components -D + +# via Bun +bun add @vant/auto-import-resolver unplugin-vue-components -D +``` + +
+Vite
+ +```ts +// vite.config.ts +import Components from 'unplugin-vue-components/vite'; +import { VantResolver } from '@vant/auto-import-resolver'; + +export default defineConfig({ + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}); +``` + +
+ +
+Rollup
+ +```ts +// rollup.config.js +import Components from 'unplugin-vue-components/rollup'; +import { VantResolver } from '@vant/auto-import-resolver'; + +export default { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}; +``` + +
+ +
+Webpack
+ +```ts +// webpack.config.js +import Components from 'unplugin-vue-components/webpack'; +import { VantResolver } from '@vant/auto-import-resolver'; + +module.exports = { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}; +``` + +
+ +
+Vue CLI
+ +```ts +// vue.config.js +import Components from 'unplugin-vue-components/webpack'; +import { VantResolver } from '@vant/auto-import-resolver'; + +module.exports = { + configureWebpack: { + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], + }, +}; +``` + +
+ +
+esbuild
+ +```ts +// esbuild.config.js +import { build } from 'esbuild'; +import Components from 'unplugin-vue-components/esbuild'; +import { VantResolver } from '@vant/auto-import-resolver'; + +build({ + plugins: [ + Components({ + resolvers: [VantResolver()], + }), + ], +}); +``` + +
diff --git a/packages/auto-import-resolver/build.js b/packages/auto-import-resolver/build.js new file mode 100644 index 000000000..f696cf294 --- /dev/null +++ b/packages/auto-import-resolver/build.js @@ -0,0 +1 @@ +require('../vant-use/build'); diff --git a/packages/auto-import-resolver/package.json b/packages/auto-import-resolver/package.json new file mode 100644 index 000000000..2e78df975 --- /dev/null +++ b/packages/auto-import-resolver/package.json @@ -0,0 +1,44 @@ +{ + "name": "@vant/auto-import-resolver", + "version": "1.0.0", + "description": "Vant auto import resolver base unplugin-vue-components", + "main": "dist/index.cjs.js", + "module": "dist/index.esm.mjs", + "typings": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.esm.mjs", + "require": "./dist/index.cjs.js" + } + }, + "sideEffects": false, + "files": [ + "dist" + ], + "scripts": { + "clean": "rimraf ./dist", + "dev": "node ./build.js -w", + "build:types": "tsc -p ./tsconfig.json --emitDeclarationOnly", + "build:bundle": "node ./build.js", + "build": "pnpm clean && pnpm build:bundle && pnpm build:types", + "release": "vant-cli release", + "prepare": "pnpm build" + }, + "publishConfig": { + "access": "public", + "registry": "https://registry.npmjs.org/" + }, + "repository": { + "type": "git", + "url": "https://github.com/vant-ui/vant.git", + "directory": "packages/auto-import-resolver" + }, + "bugs": "https://github.com/vant-ui/vant/issues", + "author": "chenjiahan", + "license": "MIT", + "devDependencies": { + "rimraf": "^5.0.0", + "typescript": "^5.0.4" + } +} diff --git a/packages/auto-import-resolver/src/index.ts b/packages/auto-import-resolver/src/index.ts new file mode 100644 index 000000000..af8e3454f --- /dev/null +++ b/packages/auto-import-resolver/src/index.ts @@ -0,0 +1,58 @@ +export interface VantResolverOptions { + /** + * import style css or less along with components + * + * @default true + */ + importStyle?: boolean | 'css' | 'less'; + + /** + * use lib + * + * @default false + */ + ssr?: boolean; +} + +/** + * Button->button; ButtonGroup->button-group + */ +function kebabCase(key: string) { + const result = key.replace(/([A-Z])/g, ' $1').trim(); + return result.split(' ').join('-').toLowerCase(); +} + +function getModuleType(ssr: boolean): string { + return ssr ? 'lib' : 'es'; +} + +function getSideEffects(dirName: string, options: VantResolverOptions) { + const { importStyle = true, ssr = false } = options; + if (!importStyle) return; + + const moduleType = getModuleType(ssr); + + if (importStyle === 'less') return `vant/${moduleType}/${dirName}/style/less`; + + return `vant/${moduleType}/${dirName}/style/index`; +} + +export function VantResolver(options: VantResolverOptions = {}) { + const { ssr = false } = options; + + const moduleType = getModuleType(ssr); + + return { + type: 'component', + resolve: (name: string) => { + if (name.startsWith('Van')) { + const partialName = name.slice(3); + return { + name: partialName, + from: `vant/${moduleType}`, + sideEffects: getSideEffects(kebabCase(partialName), options), + }; + } + }, + }; +} diff --git a/packages/auto-import-resolver/tsconfig.json b/packages/auto-import-resolver/tsconfig.json new file mode 100644 index 000000000..8d24efe7b --- /dev/null +++ b/packages/auto-import-resolver/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../../tsconfig", + "compilerOptions": { + "outDir": "./dist", + "declaration": true + }, + "include": ["src/**/*"], + "exclude": ["**/node_modules", "**/.*/"] +} diff --git a/packages/auto-import-resolver/vant.config.mjs b/packages/auto-import-resolver/vant.config.mjs new file mode 100644 index 000000000..f1aa33180 --- /dev/null +++ b/packages/auto-import-resolver/vant.config.mjs @@ -0,0 +1,5 @@ +export default { + build: { + packageManager: 'pnpm', + }, +}; diff --git a/packages/vant/docs/markdown/quickstart.en-US.md b/packages/vant/docs/markdown/quickstart.en-US.md index 7cb8a4223..d6f768085 100644 --- a/packages/vant/docs/markdown/quickstart.en-US.md +++ b/packages/vant/docs/markdown/quickstart.en-US.md @@ -76,28 +76,42 @@ For enterprise developers, we recommend: ### CLI -We recommend to use [Vue CLI](https://cli.vuejs.org/) to create a new project. +We recommend to use [Vite](https://vitejs.dev/config/) to create a new project. ```bash -# Install Vue CLI -npm install -g @vue/cli +# npm 6.x +npm create vite@latest my-vue-app --template vue -# Create a project -vue create hello-world +# npm 7+, extra double-dash is needed: +npm create vite@latest my-vue-app -- --template vue -# Open GUI -vue ui +# yarn +yarn create vite my-vue-app --template vue + +# pnpm +pnpm create vite my-vue-app --template vue ``` -![](https://fastly.jsdelivr.net/npm/@vant/assets/vue-cli-demo-201809030812.png) +then -In the GUI, click on 'Dependencies' -> `Install Dependencies` and add `vant` to the dependencies. +```bash +cd my-vue-app + +# with npm +npm install vant + +# with yarn +yarn add vant + +# with pnpm +pnpm add vant +``` ## Usage ### Basic Usage -The basic usage of Vant components; +The basic usage of Vant components: ```js import { createApp } from 'vue'; @@ -116,22 +130,26 @@ app.use(Button); ### Import on demand -If you are using vite, webpack or vue-cli, you can use [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components), this plugin can help you to auto importing components and reduce CSS file size. +If you are using `vite`, `webpack` or `vue-cli`, you can use [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components), this plugin can help you to auto importing components. + +Vant officially wrote an automatic import style parser [@vant/auto-import-resolver](https://github.com/youzan/vant/tree/main/packages/auto-import-resolver) based on `unplugin-vue-components`, both of which are used together. + +Compared with conventional usage, this method can introduce the CSS style of components on demand, thus reducing part of the code volume, but it will become more cumbersome to use. If the business's volume requirements for CSS are not particularly extreme, we recommend a simpler general usage. #### 1. Install Plugin ```bash # with npm -npm i unplugin-vue-components -D +npm i @vant/auto-import-resolver unplugin-vue-components -D # with yarn -yarn add unplugin-vue-components -D +yarn add @vant/auto-import-resolver unplugin-vue-components -D # with pnpm -pnpm add unplugin-vue-components -D +pnpm add @vant/auto-import-resolver unplugin-vue-components -D # with Bun -bun add unplugin-vue-components -D +bun add @vant/auto-import-resolver unplugin-vue-components -D ``` #### 2. Configure Plugin @@ -141,7 +159,7 @@ For `vite` based project，configure the plugin in the `vite.config.js` file: ```js import vue from '@vitejs/plugin-vue'; import Components from 'unplugin-vue-components/vite'; -import { VantResolver } from 'unplugin-vue-components/resolvers'; +import { VantResolver } from '@vant/auto-import-resolver'; export default { plugins: [ @@ -156,7 +174,7 @@ export default { For `vue-cli` based project，configure the plugin in the `vue.config.js` file: ```js -const { VantResolver } = require('unplugin-vue-components/resolvers'); +const { VantResolver } = require('@vant/auto-import-resolver'); const ComponentsPlugin = require('unplugin-vue-components/webpack'); module.exports = { @@ -173,7 +191,7 @@ module.exports = { For `webpack` based project，configure the plugin in the `webpack.config.js` file: ```js -const { VantResolver } = require('unplugin-vue-components/resolvers'); +const { VantResolver } = require('@vant/auto-import-resolver'); const ComponentsPlugin = require('unplugin-vue-components/webpack'); module.exports = { @@ -187,7 +205,7 @@ module.exports = { #### 3. Using Components -Then you can using components from Vant in the template, the `unplugin-vue-components` will automatically import the corresponding Vant components. +Then you can using components from Vant in the template, the `unplugin-vue-components` will automatically import the corresponding Vant components,`@vant/auto-import-resolver` The corresponding component style will be automatically introduced. ```html