From 5ce70ff5ebf280b3dd4843c07a1235f2fd58289a Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 26 Apr 2023 07:16:25 +0200 Subject: [PATCH 01/53] docs: releases page (#12909) Co-authored-by: sapphi-red Co-authored-by: fi3ework Co-authored-by: Jeff Yang Co-authored-by: Bjorn Lu --- .vitepress/config.ts | 1 + releases.md | 61 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 releases.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 97742080..62d5e110 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -136,6 +136,7 @@ export default defineConfig({ text: 'Resources', items: [ { text: 'Team', link: '/team' }, + { text: 'Releases', link: '/releases' }, { items: [ { diff --git a/releases.md b/releases.md new file mode 100644 index 00000000..d9c2eddb --- /dev/null +++ b/releases.md @@ -0,0 +1,61 @@ +# Releases + +Vite releases follow [Semantic Versioning](https://semver.org/). You can see the latest stable version of Vite in the [Vite npm package page](https://www.npmjs.com/package/vite). + +A full changelog of past releases is [available on GitHub](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md). + +::: tip note +The next Vite Major release will happen after the Node 16 EOL in September. + +Check out the [Vite 5 discussion](https://github.com/vitejs/vite/discussions/12466) for more information. +::: + +## Release Cycle​ + +Vite does not have a fixed release cycle. + +- **Patch** releases are released as needed. +- **Minor** releases always contain new features and are also released as needed. Minor releases always go through a beta pre-release phase. +- **Major** releases generally align with [Node.js EOL schedule](https://endoflife.date/nodejs), and will be announced ahead of time. These releases will go through an early discussion phase, and both alpha and beta pre-release phases. + +The previous Vite Major will keep receiving important fixes and security patches. After that, it would only get updates if there are security concerns. We recommend updating Vite regularly. Check out the [Migration Guides](https://vitejs.dev/guide/migration.html) when you update to each Major. + +The Vite team partners with the main projects in the ecosystem to test new Vite versions before they are released through the [vite-ecosystem-ci project](https://github.com/vitejs/vite-ecosystem-ci). Most projects using Vite should be able to quickly offer support or migrate to new versions as soon as they are released. + +## Semantic Versioning Edge Cases + +### TypeScript Definitions​ + +We may ship incompatible changes to TypeScript definitions between minor versions. This is because: + +- Sometimes TypeScript itself ships incompatible changes between minor versions, and we may have to adjust types to support newer versions of TypeScript. +- Occasionally we may need to adopt features that are only available in a newer version of TypeScript, raising the minimum required version of TypeScript. +- If you are using TypeScript, you can use a semver range that locks the current minor and manually upgrade when a new minor version of Vite is released. + +### esbuild + +[esbuild](https://esbuild.github.io/) is pre-1.0.0 and sometimes it has a breaking change we may need to include to have access to newer features and performance improvements. We may bump the esbuild's version in a Vite Minor. + +### Node.js non-LTS versions + +Non-LTS Node.js versions (odd-numbered) are not tested as part of Vite's CI, but they should still work before their [EOL](https://endoflife.date/nodejs). + +## Pre Releases​ + +Minor releases typically go through a non-fixed number of beta releases. Major releases will go through an alpha phase and a beta phase. + +Pre-releases allow early adopters and maintainers from the Ecosystem to do integration and stability testing, and provide feedback. Do not use pre-releases in production. All pre-releases are considered unstable and may ship breaking changes in between. Always pin to exact versions when using pre-releases. + +## Deprecations​ + +We periodically deprecate features that have been superseded by better alternatives in Minor releases. Deprecated features will continue to work with a type or logged warning. They will be removed in the next major release after entering deprecated status. The [Migration Guide](https://vitejs.dev/guide/migration.html) for each major will list these removals and document an upgrade path for them. + +## Experimental Features​ + +Some features are marked as experimental when released in a stable version of Vite. Experimental features allows us to gather real-world experience to influence their final design. The goal is to let users provide feedback by testing them in production. Experimental features themselves are considered unstable, and should only be used in a controlled manner. These features may change between Minors, so users must pin their Vite version when they rely on them. + +## RFCs​ + +Many changes, including features, bug fixes, and documentation improvements are discussed, implemented and reviewed via GitHub discussions, issues, and pull requests workflow. For substantial changes that would affect several downstream projects, we offer a Request For Comments (RFC) process to help gather consensus among the Vite core team, the Ecosystem, and the community. + +Continue reading about the RFC process in the [vitejs/rfcs](https://github.com/vitejs/rfcs) repo on GitHub. From 25deffbef79b1119c5004703c0f88456b1998157 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Tue, 2 May 2023 16:26:21 +0900 Subject: [PATCH 02/53] docs: update Vue 2 plugins (#13063) --- guide/features.md | 4 ++-- plugins/index.md | 6 +++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/guide/features.md b/guide/features.md index 6b2fab96..0e654cef 100644 --- a/guide/features.md +++ b/guide/features.md @@ -138,8 +138,8 @@ Vite provides first-class Vue support: - Vue 3 SFC support via [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue) - Vue 3 JSX support via [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) -- Vue 2.7 support via [@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) -- Vue <2.7 support via [vite-plugin-vue2](https://github.com/underfin/vite-plugin-vue2) +- Vue 2.7 SFC support via [@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) +- Vue 2.7 JSX support via [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) ## JSX diff --git a/plugins/index.md b/plugins/index.md index dd7cfce8..c16a1a32 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -18,7 +18,11 @@ Check out [Using Plugins](../guide/using-plugins) for information on how to use ### [@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) -- Provides Vue 2 Single File Components support. +- Provides Vue 2.7 Single File Components support. + +### [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) + +- Provides Vue 2.7 JSX support (via [dedicated Babel transform](https://github.com/vuejs/jsx-vue2/)). ### [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react) From 1b4af2270b132406e1c0acc90de9acf4929c4ce4 Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 3 May 2023 10:29:51 +0200 Subject: [PATCH 03/53] docs: document /index.html as importer during dev (#12911) Co-authored-by: Bjorn Lu --- guide/api-plugin.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guide/api-plugin.md b/guide/api-plugin.md index d5f92bad..ebcdade8 100644 --- a/guide/api-plugin.md +++ b/guide/api-plugin.md @@ -159,7 +159,9 @@ The following hooks are called on each incoming module request: - [`load`](https://rollupjs.org/plugin-development/#load) - [`transform`](https://rollupjs.org/plugin-development/#transform) -They also have an extended `options` parameter with additional Vite-specific properties. You can read more in the [SSR documentation](/guide/ssr#ssr-specific-plugin-logic). +These hooks also have an extended `options` parameter with additional Vite-specific properties. You can read more in the [SSR documentation](/guide/ssr#ssr-specific-plugin-logic). + +Some `resolveId` calls' `importer` value may be an absolute path for a generic `index.html` at root as it's not always possible to derive the actual importer due to Vite's unbundled dev server pattern. For imports handled within Vite's resolve pipeline, the importer can be tracked during the import analysis phase, providing the correct `importer` value. The following hooks are called when the server is closed: From dc196094799eda5166d05d43a7c45f5a85fd9346 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Sun, 14 May 2023 01:42:23 +0900 Subject: [PATCH 04/53] docs: remove RFCs section (#13193) --- releases.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/releases.md b/releases.md index d9c2eddb..31599406 100644 --- a/releases.md +++ b/releases.md @@ -53,9 +53,3 @@ We periodically deprecate features that have been superseded by better alternati ## Experimental Features​ Some features are marked as experimental when released in a stable version of Vite. Experimental features allows us to gather real-world experience to influence their final design. The goal is to let users provide feedback by testing them in production. Experimental features themselves are considered unstable, and should only be used in a controlled manner. These features may change between Minors, so users must pin their Vite version when they rely on them. - -## RFCs​ - -Many changes, including features, bug fixes, and documentation improvements are discussed, implemented and reviewed via GitHub discussions, issues, and pull requests workflow. For substantial changes that would affect several downstream projects, we offer a Request For Comments (RFC) process to help gather consensus among the Vite core team, the Ecosystem, and the community. - -Continue reading about the RFC process in the [vitejs/rfcs](https://github.com/vitejs/rfcs) repo on GitHub. From f080d5063f67843f4e4d4fd3dfa3790e4a33ff0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Sun, 14 May 2023 02:40:15 +0900 Subject: [PATCH 05/53] docs: tweak `build.cssCodeSplit` documentation (#13194) --- config/build-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/build-options.md b/config/build-options.md index ff4dbbd5..22306a7e 100644 --- a/config/build-options.md +++ b/config/build-options.md @@ -98,7 +98,7 @@ If you specify `build.lib`, `build.assetsInlineLimit` will be ignored and assets - **Type:** `boolean` - **Default:** `true` -Enable/disable CSS code splitting. When enabled, CSS imported in async chunks will be inlined into the async chunk itself and inserted when the chunk is loaded. +Enable/disable CSS code splitting. When enabled, CSS imported in async JS chunks will be preserved as chunks and fetched together when the chunk is fetched. If disabled, all CSS in the entire project will be extracted into a single CSS file. From 45850b0022ad9d392e87c7237bda18cf9e5b73fd Mon Sep 17 00:00:00 2001 From: Vincent Rubinetti Date: Wed, 17 May 2023 07:42:47 -0400 Subject: [PATCH 06/53] docs: update features.md note about ESM imports in web workers (#13223) --- guide/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/features.md b/guide/features.md index 0e654cef..c9e65807 100644 --- a/guide/features.md +++ b/guide/features.md @@ -541,7 +541,7 @@ import MyWorker from './worker?worker' const worker = new MyWorker() ``` -The worker script can also use `import` statements instead of `importScripts()` - note during dev this relies on browser native support and currently only works in Chrome, but for the production build it is compiled away. +The worker script can also use ESM `import` statements instead of `importScripts()`. **Note**: During dev this relies on [browser native support](https://caniuse.com/?search=module%20worker) (currently not supported in Firefox), but for the production build it is compiled away. By default, the worker script will be emitted as a separate chunk in the production build. If you wish to inline the worker as base64 strings, add the `inline` query: From ee51ae4229e5235c55a8f9b58243d5c460fa0be0 Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 24 May 2023 09:14:26 +0200 Subject: [PATCH 07/53] docs: transformIndexHtml order note (#13318) --- guide/api-plugin.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guide/api-plugin.md b/guide/api-plugin.md index ebcdade8..6024a6d9 100644 --- a/guide/api-plugin.md +++ b/guide/api-plugin.md @@ -345,6 +345,8 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo - An array of tag descriptor objects (`{ tag, attrs, children }`) to inject to the existing HTML. Each tag can also specify where it should be injected to (default is prepending to ``) - An object containing both as `{ html, tags }` + By default `order` is `undefined`, with this hook applied after the html has been transformed. In order to inject a script that should go through the Vite plugins pipeline, `order: 'pre'` will apply the hook before processing the HTML. `order: 'post'` applies the hook after all hooks with `order` undefined are applied. + **Basic Example:** ```js From c94a1a59278ef981f67da13c5a5ecea584966cc3 Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 24 May 2023 09:21:38 +0200 Subject: [PATCH 08/53] docs: preview not for production on CLI guide (#13316) Co-authored-by: Bjorn Lu --- guide/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/cli.md b/guide/cli.md index 91a89497..05061070 100644 --- a/guide/cli.md +++ b/guide/cli.md @@ -98,7 +98,7 @@ vite optimize [root] ### `vite preview` -Locally preview production build. +Locally preview the production build. Do not use this as a production server as it's not designed for it. #### Usage From f431096ec5f29674aff6d2cd7f883d126f6b1ab1 Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 24 May 2023 15:42:47 +0200 Subject: [PATCH 09/53] docs: optimizeDeps.needsInterop (#13323) Co-authored-by: Bjorn Lu <34116392+bluwy@users.noreply.github.com> --- config/dep-optimization-options.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/config/dep-optimization-options.md b/config/dep-optimization-options.md index 6c7f372a..60fb26cf 100644 --- a/config/dep-optimization-options.md +++ b/config/dep-optimization-options.md @@ -65,3 +65,10 @@ Optimizing dependencies in build mode is **experimental**. If enabled, it remove If you want to try this build strategy, you can use `optimizeDeps.disabled: false`. `@rollup/plugin-commonjs` can be removed by passing `build.commonjsOptions: { include: [] }`. ::: + +## optimizeDeps.needsInterop + +- **Experimental** +- **Type:** `string[]` + +Forces ESM interop when importing these dependencies. Vite is able to properly detect when a dependency needs interop, so this option isn't generally needed. However, different combinations of dependencies could cause some of them to be prebundled differently. Adding these packages to `needsInterop` can speed up cold start by avoiding full-page reloads. You'll receive a warning if this is the case for one of your dependencies, suggesting to add the package name to this array in your config. From 363be5ea3b39a765fbe8fed3f55b3d579711cb4c Mon Sep 17 00:00:00 2001 From: docschina Date: Thu, 25 May 2023 20:13:54 +0800 Subject: [PATCH 10/53] docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 45850b00 (#762) --- .vitepress/config.ts | 1 + guide/api-plugin.md | 2 ++ guide/features.md | 4 ++-- plugins/index.md | 4 ++++ releases.md | 55 ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 releases.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index e3b58e5d..e4fdea0b 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -85,6 +85,7 @@ export default defineConfig({ text: '相关链接', items: [ { text: 'Team', link: '/team' }, + { text: 'Releases', link: '/releases' }, { text: 'Twitter', link: 'https://twitter.com/vite_js' diff --git a/guide/api-plugin.md b/guide/api-plugin.md index 18a5e1ff..8e64fed9 100644 --- a/guide/api-plugin.md +++ b/guide/api-plugin.md @@ -161,6 +161,8 @@ console.log(msg) 它们还有一个扩展的 `options` 参数，包含其他特定于 Vite 的属性。你可以在 [SSR 文档](/guide/ssr#ssr-specific-plugin-logic) 中查阅更多内容。 +一些 `resolveId` 调用的 `importer` 值可能是根目录下的通用 `index.html` 的绝对路径，因为由于 Vite 非打包的开发服务器模式无法始终推导出实际的导入者。对于在 Vite 的解析管道中处理的导入，导入者可以在导入分析阶段进行跟踪，那时所提供的 `importer` 值是正确的。 + 以下钩子在服务器关闭时被调用： - [`buildEnd`](https://rollupjs.org/plugin-development/#buildend) diff --git a/guide/features.md b/guide/features.md index 361d48ee..6b70c0ef 100644 --- a/guide/features.md +++ b/guide/features.md @@ -139,7 +139,7 @@ Vite 为 Vue 提供第一优先级支持： - Vue 3 单文件组件支持：[@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue) - Vue 3 JSX 支持：[@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) - Vue 2.7 支持：[vitejs/vite-plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) -- Vue <2.7 的支持：[underfin/vite-plugin-vue2](https://github.com/underfin/vite-plugin-vue2) +- Vue 2.7 JSX support via [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) ## JSX {#jsx} @@ -541,7 +541,7 @@ import MyWorker from './worker?worker' const worker = new MyWorker() ``` -Worker 脚本也可以使用 `import` 语句来替代 `importScripts()` —— 注意，在开发过程中，这依赖于浏览器原生支持，目前只在 Chrome 中适用，而在生产版本中，它已经被编译掉了。 +Worker 脚本也可以使用 ESM 的 `import` 语句来替代 `importScripts()` —— **注意**，在开发过程中，这依赖于[浏览器原生支持](https://caniuse.com/?search=module%20worker)（目前在 Firefox 中不支持），而在生产版本中，它已经被编译掉了。 默认情况下，worker 脚本将在生产构建中编译成单独的 chunk。如果你想将 worker 内联为 base64 字符串，请添加 `inline` 查询参数： diff --git a/plugins/index.md b/plugins/index.md index 02792b0d..c673836f 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -20,6 +20,10 @@ Vite 旨在为常见的 web 开发工作提供开箱即用的支持。在搜索 - 提供对 Vue 2 的单文件组件支持。 +### [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) + +- 提供对 Vue 2.7 JSX 对支持（通过 [dedicated Babel transform](https://github.com/vuejs/jsx-vue2/)）。 + ### [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react) - 使用 esbuild 和 Babel，使用一个微小体积的包脚注可以实现极速的 HMR，同时提升灵活性，能够使用 Babel 的转换管线。在构建时没有使用额外的 Babel 插件，只使用了 esbuild。 diff --git a/releases.md b/releases.md new file mode 100644 index 00000000..31599406 --- /dev/null +++ b/releases.md @@ -0,0 +1,55 @@ +# Releases + +Vite releases follow [Semantic Versioning](https://semver.org/). You can see the latest stable version of Vite in the [Vite npm package page](https://www.npmjs.com/package/vite). + +A full changelog of past releases is [available on GitHub](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md). + +::: tip note +The next Vite Major release will happen after the Node 16 EOL in September. + +Check out the [Vite 5 discussion](https://github.com/vitejs/vite/discussions/12466) for more information. +::: + +## Release Cycle​ + +Vite does not have a fixed release cycle. + +- **Patch** releases are released as needed. +- **Minor** releases always contain new features and are also released as needed. Minor releases always go through a beta pre-release phase. +- **Major** releases generally align with [Node.js EOL schedule](https://endoflife.date/nodejs), and will be announced ahead of time. These releases will go through an early discussion phase, and both alpha and beta pre-release phases. + +The previous Vite Major will keep receiving important fixes and security patches. After that, it would only get updates if there are security concerns. We recommend updating Vite regularly. Check out the [Migration Guides](https://vitejs.dev/guide/migration.html) when you update to each Major. + +The Vite team partners with the main projects in the ecosystem to test new Vite versions before they are released through the [vite-ecosystem-ci project](https://github.com/vitejs/vite-ecosystem-ci). Most projects using Vite should be able to quickly offer support or migrate to new versions as soon as they are released. + +## Semantic Versioning Edge Cases + +### TypeScript Definitions​ + +We may ship incompatible changes to TypeScript definitions between minor versions. This is because: + +- Sometimes TypeScript itself ships incompatible changes between minor versions, and we may have to adjust types to support newer versions of TypeScript. +- Occasionally we may need to adopt features that are only available in a newer version of TypeScript, raising the minimum required version of TypeScript. +- If you are using TypeScript, you can use a semver range that locks the current minor and manually upgrade when a new minor version of Vite is released. + +### esbuild + +[esbuild](https://esbuild.github.io/) is pre-1.0.0 and sometimes it has a breaking change we may need to include to have access to newer features and performance improvements. We may bump the esbuild's version in a Vite Minor. + +### Node.js non-LTS versions + +Non-LTS Node.js versions (odd-numbered) are not tested as part of Vite's CI, but they should still work before their [EOL](https://endoflife.date/nodejs). + +## Pre Releases​ + +Minor releases typically go through a non-fixed number of beta releases. Major releases will go through an alpha phase and a beta phase. + +Pre-releases allow early adopters and maintainers from the Ecosystem to do integration and stability testing, and provide feedback. Do not use pre-releases in production. All pre-releases are considered unstable and may ship breaking changes in between. Always pin to exact versions when using pre-releases. + +## Deprecations​ + +We periodically deprecate features that have been superseded by better alternatives in Minor releases. Deprecated features will continue to work with a type or logged warning. They will be removed in the next major release after entering deprecated status. The [Migration Guide](https://vitejs.dev/guide/migration.html) for each major will list these removals and document an upgrade path for them. + +## Experimental Features​ + +Some features are marked as experimental when released in a stable version of Vite. Experimental features allows us to gather real-world experience to influence their final design. The goal is to let users provide feedback by testing them in production. Experimental features themselves are considered unstable, and should only be used in a controlled manner. These features may change between Minors, so users must pin their Vite version when they rely on them. From b38a5eb0cff0c7590319138606d0867749164c1b Mon Sep 17 00:00:00 2001 From: Wermeille Bastien Date: Sat, 27 May 2023 11:03:21 +0200 Subject: [PATCH 11/53] docs: update root documentation to include vite config file location (#13345) Co-authored-by: patak --- guide/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guide/index.md b/guide/index.md index 3ae2c5a0..118c53a2 100644 --- a/guide/index.md +++ b/guide/index.md @@ -110,6 +110,7 @@ Vite also supports [multi-page apps](./build#multi-page-app) with multiple `.htm #### Specifying Alternative Root Running `vite` starts the dev server using the current working directory as root. You can specify an alternative root with `vite serve some/sub/dir`. +Note that Vite will also resolve [its config file (i.e. `vite.config.js`)](/config/#configuring-vite) inside the project root, so you'll need to move it if the root is changed. ## Command Line Interface From a595081f23de8e4e52c847729047f424c2518e43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Thu, 1 Jun 2023 00:21:16 +0900 Subject: [PATCH 12/53] docs: cross drive links troubleshooting guide (#13392) --- guide/troubleshooting.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/guide/troubleshooting.md b/guide/troubleshooting.md index c9eeab87..ad636a26 100644 --- a/guide/troubleshooting.md +++ b/guide/troubleshooting.md @@ -154,3 +154,14 @@ If these code are used inside dependencies, you could use [`patch-package`](http ### Browser extensions Some browser extensions (like ad-blockers) may prevent the Vite client from sending requests to the Vite dev server. You may see a white screen without logged errors in this case. Try disabling extensions if you have this issue. + +### Cross drive links on Windows + +If there's a cross drive links in your project on Windows, Vite may not work. + +An example of cross drive links are: + +- a virtual drive linked to a folder by `subst` command +- a symlink/junction to a different drive by `mklink` command (e.g. Yarn global cache) + +Related issue: [#10802](https://github.com/vitejs/vite/issues/10802) From 30369baaefabf1baea1a5f88e904aa696b3a3064 Mon Sep 17 00:00:00 2001 From: patak Date: Wed, 31 May 2023 17:22:08 +0200 Subject: [PATCH 13/53] docs: clarify html input entry name ignored for HTML files (#13389) --- guide/build.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guide/build.md b/guide/build.md index 370b1264..7b711fe0 100644 --- a/guide/build.md +++ b/guide/build.md @@ -114,6 +114,8 @@ export default defineConfig({ If you specify a different root, remember that `__dirname` will still be the folder of your vite.config.js file when resolving the input paths. Therefore, you will need to add your `root` entry to the arguments for `resolve`. +Note that for HTML files, Vite ignores the name given to the entry in the `rollupOptions.input` object and instead respects the resolved id of the file when generating the HTML asset in the dist folder. This ensures a consistent structure with the way the dev server works. + ## Library Mode When you are developing a browser-oriented library, you are likely spending most of the time on a test/demo page that imports your actual library. With Vite, you can use your `index.html` for that purpose to get the smooth development experience. From 2bf5fee2d963bf74df387eefa871e68233d7fd1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Thu, 1 Jun 2023 00:52:30 +0900 Subject: [PATCH 14/53] docs: accessing the server on WSL2 from your LAN (#13393) --- config/server-options.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/config/server-options.md b/config/server-options.md index ab0f1b26..19065294 100644 --- a/config/server-options.md +++ b/config/server-options.md @@ -34,6 +34,13 @@ The second case is when wildcard hosts (e.g. `0.0.0.0`) are used. This is becaus ::: +::: tip Accessing the server on WSL2 from your LAN + +When running Vite on WSL2, it is not sufficient to set `host: true` to access the server from your LAN. +See [the WSL document](https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-a-wsl-2-distribution-from-your-local-area-network-lan) for more details. + +::: + ## server.port - **Type:** `number` From 403aec4451b5db7f9960a4f327f0418befeae853 Mon Sep 17 00:00:00 2001 From: docschina Date: Thu, 1 Jun 2023 18:16:28 +0800 Subject: [PATCH 15/53] docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 2bf5fee2 (#765) --- config/build-options.md | 2 +- config/dep-optimization-options.md | 7 +++++++ config/server-options.md | 7 +++++++ guide/api-plugin.md | 4 ++++ guide/build.md | 2 ++ guide/cli.md | 2 +- guide/features.md | 2 +- guide/index.md | 2 +- guide/troubleshooting.md | 11 +++++++++++ plugins/index.md | 2 +- 10 files changed, 36 insertions(+), 5 deletions(-) diff --git a/config/build-options.md b/config/build-options.md index a7ccb7b8..b2335ba4 100644 --- a/config/build-options.md +++ b/config/build-options.md @@ -98,7 +98,7 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含它们所 - **类型：** `boolean` - **默认：** `true` -启用/禁用 CSS 代码拆分。当启用时，在异步 chunk 中导入的 CSS 将内联到异步 chunk 本身，并在其被加载时插入。 +启用/禁用 CSS 代码拆分。当启用时，在异步 chunk 中导入的 CSS 将内联到异步 chunk 本身，并在其被加载时一并获取。 如果禁用，整个项目中的所有 CSS 将被提取到一个 CSS 文件中。 diff --git a/config/dep-optimization-options.md b/config/dep-optimization-options.md index 26753059..c483ccc9 100644 --- a/config/dep-optimization-options.md +++ b/config/dep-optimization-options.md @@ -65,3 +65,10 @@ export default defineConfig({ 如果你想尝试该构建策略，你可以使用 `optimizeDeps.disabled: false`。`@rollup/plugin-commonjs` 可以通过设置 `build.commonjsOptions: { include: [] }` 来移除。 ::: + +## optimizeDeps.needsInterop + +- **Experimental** +- **Type:** `string[]` + +Forces ESM interop when importing these dependencies. Vite is able to properly detect when a dependency needs interop, so this option isn't generally needed. However, different combinations of dependencies could cause some of them to be prebundled differently. Adding these packages to `needsInterop` can speed up cold start by avoiding full-page reloads. You'll receive a warning if this is the case for one of your dependencies, suggesting to add the package name to this array in your config. diff --git a/config/server-options.md b/config/server-options.md index 93945677..fd0e1f74 100644 --- a/config/server-options.md +++ b/config/server-options.md @@ -34,6 +34,13 @@ export default defineConfig({ ::: +::: tip 在 WSL2 中通过 LAN 访问开发服务器 + +当你在 WSL2 运行 Vite 时，仅设置 `host: true` 来从局域网访问服务器是不够的。 +请看 [WSL 相关文档](https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-a-wsl-2-distribution-from-your-local-area-network-lan) 了解更多细节。 + +::: + ## server.port {#server-port} - **类型：** `number` diff --git a/guide/api-plugin.md b/guide/api-plugin.md index 8e64fed9..cd891226 100644 --- a/guide/api-plugin.md +++ b/guide/api-plugin.md @@ -161,6 +161,8 @@ console.log(msg) 它们还有一个扩展的 `options` 参数，包含其他特定于 Vite 的属性。你可以在 [SSR 文档](/guide/ssr#ssr-specific-plugin-logic) 中查阅更多内容。 +一些 `resolveId` 调用 `importer` 值可能是根目录下 `index.html` 的绝对路径，这是由于 Vite 的非打包的开发服务器模式，并不总是可以获取到出实际的 importer。对于在 Vite 解析管道中处理的导入，可以在导入分析阶段跟踪导入方，提供正确的 `importer` 值。 + 一些 `resolveId` 调用的 `importer` 值可能是根目录下的通用 `index.html` 的绝对路径，因为由于 Vite 非打包的开发服务器模式无法始终推导出实际的导入者。对于在 Vite 的解析管道中处理的导入，导入者可以在导入分析阶段进行跟踪，那时所提供的 `importer` 值是正确的。 以下钩子在服务器关闭时被调用： @@ -344,6 +346,8 @@ Vite 插件也可以提供钩子来服务于特定的 Vite 目标。这些钩子 - 注入到现有 HTML 中的标签描述符对象数组（`{ tag, attrs, children }`）。每个标签也可以指定它应该被注入到哪里（默认是在 `` 之前） - 一个包含 `{ html, tags }` 的对象 + 默认情况下 `order` 是 `undefined`，这个钩子会在 HTML 被转换后应用。为了注入一个应该通过 Vite 插件管道的脚本， `order: 'pre'` 指将在处理 HTML 之前应用。 `order: 'post'` 是在所有未定义的 `order` 的钩子函数被应用后才应用。 + **基础示例：** ```js diff --git a/guide/build.md b/guide/build.md index dd4a9bc9..29afb3ac 100644 --- a/guide/build.md +++ b/guide/build.md @@ -114,6 +114,8 @@ export default defineConfig({ 如果你指定了另一个根目录，请记住，在解析输入路径时，`__dirname` 的值将仍然是 vite.config.js 文件所在的目录。因此，你需要把对应入口文件的 `root` 的路径添加到 `resolve` 的参数中。 +请注意，在 HTML 文件中，Vite 忽略了 `rollupOptions.input` 对象中给定的入口名称，而是在生成 dist 文件夹中的 HTML 资源文件时，使用了文件已解析的路径 ID。这确保了与开发服务器的工作方式保持一致的结构。 + ## 库模式 {#library-mode} 当你开发面向浏览器的库时，你可能会将大部分时间花在该库的测试/演示页面上。在 Vite 中你可以使用 `index.html` 获得如丝般顺滑的开发体验。 diff --git a/guide/cli.md b/guide/cli.md index 4088ebc5..e629dc77 100644 --- a/guide/cli.md +++ b/guide/cli.md @@ -98,7 +98,7 @@ vite optimize [root] ### `vite preview` {#vite-preview} -本地预览构建产物。 +本地预览构建产物。不要将其用作生产服务器，因为它不是为此而设计的。 #### 使用 {#usage-3} diff --git a/guide/features.md b/guide/features.md index 6b70c0ef..01f3154a 100644 --- a/guide/features.md +++ b/guide/features.md @@ -138,7 +138,7 @@ Vite 为 Vue 提供第一优先级支持： - Vue 3 单文件组件支持：[@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue) - Vue 3 JSX 支持：[@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) -- Vue 2.7 支持：[vitejs/vite-plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) +- Vue 2.7 SFC 支持：[@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) - Vue 2.7 JSX support via [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) ## JSX {#jsx} diff --git a/guide/index.md b/guide/index.md index ed81f487..e909605a 100644 --- a/guide/index.md +++ b/guide/index.md @@ -109,7 +109,7 @@ Vite 也支持多个 `.html` 作入口点的 [多页面应用模式](./build#mul #### 指定替代根目录 {#specifying-alternative-root} -`vite` 以当前工作目录作为根目录启动开发服务器。你也可以通过 `vite serve some/sub/dir` 来指定一个替代的根目录。 +`vite` 以当前工作目录作为根目录启动开发服务器。你也可以通过 `vite serve some/sub/dir` 来指定一个替代的根目录。注意 Vite 同时会解析项目根目录下的 [配置文件（即 `vite.config.js`）](/config/#configuring-vite)，因此如果根目录被改变了，你需要将配置文件移动到新的根目录下。 ## 命令行界面 {#command-line-interface} diff --git a/guide/troubleshooting.md b/guide/troubleshooting.md index c25b4c76..713ed8be 100644 --- a/guide/troubleshooting.md +++ b/guide/troubleshooting.md @@ -154,3 +154,14 @@ Vite 无法处理、也不支持仅可在非严格模式（sloppy mode）下运 ### 浏览器扩展程序 {#browser-extensions} 一些浏览器扩展程序（例如 ad-blockers 广告拦截器），可能会阻止 Vite 客户端向 Vite 开发服务器发送请求。在这种情况下，你可能会看到一个空白屏且没有错误日志。如果遇到这类问题，请尝试禁用扩展程序。 + +### Windows 上的跨驱动器链接 {#cross-drive-links-on-windows} + +如果你的项目中存在跨驱动器链接，Vite 可能无法工作。 + +跨驱动器链接的一个例子是： + +- 通过 `subst` 命令将虚拟驱动器链接到一个文件夹 +- 通过 `mklink` 命令将符号链接/联接到另一个驱动器（例如 Yarn 全局缓存） + +相关 issue：[#10802](https://github.com/vitejs/vite/issues/10802) diff --git a/plugins/index.md b/plugins/index.md index c673836f..8172987a 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -18,7 +18,7 @@ Vite 旨在为常见的 web 开发工作提供开箱即用的支持。在搜索 ### [@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2) -- 提供对 Vue 2 的单文件组件支持。 +- 提供对 Vue 2.7 的单文件组件支持。 ### [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx) From 3c5f1ea71aa609687c159df544902f793dd2a7d4 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Mon, 5 Jun 2023 21:47:56 +0800 Subject: [PATCH 16/53] docs: add special sponsors section (#13150) --- .vitepress/theme/composables/sponsor.ts | 49 +++++++++++++++++++++---- public/astro.svg | 1 + public/nuxtlabs.svg | 1 + public/stackblitz.svg | 1 + 4 files changed, 45 insertions(+), 7 deletions(-) create mode 100644 public/astro.svg create mode 100644 public/nuxtlabs.svg create mode 100644 public/stackblitz.svg diff --git a/.vitepress/theme/composables/sponsor.ts b/.vitepress/theme/composables/sponsor.ts index 3251509a..096927d4 100644 --- a/.vitepress/theme/composables/sponsor.ts +++ b/.vitepress/theme/composables/sponsor.ts @@ -21,8 +21,27 @@ const data = ref() const dataHost = 'https://sponsors.vuejs.org' const dataUrl = `${dataHost}/vite.json` -// no sponsors yet :( -const viteSponsors: Pick = { +const viteSponsors: Pick = { + special: [ + // sponsors patak-dev + { + name: 'StackBlitz', + url: 'https://stackblitz.com', + img: '/stackblitz.svg', + }, + // sponsors antfu + { + name: 'NuxtLabs', + url: 'https://nuxtlabs.com', + img: '/nuxtlabs.svg', + }, + // sponsors bluwy + { + name: 'Astro', + url: 'https://astro.build', + img: '/astro.svg', + }, + ], gold: [], } @@ -46,7 +65,12 @@ export function useSponsor() { function mapSponsors(sponsors: Sponsors) { return [ { - tier: 'Platinum Sponsor', + tier: 'Special Sponsors', + size: 'big', + items: viteSponsors['special'], + }, + { + tier: 'Platinum Sponsors', size: 'big', items: mapImgPath(sponsors['platinum']), }, @@ -58,9 +82,20 @@ function mapSponsors(sponsors: Sponsors) { ] } +const viteSponsorNames = new Set( + Object.values(viteSponsors).flatMap((sponsors) => + sponsors.map((s) => s.name), + ), +) + +/** + * Map Vue/Vite sponsors data to objects and filter out Vite-specific sponsors + */ function mapImgPath(sponsors: Sponsor[]) { - return sponsors.map((sponsor) => ({ - ...sponsor, - img: `${dataHost}/images/${sponsor.img}`, - })) + return sponsors + .filter((sponsor) => !viteSponsorNames.has(sponsor.name)) + .map((sponsor) => ({ + ...sponsor, + img: `${dataHost}/images/${sponsor.img}`, + })) } diff --git a/public/astro.svg b/public/astro.svg new file mode 100644 index 00000000..079378b2 --- /dev/null +++ b/public/astro.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/public/nuxtlabs.svg b/public/nuxtlabs.svg new file mode 100644 index 00000000..d2935645 --- /dev/null +++ b/public/nuxtlabs.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/public/stackblitz.svg b/public/stackblitz.svg new file mode 100644 index 00000000..a16fcd92 --- /dev/null +++ b/public/stackblitz.svg @@ -0,0 +1 @@ + \ No newline at end of file From 05bff01ac222aa7b12839e9b7defb6e75500aabd Mon Sep 17 00:00:00 2001 From: patak Date: Mon, 5 Jun 2023 16:35:15 +0200 Subject: [PATCH 17/53] docs: adjust aside sponsors max width (#13428) --- .vitepress/theme/styles/vars.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.vitepress/theme/styles/vars.css b/.vitepress/theme/styles/vars.css index 8af0ae26..58e5e79f 100644 --- a/.vitepress/theme/styles/vars.css +++ b/.vitepress/theme/styles/vars.css @@ -114,3 +114,7 @@ .dark .vp-doc .custom-block a { transition: color 0.25s; } + +.vp-sponsor.aside .vp-sponsor-grid.mini .vp-sponsor-grid-image { + max-width: 124px; +} From 8b00d08af9b49c37e0d68e937a69a2330404b945 Mon Sep 17 00:00:00 2001 From: Vladimir Ivakin Date: Tue, 6 Jun 2023 15:51:03 +0200 Subject: [PATCH 18/53] fix(mergeConfig): don't accept callback config (#13135) --- guide/api-javascript.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/guide/api-javascript.md b/guide/api-javascript.md index 41086c8d..cb154095 100644 --- a/guide/api-javascript.md +++ b/guide/api-javascript.md @@ -266,6 +266,10 @@ function mergeConfig( Deeply merge two Vite configs. `isRoot` represents the level within the Vite config which is being merged. For example, set `false` if you're merging two `build` options. +::: tip NOTE +`mergeConfig` accepts only config in object form. If you have a config in callback form, you should call it before passing into `mergeConfig`. +::: + ## `searchForWorkspaceRoot` **Type Signature:** From f5a320a322d1e119b617c593a261bd47ae8217ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0=20/=20green?= Date: Tue, 6 Jun 2023 23:04:50 +0900 Subject: [PATCH 19/53] feat(config): friendly ESM file require error (#13283) --- guide/troubleshooting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/guide/troubleshooting.md b/guide/troubleshooting.md index ad636a26..41089024 100644 --- a/guide/troubleshooting.md +++ b/guide/troubleshooting.md @@ -15,6 +15,23 @@ You will need to either: - Switch to another package manager (e.g. `pnpm`, `yarn`) - Remove `&` from the path to your project +## Config + +### This package is ESM only + +When importing a ESM only package by `require`, the following error happens. + +> Failed to resolve "foo". This package is ESM only but it was tried to load by `require`. + +> "foo" resolved to an ESM file. ESM file cannot be loaded by `require`. + +ESM files cannot be loaded by [`require`](). + +We recommend converting your config to ESM by either: + +- adding `"type": "module"` to the nearest `package.json` +- renaming `vite.config.js`/`vite.config.ts` to `vite.config.mjs`/`vite.config.mts` + ## Dev Server ### Requests are stalled forever From 239df056933e71c336f302c2a38bbb730eb140df Mon Sep 17 00:00:00 2001 From: Wermeille Bastien Date: Tue, 6 Jun 2023 16:36:28 +0200 Subject: [PATCH 20/53] feat: support files for `fs.allow` (#12863) --- config/server-options.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/config/server-options.md b/config/server-options.md index 19065294..8ee1a40b 100644 --- a/config/server-options.md +++ b/config/server-options.md @@ -266,6 +266,8 @@ Restrict serving files outside of workspace root. Restrict files that could be served via `/@fs/`. When `server.fs.strict` is set to `true`, accessing files outside this directory list that aren't imported from an allowed file will result in a 403. +Both directories and files can be provided. + Vite will search for the root of the potential workspace and use it as default. A valid workspace met the following conditions, otherwise will fall back to the [project root](/guide/#index-html-and-project-root). - contains `workspaces` field in `package.json` @@ -298,7 +300,8 @@ export default defineConfig({ // search up for workspace root searchForWorkspaceRoot(process.cwd()), // your custom rules - '/path/to/custom/allow', + '/path/to/custom/allow_directory', + '/path/to/custom/allow_file.demo', ], }, }, From e21927c322611f4fdb92091b14343bd79052d86d Mon Sep 17 00:00:00 2001 From: Ilya Golovin <74474615+maIIady@users.noreply.github.com> Date: Tue, 6 Jun 2023 19:39:05 +0300 Subject: [PATCH 21/53] docs(chunkSplitting): add `manualChunks` object form syntax warning when it is used with the `splitVendorChunk` plugin (#13431) Co-authored-by: patak --- guide/build.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/guide/build.md b/guide/build.md index 7b711fe0..f817afaa 100644 --- a/guide/build.md +++ b/guide/build.md @@ -60,6 +60,10 @@ export default defineConfig({ This strategy is also provided as a `splitVendorChunk({ cache: SplitVendorChunkCache })` factory, in case composition with custom logic is needed. `cache.reset()` needs to be called at `buildStart` for build watch mode to work correctly in this case. +::: warning +You should use `build.rollupOptions.output.manualChunks` function form when using this plugin. If the object form is used, the plugin won't have any effect. +::: + ## Rebuild on files changes You can enable rollup watcher with `vite build --watch`. Or, you can directly adjust the underlying [`WatcherOptions`](https://rollupjs.org/configuration-options/#watch) via `build.watch`: From ee4822d4315af40b06be97911157c3579fcd13cc Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Wed, 7 Jun 2023 16:13:24 +0800 Subject: [PATCH 22/53] feat(optimizer): support glob includes (#12414) --- config/dep-optimization-options.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/config/dep-optimization-options.md b/config/dep-optimization-options.md index 60fb26cf..d6b994b3 100644 --- a/config/dep-optimization-options.md +++ b/config/dep-optimization-options.md @@ -35,6 +35,16 @@ export default defineConfig({ By default, linked packages not inside `node_modules` are not pre-bundled. Use this option to force a linked package to be pre-bundled. +**Experimental:** If you're using a library with many deep imports, you can also specify a trailing glob pattern to pre-bundle all deep imports at once. This will avoid constantly pre-bundling whenever a new deep import is used. For example: + +```js +export default defineConfig({ + optimizeDeps: { + include: ['my-lib/components/**/*.vue'], + }, +}) +``` + ## optimizeDeps.esbuildOptions - **Type:** [`EsbuildBuildOptions`](https://esbuild.github.io/api/#simple-options) From 334f84ab655867a1a1b2e2f97fcf2210f51e5b67 Mon Sep 17 00:00:00 2001 From: HaeJun Seo Date: Thu, 8 Jun 2023 16:06:02 +0900 Subject: [PATCH 23/53] docs: link to ko translation (#13285) --- .vitepress/config.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 62d5e110..22ebb5f2 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -92,6 +92,7 @@ export default defineConfig({ ja: { label: '日本語', link: 'https://ja.vitejs.dev' }, es: { label: 'Español', link: 'https://es.vitejs.dev' }, pt: { label: 'Português', link: 'https://pt.vitejs.dev' }, + ko: { label: '한국어', link: 'https://ko.vitejs.dev' }, }, themeConfig: { From a88e033d55bdd206574320c80110e9f08036c7ee Mon Sep 17 00:00:00 2001 From: patak Date: Fri, 9 Jun 2023 11:23:03 +0200 Subject: [PATCH 24/53] docs: link to the config and using plugin sections from getting started (#13472) --- guide/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guide/index.md b/guide/index.md index 118c53a2..a7ab75db 100644 --- a/guide/index.md +++ b/guide/index.md @@ -12,7 +12,9 @@ Vite (French word for "quick", pronounced `/vit/`