diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md index 82ea1f1c0c..c1317ccd3a 100644 --- a/docs/guide/bundler.md +++ b/docs/guide/bundler.md @@ -1,3 +1,87 @@ # Bundler -> TODO +VuePress has been using [webpack](https://webpack.js.org/) as the bundler to dev and build sites. Since VuePress v2, other tools like [Vite](https://vitejs.dev/) are also supported. + +Although it is possible to create other bundler packages by community users, currently we only suggest to use the bundlers provided by VuePress team. + +## Webpack + +When using the [vuepress](https://www.npmjs.com/package/vuepress) package, the webpack bundler is installed: + +```sh +npm install -D vuepress +``` + +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. Then you can set [options of webpack bundler](../reference/bundler/webpack.md) via [bundlerConfig](../reference/config.md#bundlerconfig) option: + + + + +```js +module.exports = { + bundler: '@vuepress/webpack', + bundlerConfig: { + // webpack bundler options + }, +} +``` + + + + + +```ts +import { defineUserConfig } from 'vuepress' +import type { DefaultThemeOptions, WebpackBundlerOptions } from 'vuepress' + +export default defineUserConfig({ + bundler: '@vuepress/webpack', + bundlerConfig: { + // webpack bundler options + }, +}) +``` + + + + +## Vite + +If you want to use Vite instead, you can switch to [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package: + +```sh +npm install -D vuepress-vite +``` + +Next, you need to specify the name of the bundler to use in [bundler](../reference/config.md#bundler) option. Then you can set [options of vite bundler](../reference/bundler/vite.md) via [bundlerConfig](../reference/config.md#bundlerconfig) option: + + + + +```js +module.exports = { + bundler: '@vuepress/vite', + bundlerConfig: { + // vite bundler options + }, +} +``` + + + + + +```ts +import { defineUserConfig } from 'vuepress-vite' +import type { DefaultThemeOptions, ViteBundlerOptions } from 'vuepress-vite' + +export default defineUserConfig({ + bundler: '@vuepress/vite', + bundlerConfig: { + // vite bundler options + }, +}) +``` + + + diff --git a/docs/reference/bundler/vite.md b/docs/reference/bundler/vite.md index d5d34b36d4..cbde3ad97e 100644 --- a/docs/reference/bundler/vite.md +++ b/docs/reference/bundler/vite.md @@ -1,3 +1,19 @@ # Vite -> TODO +## viteOptions + +- Details: + + Accepts all options of Vite. + +- Also see: + - [Vite > Config](https://vitejs.dev/config/) + +## vuePluginOptions + +- Details: + + Accepts all options of [@vitejs/plugin-vue](https://www.npmjs.com/package/@vitejs/plugin-vue). + +- Also see: + - [Vite > Plugins > Official Plugins](https://vitejs.dev/plugins/#vitejs-plugin-vue) diff --git a/docs/reference/bundler/webpack.md b/docs/reference/bundler/webpack.md index 9486fe9466..0bf73d3e12 100644 --- a/docs/reference/bundler/webpack.md +++ b/docs/reference/bundler/webpack.md @@ -1,3 +1,102 @@ # Webpack -> TODO +## configureWebpack + +- Type: `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration` + +- Details: + + Edit the internal webpack config. + + This option accepts a function that will receive a webpack config object as the 1st argument, an `isServer` flag as the 2nd argument and an `isBuild` flag as the 3rd argument. You can either mutate the config directly, or return an object to be merged by [webpack-merge](https://github.com/survivejs/webpack-merge). + +## chainWebpack + +- Type: `(config: WebpackChainConfig, isServer: boolean, isBuild: boolean) => void` + +- Details: + + Edit the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). + + This option accepts a function that will receive a `Config` instance that provided by `webpack-chain` as the 1st argument an `isServer` flag as the 2nd argument and an `isBuild` flag as the 3rd argument. + +## beforeDevServer + +- Type: `(expressApp: Application, server: WebpackDevServer) => void` + +- Details: + + A hook to be called in `devServer.before` of webpack. + + The arguments of the function are the first two arguments of `devServer.before`. + +- Also see: + - [Webpack > Configuration > DevServer > devServer.before](https://webpack.js.org/configuration/dev-server/#devserverbefore) + +## afterDevServer + +- Type: `(expressApp: Application, server: WebpackDevServer) => void` + +- Details: + + A hook to be called in `devServer.after` of webpack. + + The arguments of the function are the first two arguments of `devServer.after`. + +- Also see: + - [Webpack > Configuration > DevServer > devServer.after](https://webpack.js.org/configuration/dev-server/#devserverafter) + +## postcss + +- Type: `PostcssLoaderOptions` + +- Details: + + Options for `postcss-loader`. + +- Also see: + - [postcss-loader > Options](https://github.com/webpack-contrib/postcss-loader#options) + +## stylus + +- Type: `StylusLoaderOptions` + +- Details: + + Options for `stylus-loader`. + +- Also see: + - [stylus-loader > Options](https://github.com/webpack-contrib/stylus-loader#options) + +## scss + +- Type: `SassLoaderOptions` + +- Details: + + Options for `sass-loader` for `.scss` files. + +- Also see: + - [sass-loader > Options](https://github.com/webpack-contrib/sass-loader#options) + +## sass + +- Type: `SassLoaderOptions` + +- Details: + + Options for `sass-loader` for `.sass` files. + +- Also see: + - [sass-loader > Options](https://github.com/webpack-contrib/sass-loader#options) + +## less + +- Type: `LessLoaderOptions` + +- Details: + + Options for `less-loader`. + +- Also see: + - [less-loader > Options](https://github.com/webpack-contrib/less-loader#options) diff --git a/docs/reference/config.md b/docs/reference/config.md index ce0fec6926..9d4afb972b 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -207,6 +207,11 @@ module.exports = { Provide config options to the used bundler. The options will vary depending on the bundler you are using. +- Also see: + - [Guide > Bundler](../guide/bundler.md) + - [Bundlers > Webpack](./bundler/webpack.md) + - [Bundlers > Vite](./bundler/vite.md) + ## Directory Config ### dest diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md index d6659134d6..7ecadafce0 100644 --- a/docs/zh/guide/bundler.md +++ b/docs/zh/guide/bundler.md @@ -1,3 +1,87 @@ # 打包工具 -> TODO +VuePress 一直以来都在使用 [webpack](https://webpack.js.org/) 作为打包工具来进行网站的开发和构建。从 VuePress v2 开始,也可以支持使用其他工具,如 [Vite](https://vitejs.dev/) 等。 + +尽管社区用户也可以创建打包工具 Package ,但目前我们仅推荐使用由 VuePress 团队提供的打包工具。 + +## Webpack + +在使用 [vuepress](https://www.npmjs.com/package/vuepress) Package 时,安装的是 webpack 打包工具: + +```sh +npm install -D vuepress +``` + +你可以在 [bundler](../reference/config.md#bundler) 配置项中设置你要使用的打包工具名称,或者不设置它,因为 webpack 是默认的打包工具。此时你可以通过 [bundlerConfig](../reference/config.md#bundlerconfig) 配置项来设置 [webpack 打包工具的选项](../reference/bundler/webpack.md) : + + + + +```js +module.exports = { + bundler: '@vuepress/webpack', + bundlerConfig: { + // webpack 打包工具的选项 + }, +} +``` + + + + + +```ts +import { defineUserConfig } from 'vuepress' +import type { DefaultThemeOptions, WebpackBundlerOptions } from 'vuepress' + +export default defineUserConfig({ + bundler: '@vuepress/webpack', + bundlerConfig: { + // webpack 打包工具的选项 + }, +}) +``` + + + + +## Vite + +如果想要改为使用 Vite ,你可以切换成 [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) Package : + +```sh +npm install -D vuepress-vite +``` + +接下来,你需要在 [bundler](../reference/config.md#bundler) 配置项中设置你要使用的打包工具名称。此时你可以通过 [bundlerConfig](../reference/config.md#bundlerconfig) 配置项来设置 [vite 打包工具的选项](../reference/bundler/vite.md) : + + + + +```js +module.exports = { + bundler: '@vuepress/vite', + bundlerConfig: { + // vite 打包工具的选项 + }, +} +``` + + + + + +```ts +import { defineUserConfig } from 'vuepress-vite' +import type { DefaultThemeOptions, ViteBundlerOptions } from 'vuepress-vite' + +export default defineUserConfig({ + bundler: '@vuepress/vite', + bundlerConfig: { + // vite 打包工具的选项 + }, +}) +``` + + + diff --git a/docs/zh/reference/bundler/vite.md b/docs/zh/reference/bundler/vite.md index d5d34b36d4..80f123f590 100644 --- a/docs/zh/reference/bundler/vite.md +++ b/docs/zh/reference/bundler/vite.md @@ -1,3 +1,19 @@ # Vite -> TODO +## viteOptions + +- 详情: + + 接收 Vite 的所有配置项。 + +- 参考: + - [Vite > Config](https://vitejs.dev/config/) + +## vuePluginOptions + +- 详情: + + 接收 [@vitejs/plugin-vue](https://www.npmjs.com/package/@vitejs/plugin-vue) 的所有配置项。 + +- 参考: + - [Vite > Plugins > Official Plugins](https://vitejs.dev/plugins/#vitejs-plugin-vue) diff --git a/docs/zh/reference/bundler/webpack.md b/docs/zh/reference/bundler/webpack.md index 9486fe9466..2df4f6e6fd 100644 --- a/docs/zh/reference/bundler/webpack.md +++ b/docs/zh/reference/bundler/webpack.md @@ -1,3 +1,102 @@ # Webpack -> TODO +## configureWebpack + +- 类型: `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration` + +- 详情: + + 用于修改内部的 Webpack 配置。 + + 该配置项接收一个函数,该函数的第一个参数是 Webpack 配置对象,第二个参数是 `isServer` 标志位,第三个参数是 `isBuild` 标志位。 + +## chainWebpack + +- 类型: `(config: WebpackChainConfig, isServer: boolean, isBuild: boolean) => void` + +- 详情: + + 通过 [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) 来修改内部的 Webpack 配置。 + + 该配置项接收一个函数,该函数的第一个参数是由 `webpack-chain` 提供的 `Config` 实例,第二个参数是 `isServer` 标志位,第三个参数是 `isBuild` 标志位。 + +## beforeDevServer + +- 类型: `(expressApp: Application, server: WebpackDevServer) => void` + +- 详情: + + 在 Webpack 的 `devServer.before` 中调用的 Hook 。 + + 函数的参数是 `devServer.before` 的前两个参数。 + +- 参考: + - [Webpack > Configuration > DevServer > devServer.before](https://webpack.js.org/configuration/dev-server/#devserverbefore) + +## afterDevServer + +- 类型: `(expressApp: Application, server: WebpackDevServer) => void` + +- 详情: + + 在 Webpack 的 `devServer.after` 中调用的 Hook 。 + + 函数的参数是 `devServer.after` 的前两个参数。 + +- 参考: + - [Webpack > Configuration > DevServer > devServer.after](https://webpack.js.org/configuration/dev-server/#devserverafter) + +## postcss + +- 类型: `PostcssLoaderOptions` + +- 详情: + + `postcss-loader` 的配置项。 + +- 参考: + - [postcss-loader > Options](https://github.com/webpack-contrib/postcss-loader#options) + +## stylus + +- 类型: `StylusLoaderOptions` + +- 详情: + + `stylus-loader` 的配置项。 + +- 参考: + - [stylus-loader > Options](https://github.com/webpack-contrib/stylus-loader#options) + +## scss + +- 类型: `SassLoaderOptions` + +- 详情: + + 针对 `.scss` 文件的 `sass-loader` 的配置项。 + +- 参考: + - [sass-loader > Options](https://github.com/webpack-contrib/sass-loader#options) + +## sass + +- 类型: `SassLoaderOptions` + +- 详情: + + 针对 `.sass` 文件的 `sass-loader` 的配置项。 + +- 参考: + - [sass-loader > Options](https://github.com/webpack-contrib/sass-loader#options) + +## less + +- 类型: `LessLoaderOptions` + +- 详情: + + `less-loader` 的配置项。 + +- 参考: + - [less-loader > Options](https://github.com/webpack-contrib/less-loader#options) diff --git a/docs/zh/reference/config.md b/docs/zh/reference/config.md index c6702e3a24..f96588bcf1 100644 --- a/docs/zh/reference/config.md +++ b/docs/zh/reference/config.md @@ -206,6 +206,11 @@ module.exports = { 为当前使用的打包工具提供的配置项。具体的配置项取决于你使用的打包工具。 +- 参考: + - [指南 > 打包工具](../guide/bundler.md) + - [打包工具 > Webpack](./bundler/webpack.md) + - [打包工具 > Vite](./bundler/vite.md) + ## 目录配置 ### dest