Skip to content

Commit 90b2b6a

Browse files
meteorlxymeteorlxy
committed
docs: improve bundler guide (close vuepress#425)
1 parent 5654685 commit 90b2b6a

File tree

8 files changed

+202
-174
lines changed

8 files changed

+202
-174
lines changed

‎docs/guide/bundler.md

+9-85
Original file line numberDiff line numberDiff line change
@@ -4,69 +4,17 @@ VuePress has been using [webpack](https://webpack.js.org/) as the bundler to dev
44

55
Although it is possible to create other bundler packages by community users, currently we only suggest to use the bundlers provided by VuePress team.
66

7-
## Webpack
7+
## Choose a Bundler
88

9-
When using the [vuepress](https://www.npmjs.com/package/vuepress) package, the webpack bundler is installed:
9+
When using the [vuepress](https://www.npmjs.com/package/vuepress) package, webpack bundler is installed and used automatically.
1010

11-
<CodeGroup>
12-
<CodeGroupItem title="YARN" active>
13-
14-
```bash
15-
yarn add -D vuepress@next
16-
```
17-
18-
</CodeGroupItem>
19-
20-
<CodeGroupItem title="NPM">
21-
22-
```bash
23-
npm install -D vuepress@next
24-
```
25-
26-
</CodeGroupItem>
27-
</CodeGroup>
28-
29-
You can specify the name of the bundler to use in [bundler](../reference/config.md#bundler) option, or omit it because webpack is the default bundler when using `vuepress` package. Then you can set [options of webpack bundler](../reference/bundler/webpack.md) via [bundlerConfig](../reference/config.md#bundlerconfig) option:
30-
31-
<CodeGroup>
32-
<CodeGroupItem title="JS" active>
33-
34-
```js
35-
module.exports = {
36-
bundler: '@vuepress/webpack',
37-
bundlerConfig: {
38-
// webpack bundler options
39-
},
40-
}
41-
```
42-
43-
</CodeGroupItem>
44-
45-
<CodeGroupItem title="TS">
46-
47-
```ts
48-
import { defineUserConfig } from 'vuepress'
49-
import type { DefaultThemeOptions, WebpackBundlerOptions } from 'vuepress'
50-
51-
export default defineUserConfig<DefaultThemeOptions, WebpackBundlerOptions>({
52-
bundler: '@vuepress/webpack',
53-
bundlerConfig: {
54-
// webpack bundler options
55-
},
56-
})
57-
```
58-
59-
</CodeGroupItem>
60-
</CodeGroup>
61-
62-
## Vite
63-
64-
If you want to use Vite instead, you can switch to [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package:
11+
If you want to use vite bundler instead, you can switch to [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package:
6512

6613
<CodeGroup>
6714
<CodeGroupItem title="YARN" active>
6815

6916
```bash
17+
yarn remove vuepress
7018
yarn add -D vuepress-vite@next
7119
```
7220

@@ -75,41 +23,17 @@ yarn add -D vuepress-vite@next
7523
<CodeGroupItem title="NPM">
7624

7725
```bash
26+
npm uninstall vuepress
7827
npm install -D vuepress-vite@next
7928
```
8029

8130
</CodeGroupItem>
8231
</CodeGroup>
8332

84-
You can specify the name of the bundler to use in [bundler](../reference/config.md#bundler) option, or omit it because vite is the default bundler when using `vuepress-vite` package. Then you can set [options of vite bundler](../reference/bundler/vite.md) via [bundlerConfig](../reference/config.md#bundlerconfig) option:
33+
## Bundler Config
8534

86-
<CodeGroup>
87-
<CodeGroupItem title="JS" active>
88-
89-
```js
90-
module.exports = {
91-
bundler: '@vuepress/vite',
92-
bundlerConfig: {
93-
// vite bundler options
94-
},
95-
}
96-
```
97-
98-
</CodeGroupItem>
35+
Generally, you could use a bundler without extra configuration, because we have already configured them properly to work with VuePress.
9936

100-
<CodeGroupItem title="TS">
37+
Similar to [themeConfig](../reference/config.md#themeconfig), VuePress also allows users to set bundler config via [bundlerConfig](../reference/config.md#bundlerconfig).
10138

102-
```ts
103-
import { defineUserConfig } from 'vuepress-vite'
104-
import type { DefaultThemeOptions, ViteBundlerOptions } from 'vuepress-vite'
105-
106-
export default defineUserConfig<DefaultThemeOptions, ViteBundlerOptions>({
107-
bundler: '@vuepress/vite',
108-
bundlerConfig: {
109-
// vite bundler options
110-
},
111-
})
112-
```
113-
114-
</CodeGroupItem>
115-
</CodeGroup>
39+
You can refer to [Bundlers > Webpack](../reference/bundler/webpack.md) and [Bundlers > Vite](../reference/bundler/vite.md) to check out all options of the corresponding bundler.

‎docs/reference/bundler/vite.md

+45-1
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,53 @@
22

33
<NpmBadge package="@vuepress/bundler-vite" />
44

5+
Vite bundler is provided by [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) package. It is a dependency of the [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package, and you can also install it separately.
6+
7+
```bash
8+
npm i -D @vuepress/bundler-vite@next
9+
```
10+
511
## Options
612

7-
Reference of webpack bundler config, which can be set via [bundlerConfig](../config.md#bundlerconfig).
13+
Reference of vite bundler config, which can be set via [bundlerConfig](../config.md#bundlerconfig).
14+
15+
<CodeGroup>
16+
<CodeGroupItem title="JS" active>
17+
18+
```js
19+
module.exports = {
20+
// when using vuepress-vite package, you can omit this field
21+
// because vite is the default bundler
22+
bundler: '@vuepress/bundler-vite',
23+
// bundler options
24+
bundlerConfig: {
25+
// see below
26+
},
27+
}
28+
```
29+
30+
</CodeGroupItem>
31+
32+
<CodeGroupItem title="TS">
33+
34+
```ts
35+
import type { ViteBundlerOptions } from '@vuepress/bundler-vite'
36+
import { defineUserConfig } from '@vuepress/cli'
37+
import type { DefaultThemeOptions } from '@vuepress/theme-default'
38+
39+
export default defineUserConfig<DefaultThemeOptions, ViteBundlerOptions>({
40+
// when using vuepress-vite package, you can omit this field
41+
// because vite is the default bundler
42+
bundler: '@vuepress/bundler-vite',
43+
// options for vite bundler
44+
bundlerConfig: {
45+
// see below
46+
},
47+
})
48+
```
49+
50+
</CodeGroupItem>
51+
</CodeGroup>
852

953
### viteOptions
1054

‎docs/reference/bundler/webpack.md

+44
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,54 @@
22

33
<NpmBadge package="@vuepress/bundler-webpack" />
44

5+
Webpack bundler is provided by [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately.
6+
7+
```bash
8+
npm i -D @vuepress/bundler-webpack@next
9+
```
10+
511
## Options
612

713
Reference of webpack bundler config, which can be set via [bundlerConfig](../config.md#bundlerconfig).
814

15+
<CodeGroup>
16+
<CodeGroupItem title="JS" active>
17+
18+
```js
19+
module.exports = {
20+
// when using vuepress package, you can omit this field
21+
// because webpack is the default bundler
22+
bundler: '@vuepress/bundler-webpack',
23+
// options for webpack bundler
24+
bundlerConfig: {
25+
// see below
26+
},
27+
}
28+
```
29+
30+
</CodeGroupItem>
31+
32+
<CodeGroupItem title="TS">
33+
34+
```ts
35+
import type { WebpackBundlerOptions } from '@vuepress/bundler-webpack'
36+
import { defineUserConfig } from '@vuepress/cli'
37+
import type { DefaultThemeOptions } from '@vuepress/theme-default'
38+
39+
export default defineUserConfig<DefaultThemeOptions, WebpackBundlerOptions>({
40+
// when using vuepress package, you can omit this field
41+
// because webpack is the default bundler
42+
bundler: '@vuepress/bundler-webpack',
43+
// options for webpack bundler
44+
bundlerConfig: {
45+
// see below
46+
},
47+
})
48+
```
49+
50+
</CodeGroupItem>
51+
</CodeGroup>
52+
953
### configureWebpack
1054

1155
- Type: `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration`

‎docs/reference/node-api.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
<NpmBadge package="@vuepress/core" />
44

5-
Node API is provided by [@vuepress/core](https://www.npmjs.com/package/@vuepress/core) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately.
5+
Node API is provided by [@vuepress/core](https://www.npmjs.com/package/@vuepress/core) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately:
6+
7+
```bash
8+
npm i -D @vuepress/core@next
9+
```
610

711
## App
812

‎docs/zh/guide/bundler.md

+10-86
Original file line numberDiff line numberDiff line change
@@ -2,71 +2,19 @@
22

33
VuePress 一直以来都在使用 [webpack](https://webpack.js.org/) 作为打包工具来进行网站的开发和构建。从 VuePress v2 开始，也可以支持使用其他工具，如 [Vite](https://vitejs.dev/) 等。
44

5-
尽管社区用户也可以创建打包工具 Package ，但目前我们仅推荐使用由 VuePress 团队提供的打包工具。
5+
尽管社区用户也可以创建打包工具，但目前我们仅推荐使用由 VuePress 团队提供的打包工具。
66

7-
## Webpack
7+
## 选择一个打包工具
88

9-
在使用 [vuepress](https://www.npmjs.com/package/vuepress) Package 时，安装的是 webpack 打包工具：
9+
在使用 [vuepress](https://www.npmjs.com/package/vuepress) 包时，会自动安装和使用 Webpack 打包工具。
1010

11-
<CodeGroup>
12-
<CodeGroupItem title="YARN" active>
13-
14-
```bash
15-
yarn add -D vuepress@next
16-
```
17-
18-
</CodeGroupItem>
19-
20-
<CodeGroupItem title="NPM">
21-
22-
```bash
23-
npm install -D vuepress@next
24-
```
25-
26-
</CodeGroupItem>
27-
</CodeGroup>
28-
29-
你可以在 [bundler](../reference/config.md#bundler) 配置项中设置你要使用的打包工具名称，或者不设置它，因为在使用 `vuepress` Package 时， webpack 是默认的打包工具。此时你可以通过 [bundlerConfig](../reference/config.md#bundlerconfig) 配置项来设置 [webpack 打包工具的选项](../reference/bundler/webpack.md) ：
30-
31-
<CodeGroup>
32-
<CodeGroupItem title="JS" active>
33-
34-
```js
35-
module.exports = {
36-
bundler: '@vuepress/webpack',
37-
bundlerConfig: {
38-
// webpack 打包工具的选项
39-
},
40-
}
41-
```
42-
43-
</CodeGroupItem>
44-
45-
<CodeGroupItem title="TS">
46-
47-
```ts
48-
import { defineUserConfig } from 'vuepress'
49-
import type { DefaultThemeOptions, WebpackBundlerOptions } from 'vuepress'
50-
51-
export default defineUserConfig<DefaultThemeOptions, WebpackBundlerOptions>({
52-
bundler: '@vuepress/webpack',
53-
bundlerConfig: {
54-
// webpack 打包工具的选项
55-
},
56-
})
57-
```
58-
59-
</CodeGroupItem>
60-
</CodeGroup>
61-
62-
## Vite
63-
64-
如果想要改为使用 Vite ，你可以切换成 [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) Package ：
11+
如果你想改为使用 Vite 打包工具，那么你可以切换为 [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) 包：
6512

6613
<CodeGroup>
6714
<CodeGroupItem title="YARN" active>
6815

6916
```bash
17+
yarn remove vuepress
7018
yarn add -D vuepress-vite@next
7119
```
7220

@@ -75,41 +23,17 @@ yarn add -D vuepress-vite@next
7523
<CodeGroupItem title="NPM">
7624

7725
```bash
26+
npm uninstall vuepress
7827
npm install -D vuepress-vite@next
7928
```
8029

8130
</CodeGroupItem>
8231
</CodeGroup>
8332

84-
你可以在 [bundler](../reference/config.md#bundler) 配置项中设置你要使用的打包工具名称，或者不设置它，因为在使用 `vuepress-vite` Package 时， vite 是默认的打包工具。此时你可以通过 [bundlerConfig](../reference/config.md#bundlerconfig) 配置项来设置 [vite 打包工具的选项](../reference/bundler/vite.md) ：
33+
## 打包工具配置
8534

86-
<CodeGroup>
87-
<CodeGroupItem title="JS" active>
88-
89-
```js
90-
module.exports = {
91-
bundler: '@vuepress/vite',
92-
bundlerConfig: {
93-
// vite 打包工具的选项
94-
},
95-
}
96-
```
97-
98-
</CodeGroupItem>
35+
通常情况下，你不要任何额外配置就可以使用一个打包工具，因为我们已经帮你配置好了它们。
9936

100-
<CodeGroupItem title="TS">
37+
类似于 [themeConfig](../reference/config.md#themeconfig) ， VuePress 同样允许用户通过 [bundlerConfig](../reference/config.md#bundlerconfig) 来配置打包工具。
10138

102-
```ts
103-
import { defineUserConfig } from 'vuepress-vite'
104-
import type { DefaultThemeOptions, ViteBundlerOptions } from 'vuepress-vite'
105-
106-
export default defineUserConfig<DefaultThemeOptions, ViteBundlerOptions>({
107-
bundler: '@vuepress/vite',
108-
bundlerConfig: {
109-
// vite 打包工具的选项
110-
},
111-
})
112-
```
113-
114-
</CodeGroupItem>
115-
</CodeGroup>
39+
你可以参考 [打包工具 > Webpack](../reference/bundler/webpack.md) 和 [打包工具 > Vite](../reference/bundler/vite.md) 来查看对应打包工具的所有配置项。

0 commit comments

Comments
 (0)