diff --git a/docs/config/build-options.md b/docs/config/build-options.md index 3939261ea6674e..4d620a91b2ede0 100644 --- a/docs/config/build-options.md +++ b/docs/config/build-options.md @@ -12,9 +12,9 @@ Browser compatibility target for the final bundle. The default value is a Vite s Another special value is `'esnext'` - which assumes native dynamic imports support and will only perform minimal transpiling. -The transform is performed with esbuild and the value should be a valid [esbuild target option](https://esbuild.github.io/api/#target). Custom targets can either be an ES version (e.g. `es2015`), a browser with version (e.g. `chrome58`), or an array of multiple target strings. +The transform is performed with Oxc Transformer and the value should be a valid [Oxc Transformer target option](https://oxc.rs/docs/guide/usage/transformer/lowering#target). Custom targets can either be an ES version (e.g. `es2015`), a browser with version (e.g. `chrome58`), or an array of multiple target strings. -Note the build will fail if the code contains features that cannot be safely transpiled by esbuild. See [esbuild docs](https://esbuild.github.io/content-types/#javascript) for more details. +Note the build will output a warning if the code contains features that cannot be safely transpiled by Oxc. See [Oxc docs](https://oxc.rs/docs/guide/usage/transformer/lowering#warnings) for more details. ## build.modulePreload @@ -134,6 +134,12 @@ In this case, you need to set `build.cssTarget` to `chrome61` to prevent vite fr This option allows users to override CSS minification specifically instead of defaulting to `build.minify`, so you can configure minification for JS and CSS separately. Vite uses [Lightning CSS](https://lightningcss.dev/minification.html) by default to minify CSS. It can be configured using [`css.lightningcss`](./shared-options.md#css-lightningcss). Set the option to `'esbuild'` to use esbuild instead. +esbuild must be installed when it is set to `'esbuild'`. + +```sh +npm add -D esbuild +``` + ## build.sourcemap - **Type:** `boolean | 'inline' | 'hidden'` @@ -141,17 +147,20 @@ This option allows users to override CSS minification specifically instead of de Generate production source maps. If `true`, a separate sourcemap file will be created. If `'inline'`, the sourcemap will be appended to the resulting output file as a data URI. `'hidden'` works like `true` except that the corresponding sourcemap comments in the bundled files are suppressed. -## build.rollupOptions +## build.rolldownOptions + +- **Type:** [`RolldownOptions`](https://rollupjs.org/configuration-options/) -- **Type:** [`RollupOptions`](https://rollupjs.org/configuration-options/) + -Directly customize the underlying Rollup bundle. This is the same as options that can be exported from a Rollup config file and will be merged with Vite's internal Rollup options. See [Rollup options docs](https://rollupjs.org/configuration-options/) for more details. +Directly customize the underlying Rolldown bundle. This is the same as options that can be exported from a Rolldown config file and will be merged with Vite's internal Rolldown options. See [Rolldown options docs](https://rollupjs.org/configuration-options/) for more details. -## build.commonjsOptions +## build.rollupOptions -- **Type:** [`RollupCommonJSOptions`](https://github.com/rollup/plugins/tree/master/packages/commonjs#options) +- **Type:** `RolldownOptions` +- **Deprecated** -Options to pass on to [@rollup/plugin-commonjs](https://github.com/rollup/plugins/tree/master/packages/commonjs). +This option is an alias of `build.rolldownOptions` option. Use `build.rolldownOptions` option instead. ## build.dynamicImportVarsOptions @@ -160,6 +169,8 @@ Options to pass on to [@rollup/plugin-commonjs](https://github.com/rollup/plugin Options to pass on to [@rollup/plugin-dynamic-import-vars](https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars). + + ## build.lib - **Type:** `{ entry: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string), cssFileName?: string }` @@ -317,6 +328,8 @@ Limit for chunk size warnings (in kB). It is compared against the uncompressed c ## build.watch + + - **Type:** [`WatcherOptions`](https://rollupjs.org/configuration-options/#watch)`| null` - **Default:** `null` diff --git a/docs/config/index.md b/docs/config/index.md index 71f7bdbd04f04f..1732131654b683 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -23,7 +23,7 @@ vite --config my-config.js ``` ::: tip CONFIG LOADING -By default, Vite uses `esbuild` to bundle the config into a temporary file and load it. This may cause issues when importing TypeScript files in a monorepo. If you encounter any issues with this approach, you can specify `--configLoader runner` to use the [module runner](/guide/api-environment-runtimes.html#modulerunner) instead, which will not create a temporary config and will transform any files on the fly. Note that module runner doesn't support CJS in config files, but external CJS packages should work as usual. +By default, Vite uses [Rolldown](https://rolldown.rs/) to bundle the config into a temporary file and load it. This may cause issues when importing TypeScript files in a monorepo. If you encounter any issues with this approach, you can specify `--configLoader runner` to use the [module runner](/guide/api-environment-runtimes.html#modulerunner) instead, which will not create a temporary config and will transform any files on the fly. Note that module runner doesn't support CJS in config files, but external CJS packages should work as usual. Alternatively, if you're using an environment that supports TypeScript (e.g. `node --experimental-strip-types`), or if you're only writing plain JavaScript, you can specify `--configLoader native` to use the environment's native runtime to load the config file. Note that updates to modules imported by the config file are not detected and hence would not auto-restart the Vite server. ::: diff --git a/docs/config/shared-options.md b/docs/config/shared-options.md index 00b2b9346e6d8f..23e0808fc3b62c 100644 --- a/docs/config/shared-options.md +++ b/docs/config/shared-options.md @@ -40,7 +40,7 @@ See [Env Variables and Modes](/guide/env-and-mode) for more details. Define global constant replacements. Entries will be defined as globals during dev and statically replaced during build. -Vite uses [esbuild defines](https://esbuild.github.io/api/#define) to perform replacements, so value expressions must be a string that contains a JSON-serializable value (null, boolean, number, string, array, or object) or a single identifier. For non-string values, Vite will automatically convert it to a string with `JSON.stringify`. +Vite uses [Oxc's define feature](https://oxc.rs/docs/guide/usage/transformer/global-variable-replacement#define) to perform replacements, so value expressions must be a string that contains a JSON-serializable value (null, boolean, number, string, array, or object) or a single identifier. For non-string values, Vite will automatically convert it to a string with `JSON.stringify`. **Example:** @@ -96,6 +96,8 @@ Directory to save cache files. Files in this directory are pre-bundled deps or s Will be passed to `@rollup/plugin-alias` as its [entries option](https://github.com/rollup/plugins/tree/master/packages/alias#entries). Can either be an object, or an array of `{ find, replacement, customResolver }` pairs. + + When aliasing to file system paths, always use absolute paths. Relative alias values will be used as-is and will not be resolved into file system paths. More advanced custom resolution can be achieved through [plugins](/guide/api-plugin). diff --git a/docs/config/worker-options.md b/docs/config/worker-options.md index 91edfe173a2e60..dc257c2b7913e3 100644 --- a/docs/config/worker-options.md +++ b/docs/config/worker-options.md @@ -18,6 +18,15 @@ The function should return new plugin instances as they are used in parallel rol ## worker.rollupOptions -- **Type:** [`RollupOptions`](https://rollupjs.org/configuration-options/) + + +- **Type:** [`RolldownOptions`](https://rollupjs.org/configuration-options/) Rollup options to build worker bundle. + +## worker.rollupOptions + +- **Type:** `RolldownOptions` +- **Deprecated** + +This option is an alias of `worker.rolldownOptions` option. Use `build.rolldownOptions` option instead. diff --git a/docs/guide/api-javascript.md b/docs/guide/api-javascript.md index 3816a30727c4cb..a3a87f9e3dd26f 100644 --- a/docs/guide/api-javascript.md +++ b/docs/guide/api-javascript.md @@ -389,6 +389,21 @@ function normalizePath(id: string): string Normalizes a path to interoperate between Vite plugins. +## `transformWithOxc` + +**Type Signature:** + +```ts +async function transformWithOxc( + code: string, + filename: string, + options?: OxcTransformOptions, + inMap?: object, +): Promise & { warnings: string[] }> +``` + +Transform JavaScript or TypeScript with [Oxc Transformer](https://oxc.rs/docs/guide/usage/transformer). Useful for plugins that prefer matching Vite's internal Oxc Transformer transform. + ## `transformWithEsbuild` **Type Signature:** @@ -402,6 +417,8 @@ async function transformWithEsbuild( ): Promise ``` +**Deprecated:** Use `transformWithOxc` instead. + Transform JavaScript or TypeScript with esbuild. Useful for plugins that prefer matching Vite's internal esbuild transform. ## `loadConfigFromFile` diff --git a/docs/guide/api-plugin.md b/docs/guide/api-plugin.md index d6f797034cd556..e3715749188854 100644 --- a/docs/guide/api-plugin.md +++ b/docs/guide/api-plugin.md @@ -4,6 +4,8 @@ Vite plugins extends Rollup's well-designed plugin interface with a few extra Vi **It is recommended to go through [Rollup's plugin documentation](https://rollupjs.org/plugin-development/) first before reading the sections below.** + + ## Authoring a Plugin Vite strives to offer established patterns out of the box, so before creating a new plugin make sure that you check the [Features guide](/guide/features) to see if your need is covered. Also review available community plugins, both in the form of a [compatible Rollup plugin](https://github.com/rollup/awesome) and [Vite Specific plugins](https://github.com/vitejs/awesome-vite#plugins) diff --git a/docs/guide/build.md b/docs/guide/build.md index 03fbf6494c0fef..a71ee013680613 100644 --- a/docs/guide/build.md +++ b/docs/guide/build.md @@ -50,23 +50,25 @@ If you don't know the base path in advance, you may set a relative base path wit ## Customizing the Build -The build can be customized via various [build config options](/config/build-options.md). Specifically, you can directly adjust the underlying [Rollup options](https://rollupjs.org/configuration-options/) via `build.rollupOptions`: +The build can be customized via various [build config options](/config/build-options.md). Specifically, you can directly adjust the underlying [Rolldown options](https://rollupjs.org/configuration-options/) via `build.rolldownOptions`: + + ```js [vite.config.js] export default defineConfig({ build: { - rollupOptions: { + rolldownOptions: { // https://rollupjs.org/configuration-options/ }, }, }) ``` -For example, you can specify multiple Rollup outputs with plugins that are only applied during build. +For example, you can specify multiple Rolldown outputs with plugins that are only applied during build. ## Chunking Strategy -You can configure how chunks are split using `build.rollupOptions.output.manualChunks` (see [Rollup docs](https://rollupjs.org/configuration-options/#output-manualchunks)). If you use a framework, refer to their documentation for configuring how chunks are split. +You can configure how chunks are split using `build.rolldownOptions.output.advancedChunks` (see [Rolldown docs](https://rolldown.rs/in-depth/advanced-chunks)). If you use a framework, refer to their documentation for configuring how chunks are split. ## Load Error Handling @@ -84,6 +86,8 @@ When a new deployment occurs, the hosting service may delete the assets from pre 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`: + + ```js [vite.config.js] export default defineConfig({ build: { @@ -123,7 +127,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url)) export default defineConfig({ build: { - rollupOptions: { + rolldownOptions: { input: { main: resolve(__dirname, 'index.html'), nested: resolve(__dirname, 'nested/index.html'), @@ -135,7 +139,7 @@ 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. +Note that for HTML files, Vite ignores the name given to the entry in the `rolldownOptions.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 @@ -160,7 +164,7 @@ export default defineConfig({ // the proper extensions will be added fileName: 'my-lib', }, - rollupOptions: { + rolldownOptions: { // make sure to externalize deps that shouldn't be bundled // into your library external: ['vue'], @@ -306,7 +310,7 @@ In library mode, all [`import.meta.env.*`](./env-and-mode.md) usage are statical ::: ::: warning Advanced Usage -Library mode includes a simple and opinionated configuration for browser-oriented and JS framework libraries. If you are building non-browser libraries, or require advanced build flows, you can use [Rollup](https://rollupjs.org) or [esbuild](https://esbuild.github.io) directly. +Library mode includes a simple and opinionated configuration for browser-oriented and JS framework libraries. If you are building non-browser libraries, or require advanced build flows, you can use [tsdown](https://tsdown.dev/) or [Rolldown](https://rolldown.rs/) directly. ::: ## Advanced Base Options diff --git a/docs/guide/cli.md b/docs/guide/cli.md index a65b672fb4050e..7b6a2eefc6b7a3 100644 --- a/docs/guide/cli.md +++ b/docs/guide/cli.md @@ -14,25 +14,25 @@ vite [root] #### Options -| Options | | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `--host [host]` | Specify hostname (`string`) | -| `--port ` | Specify port (`number`) | -| `--open [path]` | Open browser on startup (`boolean \| string`) | -| `--cors` | Enable CORS (`boolean`) | -| `--strictPort` | Exit if specified port is already in use (`boolean`) | -| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | -| `-c, --config ` | Use specified config file (`string`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `-l, --logLevel ` | info \| warn \| error \| silent (`string`) | -| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | -| `--configLoader ` | Use `bundle` to bundle the config with esbuild, or `runner` (experimental) to process it on the fly, or `native` (experimental) to load using the native runtime (default: `bundle`) | -| `--profile` | Start built-in Node.js inspector (check [Performance bottlenecks](/guide/troubleshooting#performance-bottlenecks)) | -| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | -| `-f, --filter ` | Filter debug logs (`string`) | -| `-m, --mode ` | Set env mode (`string`) | -| `-h, --help` | Display available CLI options | -| `-v, --version` | Display version number | +| Options | | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--host [host]` | Specify hostname (`string`) | +| `--port ` | Specify port (`number`) | +| `--open [path]` | Open browser on startup (`boolean \| string`) | +| `--cors` | Enable CORS (`boolean`) | +| `--strictPort` | Exit if specified port is already in use (`boolean`) | +| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | +| `-c, --config ` | Use specified config file (`string`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `-l, --logLevel ` | info \| warn \| error \| silent (`string`) | +| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | +| `--configLoader ` | Use `bundle` to bundle the config with Rolldown, or `runner` (experimental) to process it on the fly, or `native` (experimental) to load using the native runtime (default: `bundle`) | +| `--profile` | Start built-in Node.js inspector (check [Performance bottlenecks](/guide/troubleshooting#performance-bottlenecks)) | +| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | +| `-f, --filter ` | Filter debug logs (`string`) | +| `-m, --mode ` | Set env mode (`string`) | +| `-h, --help` | Display available CLI options | +| `-v, --version` | Display version number | ## Build @@ -48,30 +48,30 @@ vite build [root] #### Options -| Options | | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `--target ` | Transpile target (default: `"modules"`) (`string`) | -| `--outDir ` | Output directory (default: `dist`) (`string`) | -| `--assetsDir ` | Directory under outDir to place assets in (default: `"assets"`) (`string`) | -| `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | -| `--ssr [entry]` | Build specified entry for server-side rendering (`string`) | -| `--sourcemap [output]` | Output source maps for build (default: `false`) (`boolean \| "inline" \| "hidden"`) | -| `--minify [minifier]` | Enable/disable minification, or specify minifier to use (default: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) | -| `--manifest [name]` | Emit build manifest json (`boolean \| string`) | -| `--ssrManifest [name]` | Emit ssr manifest json (`boolean \| string`) | -| `--emptyOutDir` | Force empty outDir when it's outside of root (`boolean`) | -| `-w, --watch` | Rebuilds when modules have changed on disk (`boolean`) | -| `-c, --config ` | Use specified config file (`string`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | -| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | -| `--configLoader ` | Use `bundle` to bundle the config with esbuild or `runner` (experimental) to process it on the fly (default: `bundle`) | -| `--profile` | Start built-in Node.js inspector (check [Performance bottlenecks](/guide/troubleshooting#performance-bottlenecks)) | -| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | -| `-f, --filter ` | Filter debug logs (`string`) | -| `-m, --mode ` | Set env mode (`string`) | -| `-h, --help` | Display available CLI options | -| `--app` | Build all environments, same as `builder: {}` (`boolean`, experimental) | +| Options | | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `--target ` | Transpile target (default: `"modules"`) (`string`) | +| `--outDir ` | Output directory (default: `dist`) (`string`) | +| `--assetsDir ` | Directory under outDir to place assets in (default: `"assets"`) (`string`) | +| `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | +| `--ssr [entry]` | Build specified entry for server-side rendering (`string`) | +| `--sourcemap [output]` | Output source maps for build (default: `false`) (`boolean \| "inline" \| "hidden"`) | +| `--minify [minifier]` | Enable/disable minification, or specify minifier to use (default: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) | +| `--manifest [name]` | Emit build manifest json (`boolean \| string`) | +| `--ssrManifest [name]` | Emit ssr manifest json (`boolean \| string`) | +| `--emptyOutDir` | Force empty outDir when it's outside of root (`boolean`) | +| `-w, --watch` | Rebuilds when modules have changed on disk (`boolean`) | +| `-c, --config ` | Use specified config file (`string`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | +| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | +| `--configLoader ` | Use `bundle` to bundle the config with Rolldown or `runner` (experimental) to process it on the fly (default: `bundle`) | +| `--profile` | Start built-in Node.js inspector (check [Performance bottlenecks](/guide/troubleshooting#performance-bottlenecks)) | +| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | +| `-f, --filter ` | Filter debug logs (`string`) | +| `-m, --mode ` | Set env mode (`string`) | +| `-h, --help` | Display available CLI options | +| `--app` | Build all environments, same as `builder: {}` (`boolean`, experimental) | ## Others @@ -89,18 +89,18 @@ vite optimize [root] #### Options -| Options | | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | -| `-c, --config ` | Use specified config file (`string`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | -| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | -| `--configLoader ` | Use `bundle` to bundle the config with esbuild or `runner` (experimental) to process it on the fly (default: `bundle`) | -| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | -| `-f, --filter ` | Filter debug logs (`string`) | -| `-m, --mode ` | Set env mode (`string`) | -| `-h, --help` | Display available CLI options | +| Options | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | +| `-c, --config ` | Use specified config file (`string`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | +| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | +| `--configLoader ` | Use `bundle` to bundle the config with Rolldown or `runner` (experimental) to process it on the fly (default: `bundle`) | +| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | +| `-f, --filter ` | Filter debug logs (`string`) | +| `-m, --mode ` | Set env mode (`string`) | +| `-h, --help` | Display available CLI options | ### `vite preview` @@ -116,19 +116,19 @@ vite preview [root] #### Options -| Options | | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `--host [host]` | Specify hostname (`string`) | -| `--port ` | Specify port (`number`) | -| `--strictPort` | Exit if specified port is already in use (`boolean`) | -| `--open [path]` | Open browser on startup (`boolean \| string`) | -| `--outDir ` | Output directory (default: `dist`)(`string`) | -| `-c, --config ` | Use specified config file (`string`) | -| `--base ` | Public base path (default: `/`) (`string`) | -| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | -| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | -| `--configLoader ` | Use `bundle` to bundle the config with esbuild or `runner` (experimental) to process it on the fly (default: `bundle`) | -| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | -| `-f, --filter ` | Filter debug logs (`string`) | -| `-m, --mode ` | Set env mode (`string`) | -| `-h, --help` | Display available CLI options | +| Options | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--host [host]` | Specify hostname (`string`) | +| `--port ` | Specify port (`number`) | +| `--strictPort` | Exit if specified port is already in use (`boolean`) | +| `--open [path]` | Open browser on startup (`boolean \| string`) | +| `--outDir ` | Output directory (default: `dist`)(`string`) | +| `-c, --config ` | Use specified config file (`string`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `-l, --logLevel ` | Info \| warn \| error \| silent (`string`) | +| `--clearScreen` | Allow/disable clear screen when logging (`boolean`) | +| `--configLoader ` | Use `bundle` to bundle the config with Rolldown or `runner` (experimental) to process it on the fly (default: `bundle`) | +| `-d, --debug [feat]` | Show debug logs (`string \| boolean`) | +| `-f, --filter ` | Filter debug logs (`string`) | +| `-m, --mode ` | Set env mode (`string`) | +| `-h, --help` | Display available CLI options | diff --git a/docs/guide/dep-pre-bundling.md b/docs/guide/dep-pre-bundling.md index 4a76d2a70402e6..ce5dac206125d6 100644 --- a/docs/guide/dep-pre-bundling.md +++ b/docs/guide/dep-pre-bundling.md @@ -22,12 +22,12 @@ This is Vite performing what we call "dependency pre-bundling". This process ser By pre-bundling `lodash-es` into a single module, we now only need one HTTP request instead! ::: tip NOTE -Dependency pre-bundling only applies in development mode, and uses `esbuild` to convert dependencies to ESM. In production builds, `@rollup/plugin-commonjs` is used instead. +Dependency pre-bundling only applies in development mode. ::: ## Automatic Dependency Discovery -If an existing cache is not found, Vite will crawl your source code and automatically discover dependency imports (i.e. "bare imports" that expect to be resolved from `node_modules`) and use these found imports as entry points for the pre-bundle. The pre-bundling is performed with `esbuild` so it's typically very fast. +If an existing cache is not found, Vite will crawl your source code and automatically discover dependency imports (i.e. "bare imports" that expect to be resolved from `node_modules`) and use these found imports as entry points for the pre-bundle. The pre-bundling is performed with [Rolldown](https://rolldown.rs/) so it's typically very fast. After the server has already started, if a new dependency import is encountered that isn't already in the cache, Vite will re-run the dep bundling process and reload the page if needed. @@ -35,7 +35,7 @@ After the server has already started, if a new dependency import is encountered In a monorepo setup, a dependency may be a linked package from the same repo. Vite automatically detects dependencies that are not resolved from `node_modules` and treats the linked dep as source code. It will not attempt to bundle the linked dep, and will analyze the linked dep's dependency list instead. -However, this requires the linked dep to be exported as ESM. If not, you can add the dependency to [`optimizeDeps.include`](/config/dep-optimization-options.md#optimizedeps-include) and [`build.commonjsOptions.include`](/config/build-options.md#build-commonjsoptions) in your config. +However, this requires the linked dep to be exported as ESM. If not, you can add the dependency to [`optimizeDeps.include`](/config/dep-optimization-options.md#optimizedeps-include) in your config. ```js twoslash [vite.config.js] import { defineConfig } from 'vite' @@ -44,11 +44,6 @@ export default defineConfig({ optimizeDeps: { include: ['linked-dep'], }, - build: { - commonjsOptions: { - include: [/linked-dep/, /node_modules/], - }, - }, }) ``` @@ -62,7 +57,9 @@ A typical use case for `optimizeDeps.include` or `optimizeDeps.exclude` is when Both `include` and `exclude` can be used to deal with this. If the dependency is large (with many internal modules) or is CommonJS, then you should include it; If the dependency is small and is already valid ESM, you can exclude it and let the browser load it directly. -You can further customize esbuild too with the [`optimizeDeps.esbuildOptions` option](/config/dep-optimization-options.md#optimizedeps-esbuildoptions). For example, adding an esbuild plugin to handle special files in dependencies or changing the [build `target`](https://esbuild.github.io/api/#target). +You can further customize esbuild too with the [`optimizeDeps.rolldownOptions` option](/config/dep-optimization-options.md#optimizedeps-rolldownoptions). For example, adding an Rolldown plugin to handle special files in dependencies or changing the [build `target`](https://esbuild.github.io/api/#target). + + ## Caching diff --git a/docs/guide/features.md b/docs/guide/features.md index c7caead35756f7..f3419083fbcae5 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -94,6 +94,14 @@ If `target` in `tsconfig.json` is not `ESNext` or `ES2022` or newer, or if there As such, it is recommended to set `target` to `ESNext` or `ES2022` or newer, or set `useDefineForClassFields` to `true` explicitly when configuring `tsconfig.json`. ::: +#### `paths` + +- [TypeScript documentation](https://www.typescriptlang.org/tsconfig/#paths) + +`resolve.tsconfigPaths: true` can be specified to tell Vite to use the `paths` option in `tsconfig.json` to resolve imports. + +Note that this feature has a performance cost and is [discouraged by the TypeScript team to use this option to change the behavior of the external tools](https://www.typescriptlang.org/tsconfig/#paths:~:text=Note%20that%20this%20feature%20does%20not%20change%20how%20import%20paths%20are%20emitted%20by%20tsc%2C%20so%20paths%20should%20only%20be%20used%20to%20inform%20TypeScript%20that%20another%20tool%20has%20this%20mapping%20and%20will%20use%20it%20at%20runtime%20or%20when%20bundling.). + #### Other Compiler Options Affecting the Build Result - [`extends`](https://www.typescriptlang.org/tsconfig#extends) diff --git a/docs/guide/migration.md b/docs/guide/migration.md index c2c2d36932bd1f..d0453de9acafa4 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -12,7 +12,7 @@ This section will be moved to the release post before the stable release. Vite 8 now has built-in tsconfig `paths` support, thanks to [Oxc Resolver](https://oxc.rs/docs/guide/usage/resolver). This is not enabled by default, because it has a performance cost and is [discouraged by the TypeScript team to use this option to change the behavior of the external tools](https://www.typescriptlang.org/tsconfig/#paths:~:text=Note%20that%20this%20feature%20does%20not%20change%20how%20import%20paths%20are%20emitted%20by%20tsc%2C%20so%20paths%20should%20only%20be%20used%20to%20inform%20TypeScript%20that%20another%20tool%20has%20this%20mapping%20and%20will%20use%20it%20at%20runtime%20or%20when%20bundling.). While having that caveat, you can enable it by setting `resolve.tsconfigPaths` to `true`. -**_[TODO: fix before stable release] currently this feature only supports basic cases. If the tsconfig.json uses references/include/exclude, it won't work as expected._** +The tsconfig.json in the closest parent directory will be used. For more details about what tsconfig.json is used, see [the Features page](/guide/features#typescript-compiler-options). ### `emitDecoratorMetadata` Support @@ -22,7 +22,7 @@ Note that this transformation has some limitations as the full support requires ## Default Browser Target change -**_TODO: implement this change later_** +**_TODO: This change is not implemented yet, but will be implemented before stable release._** The default browser value of `build.target`, `'baseline-widely-available'`, is updated to a newer browser. @@ -281,6 +281,29 @@ See Rolldown's document about this problem for more details: [Ambiguous `default This change may break some existing code importing CJS modules. You can use the `legacy.inconsistentCjsInterop: true` option to temporary restore the previous behavior. Note that this option will be removed in the future. If you find a package that is affected by this change, please report it to the package author. Make sure to link to the Rolldown document above so that the author can understand the context. +### Module Type Support and Auto Detection + +This change only affects plugin authors. + +Rolldown has an experimental [Module type support](https://rolldown.rs/guide/notable-features#module-types), which is similar to [esbuild's `loader` option](https://esbuild.github.io/api/#loader). Due to this, Rolldown automatically sets a module type based on the extension of the resolved id. + +If you are converting the content to JavaScript from other types in `load` or `transform` hooks, you may need to add `moduleType: 'js'` to the returned value. + +```js +const plugin = { + name: 'txt-loader', + load(id) { + if (id.endsWith('.txt')) { + const content = fs.readFile(id, 'utf-8') + return { + code: `export default ${JSON.stringify(content)}`, + moduleType: 'js', // [!code ++] + } + } + }, +} +``` + ### Removed Module Resolution Using Format Sniffing When both `browser` and `module` fields are present in `package.json`, Vite used to resolve the field based on the content of the file, trying to pick the ESM file for browsers. This was introduced because some packages were using the `module` field to point to ESM files for Node.js and some other packages were using the `browser` field to point to UMD files for browsers. Given that the modern `exports` field solved this problem and is now adopted by many packages, Vite no longer uses this heuristic and always respects the order of the [`resolve.mainFields`](/config/shared-options#resolve-mainfields) option. If you were relying on this behavior, you can use the [`resolve.alias`](/config/shared-options#resolve-alias) option to map the field to the desired file or apply a patch with your package manager (e.g. `patch-package`, `pnpm patch`). @@ -328,33 +351,33 @@ The following options are deprecated and will be removed in the future: - `build.rollupOptions`: renamed to `build.rolldownOptions` - `worker.rollupOptions`: renamed to `worker.rolldownOptions` +- `build.commonjsOptions`: it is now no-op ## General Changes ## Removed deprecated features -**_TODO: implement these changes later_** +**_TODO: This change is not implemented yet, but will be implemented before stable release._** ## Advanced There are other breaking changes which only affect few users. -- **[TODO: fix before stable release (better if it's fixed before first beta)]** https://github.com/rolldown/rolldown/issues/5867 -- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/5726 (affects nuxt, qwik) -- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/3403 (affects sveltekit) -- **[TODO: fix before stable release]** Legacy chunks are emitted as an asset file instead of a chunk file due to the lack of prebuilt chunk emit feature ([rolldown#4304](https://github.com/rolldown/rolldown/issues/4034)). This means the chunk related options does not apply to legacy chunks and the manifest file will not include legacy chunks as a chunk file. -- **[TODO: fix before stable release]** resolver cache breaks minor cases in Vitest ([rolldown-vite#466](https://github.com/vitejs/rolldown-vite/issues/466), [vitest#8754](https://github.com/vitest-dev/vitest/issues/8754#issuecomment-3441115032)) -- **[TODO: fix before stable release]** The resolver does not work with yarn pnp ([rolldown-vite#324](https://github.com/vitejs/rolldown-vite/issues/324), [rolldown-vite#392](https://github.com/vitejs/rolldown-vite/issues/392)) -- **[TODO: fix before stable release]** native plugin ordering issue ([rolldown-vite#373](https://github.com/vitejs/rolldown-vite/issues/373)) -- **[TODO: fix before stable release]** `@vite-ignore` comment edge case ([rolldown-vite#426](https://github.com/vitejs/rolldown-vite/issues/426)) -- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/3403 -- **[TODO: clarify this here a bit more]** ext glob support ([rolldown-vite#365](https://github.com/vitejs/rolldown-vite/issues/365)) +- **[TODO: this will be fixed before stable release]** https://github.com/rolldown/rolldown/issues/5726 (affects nuxt, qwik) +- **[TODO: this will be fixed before stable release]** https://github.com/rolldown/rolldown/issues/3403 (affects sveltekit) +- **[TODO: this will be fixed before stable release]** Legacy chunks are emitted as an asset file instead of a chunk file due to the lack of prebuilt chunk emit feature ([rolldown#4304](https://github.com/rolldown/rolldown/issues/4034)). This means the chunk related options does not apply to legacy chunks and the manifest file will not include legacy chunks as a chunk file. +- **[TODO: this will be fixed before stable release]** resolver cache breaks minor cases in Vitest ([rolldown-vite#466](https://github.com/vitejs/rolldown-vite/issues/466), [vitest#8754](https://github.com/vitest-dev/vitest/issues/8754#issuecomment-3441115032)) +- **[TODO: this will be fixed before stable release]** The resolver does not work with yarn pnp ([rolldown-vite#324](https://github.com/vitejs/rolldown-vite/issues/324), [rolldown-vite#392](https://github.com/vitejs/rolldown-vite/issues/392)) +- **[TODO: this will be fixed before stable release]** native plugin ordering issue ([rolldown-vite#373](https://github.com/vitejs/rolldown-vite/issues/373)) +- **[TODO: this will be fixed before stable release]** `@vite-ignore` comment edge case ([rolldown-vite#426](https://github.com/vitejs/rolldown-vite/issues/426)) +- **[TODO: this will be fixed before stable release]** https://github.com/rolldown/rolldown/issues/3403 +- [Extglobs](https://github.com/micromatch/picomatch/blob/master/README.md#extglobs) are not supported yet ([rolldown-vite#365](https://github.com/vitejs/rolldown-vite/issues/365)) - `define` does not share reference for objects: When you pass an object as a value to `define`, each variable will have a separate copy of the object. See [Oxc Transformer document](https://oxc.rs/docs/guide/usage/transformer/global-variable-replacement#define) for more details. - `bundle` object changes (`bundle` is an object passed in `generateBundle` / `writeBundle` hooks, returned by `build` function): - Assigning to `bundle[foo]` is not supported. This is discouraged by Rollup as well. Please use `this.emitFile()` instead. - the reference is not shared across the hooks ([rolldown-vite#410](https://github.com/vitejs/rolldown-vite/issues/410)) - `structuredClone(bundle)` errors with `DataCloneError: # could not be cloned`. This is not supported anymore. Please clone it with `structuredClone({ ...bundle })`. ([rolldown-vite#128](https://github.com/vitejs/rolldown-vite/issues/128)) -- **[TODO: clarify this in Rolldown's docs and link it from here]** All parallel hooks in Rollup works as sequential hooks. +- All parallel hooks in Rollup works as sequential hooks. See [Rolldown's documentation](https://rolldown.rs/apis/plugin-api#sequential-hook-execution) for more details. - `"use strict";` is not injected sometimes. See [Rolldown's documentation](https://rolldown.rs/in-depth/directives) for more details. - Transforming to lower than ES5 with plugin-legacy is not supported ([rolldown-vite#452](https://github.com/vitejs/rolldown-vite/issues/452)) - Passing the same browser with multiple versions of it to `build.target` option now errors: esbuild selects the latest version of it, which was probably not what you intended. diff --git a/docs/guide/philosophy.md b/docs/guide/philosophy.md index fd2b8668c37661..15b091c75baccf 100644 --- a/docs/guide/philosophy.md +++ b/docs/guide/philosophy.md @@ -16,7 +16,7 @@ When adding new features, these patterns are followed to create a future-proof A ## A Pragmatic Approach to Performance -Vite has been focused on performance since its [origins](./why.md). Its dev server architecture allows HMR that stays fast as projects scale. Vite uses native tools like [esbuild](https://esbuild.github.io/) and [SWC](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react-swc) to implement intensive tasks but keeps the rest of the code in JS to balance speed with flexibility. When needed, framework plugins will tap into [Babel](https://babeljs.io/) to compile user code. And during build time Vite currently uses [Rollup](https://rollupjs.org/) where bundling size and having access to a wide ecosystem of plugins are more important than raw speed. Vite will continue to evolve internally, using new libraries as they appear to improve DX while keeping its API stable. +Vite has been focused on performance since its [origins](./why.md). Its dev server architecture allows HMR that stays fast as projects scale. Vite is based on native tools that includes [Oxc toolchain](https://oxc.rs/) and [Rolldown](https://rolldown.rs/) to implement intensive tasks but keeps the rest of the code in JS to balance speed with flexibility. When needed, framework plugins will tap into [Babel](https://babeljs.io/) to compile user code. Thanks to Rolldown's Rollup plugin compatibility, Vite has access to a wide ecosystem of plugins. ## Building Frameworks on Top of Vite diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index d8fc7c27645ada..d83b2f514609c2 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -187,7 +187,7 @@ Note that you cannot retry the dynamic import due to browser limitations ([whatw The error may also occur if the browser extensions (like ad-blockers) are blocking that request. -It might be possible to work around by selecting a different chunk name by [`build.rollupOptions.output.chunkFileNames`](../config/build-options.md#build-rollupoptions), as these extensions often block requests based on file names (e.g. names containing `ad`, `track`). +It might be possible to work around by selecting a different chunk name by [`build.rolldownOptions.output.chunkFileNames`](../config/build-options.md#build-rolldownoptions), as these extensions often block requests based on file names (e.g. names containing `ad`, `track`). ## Optimized Dependencies diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 041e91db2a68d7..36f25c00e33e3f 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -18,11 +18,11 @@ Provides Vue 3 JSX support (via [dedicated Babel transform](https://github.com/v ### [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react) -Uses esbuild and Babel, achieving fast HMR with a small package footprint and the flexibility of being able to use the Babel transform pipeline. Without additional Babel plugins, only esbuild is used during builds. +Uses [Oxc Transformer](https://oxc.rs/docs/guide/usage/transformer) and [Babel](https://babeljs.io/), achieving fast HMR with a small package footprint and the flexibility of being able to use the Babel transform pipeline. Without additional Babel plugins, only Oxc Transformer is used. ### [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react-swc) -Replaces Babel with SWC during development. During production builds, SWC+esbuild are used when using plugins, and esbuild only otherwise. For big projects that don't require non-standard React extensions, cold start and Hot Module Replacement (HMR) can be significantly faster. +Replaces Babel with [SWC](https://swc.rs/) during development. During production builds, SWC+Oxc Transformer are used when using plugins, and Oxc Transformer only otherwise. For big projects that requires custom plugins, cold start and Hot Module Replacement (HMR) can be significantly faster, if the plugin is also available for SWC. ### [@vitejs/plugin-rsc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc) @@ -42,6 +42,12 @@ Provides legacy browsers support for the production build. Check out [awesome-vite](https://github.com/vitejs/awesome-vite#plugins) - you can also submit a PR to list your plugins there. +## Rolldown Builtin Plugins + +Vite uses [Rolldown](https://rolldown.rs/) under the hood and it provides a few builtin plugins for common use cases. + +Read the [Rolldown Builtin Plugins section](https://rolldown.rs/builtin-plugins/) for more information. + ## Rollup Plugins [Vite plugins](../guide/api-plugin) are an extension of Rollup's plugin interface. Check out the [Rollup Plugin Compatibility section](../guide/api-plugin#rollup-plugin-compatibility) for more information. diff --git a/docs/releases.md b/docs/releases.md index 83271f97f3f7d1..4491eeaccd1c63 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -43,10 +43,6 @@ We may ship incompatible changes to TypeScript definitions between minor version - 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). diff --git a/packages/vite/src/node/cli.ts b/packages/vite/src/node/cli.ts index b2f95d4f3809d6..bc18f3c91ac6b9 100644 --- a/packages/vite/src/node/cli.ts +++ b/packages/vite/src/node/cli.ts @@ -175,7 +175,7 @@ cli .option('--clearScreen', `[boolean] allow/disable clear screen when logging`) .option( '--configLoader ', - `[string] use 'bundle' to bundle the config with esbuild, or 'runner' (experimental) to process it on the fly, or 'native' (experimental) to load using the native runtime (default: bundle)`, + `[string] use 'bundle' to bundle the config with Rolldown, or 'runner' (experimental) to process it on the fly, or 'native' (experimental) to load using the native runtime (default: bundle)`, ) .option('-d, --debug [feat]', `[string | boolean] show debug logs`) .option('-f, --filter ', `[string] filter debug logs`) diff --git a/packages/vite/src/node/config.ts b/packages/vite/src/node/config.ts index e0a3940a60b2e9..c23f4bd996503c 100644 --- a/packages/vite/src/node/config.ts +++ b/packages/vite/src/node/config.ts @@ -548,8 +548,8 @@ export interface ExperimentalOptions { /** * Enable builtin plugin that written by rust, which is faster than js plugin. * - * - 'resolver': Enable only the native resolver plugin. - * - 'v1': Enable the first stable set of native plugins (including resolver). + * - 'resolver' (deprecated, will be removed in v8 stable): Enable only the native resolver plugin. + * - 'v1' (will be deprecated, will be removed in v8 stable): Enable the first stable set of native plugins (including resolver). * - true: Enable all native plugins (currently an alias of 'v1', it will map to a newer one in the future versions). * * @experimental