docs: migration guide (#469)

Co-authored-by: Alexander Lichter <[email protected]>

Author: sapphi-red

docs/config/build-options.md

@@ -129,10 +129,10 @@ In this case, you need to set `build.cssTarget` to `chrome61` to prevent vite fr
 
 ## build.cssMinify
 
-- **Type:** `boolean | 'esbuild' | 'lightningcss'`
-- **Default:** the same as [`build.minify`](#build-minify) for client, `'esbuild'` for SSR
+- **Type:** `boolean | 'lightningcss' | 'esbuild'`
+- **Default:** the same as [`build.minify`](#build-minify) for client, `'lightningcss'` for SSR
 
-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 `esbuild` by default to minify CSS. Set the option to `'lightningcss'` to use [Lightning CSS](https://lightningcss.dev/minification.html) instead. If selected, it can be configured using [`css.lightningcss`](./shared-options.md#css-lightningcss).
+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.
 
 ## build.sourcemap
 
@@ -277,16 +277,19 @@ During the SSR build, static assets aren't emitted as it is assumed they would b
 
 ## build.minify
 
-- **Type:** `boolean | 'terser' | 'esbuild'`
-- **Default:** `'esbuild'` for client build, `false` for SSR build
+- **Type:** `boolean | 'oxc' | 'terser' | 'esbuild'`
+- **Default:** `'oxc'` for client build, `false` for SSR build
 
-Set to `false` to disable minification, or specify the minifier to use. The default is [esbuild](https://github.com/evanw/esbuild) which is 20 ~ 40x faster than terser and only 1 ~ 2% worse compression. [Benchmarks](https://github.com/privatenumber/minification-benchmarks)
+Set to `false` to disable minification, or specify the minifier to use. The default is [Oxc Minifier](https://oxc.rs/docs/guide/usage/minifier) which is 30 ~ 90x faster than terser and only 0.5 ~ 2% worse compression. [Benchmarks](https://github.com/privatenumber/minification-benchmarks)
+
+`build.minify: 'esbuild'` is deprecated and will be removed in the future.
 
 Note the `build.minify` option does not minify whitespaces when using the `'es'` format in lib mode, as it removes pure annotations and breaks tree-shaking.
 
-Terser must be installed when it is set to `'terser'`.
+esbuild or Terser must be installed when it is set to `'esbuild'` or `'terser'` respectively.
 
 ```sh
+npm add -D esbuild
 npm add -D terser
 ```
 

docs/config/dep-optimization-options.md

@@ -51,6 +51,23 @@ export default defineConfig({
 })
 ```
 
+## optimizeDeps.rolldownOptions <NonInheritBadge />
+
+- **Type:** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<``RolldownOptions`, `'input' | 'logLevel' | 'output'> & {
+  output?: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`
+    `RolldownOutputOptions`,
+    `'format' | 'sourcemap' | 'dir' | 'banner'>`
+`}`
+
+<!-- TODO: add link to RolldownOptions -->
+<!-- TODO: add link to RolldownOutputOptions -->
+
+Options to pass to Rolldown during the dep scanning and optimization.
+
+Certain options are omitted since changing them would not be compatible with Vite's dep optimization.
+
+- `plugins` are merged with Vite's dep plugin
+
 ## optimizeDeps.esbuildOptions <NonInheritBadge />
 
 - **Type:** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`[`EsbuildBuildOptions`](https://esbuild.github.io/api/#general-options)`,
@@ -64,13 +81,9 @@ export default defineConfig({
 | 'outbase'
 | 'outExtension'
 | 'metafile'>`
+- **Deprecated**
 
-Options to pass to esbuild during the dep scanning and optimization.
-
-Certain options are omitted since changing them would not be compatible with Vite's dep optimization.
-
-- `external` is also omitted, use Vite's `optimizeDeps.exclude` option
-- `plugins` are merged with Vite's dep plugin
+This option is converted to `optimizeDeps.rolldownOptions` internally. Use `optimizeDeps.rolldownOptions` instead.
 
 ## optimizeDeps.force <NonInheritBadge />
 

docs/config/shared-options.md

@@ -353,36 +353,44 @@ If set to `true`, imported JSON will be transformed into `export default JSON.pa
 
 If set to `'auto'`, the data will be stringified only if [the data is bigger than 10kB](https://v8.dev/blog/cost-of-javascript-2019#json:~:text=A%20good%20rule%20of%20thumb%20is%20to%20apply%20this%20technique%20for%20objects%20of%2010%20kB%20or%20larger).
 
-## esbuild
+## oxc
 
-- **Type:** `ESBuildOptions | false`
+- **Type:** `OxcOptions | false`
 
-`ESBuildOptions` extends [esbuild's own transform options](https://esbuild.github.io/api/#transform). The most common use case is customizing JSX:
+`OxcOptions` extends [Oxc Transformer's options](https://oxc.rs/docs/guide/usage/transformer). The most common use case is customizing JSX:
 
 ```js
 export default defineConfig({
-  esbuild: {
-    jsxFactory: 'h',
-    jsxFragment: 'Fragment',
+  oxc: {
+    jsx: {
+      runtime: 'classic',
+      pragma: 'h',
+      pragmaFrag: 'Fragment',
+    },
   },
 })
 ```
 
-By default, esbuild is applied to `ts`, `jsx` and `tsx` files. You can customize this with `esbuild.include` and `esbuild.exclude`, which can be a regex, a [picomatch](https://github.com/micromatch/picomatch#globbing-features) pattern, or an array of either.
+By default, transformation by Oxc is applied to `ts`, `jsx` and `tsx` files. You can customize this with `oxc.include` and `oxc.exclude`, which can be a regex, a [picomatch](https://github.com/micromatch/picomatch#globbing-features) pattern, or an array of either.
 
-In addition, you can also use `esbuild.jsxInject` to automatically inject JSX helper imports for every file transformed by esbuild:
+In addition, you can also use `oxc.jsxInject` to automatically inject JSX helper imports for every file transformed by Oxc:
 
 ```js
 export default defineConfig({
-  esbuild: {
+  oxc: {
     jsxInject: `import React from 'react'`,
   },
 })
 ```
 
-When [`build.minify`](./build-options.md#build-minify) is `true`, all minify optimizations are applied by default. To disable [certain aspects](https://esbuild.github.io/api/#minify) of it, set any of `esbuild.minifyIdentifiers`, `esbuild.minifySyntax`, or `esbuild.minifyWhitespace` options to `false`. Note the `esbuild.minify` option can't be used to override `build.minify`.
+Set to `false` to disable transformation by Oxc.
+
+## esbuild
+
+- **Type:** `ESBuildOptions | false`
+- **Deprecated**
 
-Set to `false` to disable esbuild transforms.
+This option is converted to `oxc` option internally. Use `oxc` option instead.
 
 ## assetsInclude