refactor: make esbuild optional peer dependency

Author: sapphi-red

eslint.config.js

@@ -91,6 +91,7 @@ export default tseslint.config(
         {
           allowModules: [
             'vite',
+            'esbuild',
             'less',
             'sass',
             'sass-embedded',

packages/vite/package.json

@@ -86,7 +86,6 @@
   "//": "READ CONTRIBUTING.md to understand what to put under deps vs. devDeps!",
   "dependencies": {
     "@oxc-project/runtime": "^0.53.0",
-    "esbuild": "^0.25.0",
     "lightningcss": "^1.29.1",
     "postcss": "^8.5.3",
     "rolldown": "1.0.0-beta.3-commit.62fba31"
@@ -120,6 +119,7 @@
     "dotenv": "^16.4.7",
     "dotenv-expand": "^12.0.1",
     "es-module-lexer": "^1.6.0",
+    "esbuild": "^0.25.0",
     "escape-html": "^1.0.3",
     "estree-walker": "^3.0.3",
     "etag": "^1.8.1",
@@ -158,6 +158,7 @@
   },
   "peerDependencies": {
     "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+    "esbuild": "^0.25.0",
     "jiti": ">=1.21.0",
     "less": "*",
     "sass": "*",
@@ -172,6 +173,9 @@
     "@types/node": {
       "optional": true
     },
+    "esbuild": {
+      "optional": true
+    },
     "jiti": {
       "optional": true
     },

packages/vite/rollup.dts.config.ts

@@ -55,13 +55,8 @@ const identifierReplacements: Record<string, Record<string, string>> = {
     TransformResult$1: 'rolldown.TransformResult',
   },
   'rolldown/experimental': {
-    TransformOptions$2: 'rolldown_experimental_TransformOptions',
-    TransformResult$3: 'rolldown_experimental_TransformResult',
-  },
-  esbuild: {
-    TransformResult$2: 'esbuild_TransformResult',
-    TransformOptions$1: 'esbuild_TransformOptions',
-    BuildOptions$1: 'esbuild_BuildOptions',
+    TransformOptions$1: 'rolldown_experimental_TransformOptions',
+    TransformResult$2: 'rolldown_experimental_TransformResult',
   },
   'node:https': {
     Server$1: 'HttpsServer',

packages/vite/src/node/build.ts

@@ -23,7 +23,7 @@ import type {
 } from 'rolldown'
 import type { RollupCommonJSOptions } from 'dep-types/commonjs'
 import type { RollupDynamicImportVarsOptions } from 'dep-types/dynamicImportVars'
-import type { TransformOptions } from 'esbuild'
+import type { EsbuildTarget } from 'types/internal/esbuildOptions'
 import type { ChunkMetadata } from 'types/metadata'
 import { withTrailingSlash } from '../shared/utils'
 import {
@@ -104,7 +104,7 @@ export interface BuildEnvironmentOptions {
    * https://esbuild.github.io/content-types/#javascript for more details.
    * @default 'modules'
    */
-  target?: 'modules' | TransformOptions['target'] | false
+  target?: 'modules' | EsbuildTarget | false
   /**
    * whether to inject module preload polyfill.
    * Note: does not apply to library mode.
@@ -157,7 +157,7 @@ export interface BuildEnvironmentOptions {
    * doesn't support the #RGBA syntax.
    * @default target
    */
-  cssTarget?: TransformOptions['target'] | false
+  cssTarget?: EsbuildTarget | false
   /**
    * Override CSS minification specifically instead of defaulting to `build.minify`,
    * so you can configure minification for JS and CSS separately.

packages/vite/src/node/index.ts

@@ -138,8 +138,7 @@ export type {
   StylusPreprocessorOptions,
 } from './plugins/css'
 export type { JsonOptions } from './plugins/json'
-export type { TransformOptions as EsbuildTransformOptions } from 'esbuild'
-export type { ESBuildOptions, ESBuildTransformResult } from './plugins/esbuild'
+export type { EsbuildTransformOptions } from 'types/internal/esbuildOptions'
 export type { OxcOptions } from './plugins/oxc'
 export type { Manifest, ManifestChunk } from './plugins/manifest'
 export type { ResolveOptions, InternalResolveOptions } from './plugins/resolve'

packages/vite/src/node/optimizer/index.ts

@@ -4,7 +4,7 @@ import path from 'node:path'
 import { promisify } from 'node:util'
 import { performance } from 'node:perf_hooks'
 import colors from 'picocolors'
-import type { BuildOptions as EsbuildBuildOptions } from 'esbuild'
+import type { DepsOptimizerEsbuildOptions } from 'types/internal/esbuildOptions'
 import { init, parse } from 'es-module-lexer'
 import { isDynamicPattern } from 'tinyglobby'
 import {
@@ -96,19 +96,7 @@ export interface DepOptimizationConfig {
    *
    * https://esbuild.github.io/api
    */
-  esbuildOptions?: Omit<
-    EsbuildBuildOptions,
-    | 'bundle'
-    | 'entryPoints'
-    | 'external'
-    | 'write'
-    | 'watch'
-    | 'outdir'
-    | 'outfile'
-    | 'outbase'
-    | 'outExtension'
-    | 'metafile'
-  >
+  esbuildOptions?: DepsOptimizerEsbuildOptions
   rollupOptions?: Omit<RolldownOptions, 'input' | 'logLevel' | 'output'> & {
     output?: Omit<
       RolldownOutputOptions,

packages/vite/src/node/plugins/css.ts

@@ -22,8 +22,6 @@ import type Stylus from 'stylus'
 import type Less from 'less'
 import type { Alias } from 'dep-types/alias'
 import type { LightningCSSOptions } from 'types/internal/lightningcssOptions'
-import type { TransformOptions } from 'esbuild'
-import { formatMessages, transform } from 'esbuild'
 import type { RawSourceMap } from '@ampproject/remapping'
 import { WorkerWithFallback } from 'artichokie'
 import { globSync } from 'tinyglobby'
@@ -37,6 +35,7 @@ import type {
   TransformAttributeResult as LightningCssTransformAttributeResult,
   TransformResult as LightningCssTransformResult,
 } from 'lightningcss'
+import type { EsbuildTransformOptions } from 'types/internal/esbuildOptions'
 import { getCodeWithSourcemap, injectSourcesContent } from '../server/sourcemap'
 import type { EnvironmentModuleNode } from '../server/moduleGraph'
 import {
@@ -2055,6 +2054,7 @@ async function minifyCSS(
   // See https://github.com/vitejs/vite/pull/13893#issuecomment-1678628198
 
   if (config.build.cssMinify === 'esbuild') {
+    const { transform, formatMessages } = await importEsbuild()
     try {
       const { code, warnings } = await transform(css, {
         loader: 'css',
@@ -2125,8 +2125,8 @@ async function minifyCSS(
 
 function resolveMinifyCssEsbuildOptions(
   options: ESBuildOptions,
-): TransformOptions {
-  const base: TransformOptions = {
+): EsbuildTransformOptions {
+  const base: EsbuildTransformOptions = {
     charset: options.charset ?? 'utf8',
     logLevel: options.logLevel,
     logLimit: options.logLimit,
@@ -3319,6 +3319,8 @@ function isPreProcessor(lang: any): lang is PreprocessLang {
   return lang && preprocessorSet.has(lang)
 }
 
+const importEsbuild = createCachedImport(() => import('esbuild'))
+
 const importLightningCSS = createCachedImport(() => import('lightningcss'))
 async function compileLightningCSS(
   id: string,

packages/vite/src/node/plugins/esbuild.ts

@@ -1,12 +1,11 @@
 import path from 'node:path'
 import colors from 'picocolors'
 import type {
-  Loader,
-  Message,
-  TransformOptions,
-  TransformResult,
-} from 'esbuild'
-import { transform } from 'esbuild'
+  EsbuildLoader,
+  EsbuildMessage,
+  EsbuildTransformOptions,
+  EsbuildTransformResult as RawEsbuildTransformResult,
+} from 'types/internal/esbuildOptions'
 import type { RawSourceMap } from '@ampproject/remapping'
 import type { InternalModuleFormat, SourceMap } from 'rolldown'
 import type { TSConfckParseResult } from 'tsconfck'
@@ -43,7 +42,7 @@ export const defaultEsbuildSupported = {
   'import-meta': true,
 }
 
-export interface ESBuildOptions extends TransformOptions {
+export interface ESBuildOptions extends EsbuildTransformOptions {
   include?: string | RegExp | ReadonlyArray<string | RegExp>
   exclude?: string | RegExp | ReadonlyArray<string | RegExp>
   jsxInject?: string
@@ -53,7 +52,7 @@ export interface ESBuildOptions extends TransformOptions {
   minify?: never
 }
 
-export type ESBuildTransformResult = Omit<TransformResult, 'map'> & {
+export type ESBuildTransformResult = Omit<RawEsbuildTransformResult, 'map'> & {
   map: SourceMap
 }
 
@@ -76,10 +75,16 @@ type TSConfigJSON = {
 }
 type TSCompilerOptions = NonNullable<TSConfigJSON['compilerOptions']>
 
+let esbuild: Promise<typeof import('esbuild')> | undefined
+const importEsbuild = () => {
+  esbuild ||= import('esbuild')
+  return esbuild
+}
+
 export async function transformWithEsbuild(
   code: string,
   filename: string,
-  options?: TransformOptions,
+  options?: EsbuildTransformOptions,
   inMap?: object,
   config?: ResolvedConfig,
   watcher?: FSWatcher,
@@ -98,7 +103,7 @@ export async function transformWithEsbuild(
     } else if (ext === 'cts' || ext === 'mts') {
       loader = 'ts'
     } else {
-      loader = ext as Loader
+      loader = ext as EsbuildLoader
     }
   }
 
@@ -179,7 +184,7 @@ export async function transformWithEsbuild(
     }
   }
 
-  const resolvedOptions: TransformOptions = {
+  const resolvedOptions: EsbuildTransformOptions = {
     sourcemap: true,
     // ensure source file name contains full query
     sourcefile: filename,
@@ -198,6 +203,7 @@ export async function transformWithEsbuild(
   delete resolvedOptions.jsxInject
 
   try {
+    const { transform } = await importEsbuild()
     const result = await transform(code, resolvedOptions)
     let map: SourceMap
     if (inMap && resolvedOptions.sourcemap) {
@@ -222,7 +228,7 @@ export async function transformWithEsbuild(
     // patch error information
     if (e.errors) {
       e.frame = ''
-      e.errors.forEach((m: Message) => {
+      e.errors.forEach((m: EsbuildMessage) => {
         if (
           m.text === 'Experimental decorators are not currently enabled' ||
           m.text ===
@@ -247,7 +253,7 @@ export function esbuildPlugin(config: ResolvedConfig): Plugin {
 
   // Remove optimization options for dev as we only need to transpile them,
   // and for build as the final optimization is in `buildEsbuildPlugin`
-  const transformOptions: TransformOptions = {
+  const transformOptions: EsbuildTransformOptions = {
     target: 'esnext',
     charset: 'utf8',
     ...esbuildTransformOptions,
@@ -303,7 +309,7 @@ export function esbuildPlugin(config: ResolvedConfig): Plugin {
 
 const rollupToEsbuildFormatMap: Record<
   string,
-  TransformOptions['format'] | undefined
+  EsbuildTransformOptions['format'] | undefined
 > = {
   es: 'esm',
   cjs: 'cjs',
@@ -381,7 +387,7 @@ export const buildEsbuildPlugin = (): Plugin => {
 export function resolveEsbuildTranspileOptions(
   config: ResolvedConfig,
   format: InternalModuleFormat,
-): TransformOptions | null {
+): EsbuildTransformOptions | null {
   const target = config.build.target
   const minify = config.build.minify === 'esbuild'
 
@@ -395,7 +401,7 @@ export function resolveEsbuildTranspileOptions(
   const isEsLibBuild = config.build.lib && format === 'es'
   const esbuildOptions = config.esbuild || {}
 
-  const options: TransformOptions = {
+  const options: EsbuildTransformOptions = {
     charset: 'utf8',
     ...esbuildOptions,
     loader: 'js',
@@ -467,7 +473,7 @@ export function resolveEsbuildTranspileOptions(
   }
 }
 
-function prettifyMessage(m: Message, code: string): string {
+function prettifyMessage(m: EsbuildMessage, code: string): string {
   let res = colors.yellow(m.text)
   if (m.location) {
     res += `\n` + generateCodeFrame(code, m.location)

packages/vite/src/node/publicUtils.ts

@@ -11,7 +11,8 @@ export {
   DEFAULT_SERVER_MAIN_FIELDS as defaultServerMainFields,
   defaultAllowedOrigins,
 } from './constants'
-export { version as esbuildVersion } from 'esbuild'
+// NOTE: export for backward compat
+export const esbuildVersion = '0.25.0'
 export {
   splitVendorChunkPlugin,
   splitVendorChunk,

packages/vite/types/internal/esbuildOptions.d.ts

@@ -0,0 +1,28 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+
+// @ts-ignore `esbuild` may not be installed
+import type esbuild from 'esbuild'
+
+/* eslint-enable @typescript-eslint/ban-ts-comment */
+
+export type EsbuildTarget = string | string[]
+
+export type EsbuildLoader = esbuild.Loader
+export type EsbuildTransformOptions = esbuild.TransformOptions
+export type EsbuildTransformResult = esbuild.TransformResult
+
+export type EsbuildMessage = esbuild.Message
+
+export type DepsOptimizerEsbuildOptions = Omit<
+  esbuild.BuildOptions,
+  | 'bundle'
+  | 'entryPoints'
+  | 'external'
+  | 'write'
+  | 'watch'
+  | 'outdir'
+  | 'outfile'
+  | 'outbase'
+  | 'outExtension'
+  | 'metafile'
+>