index.ts

import fs from 'fs'
import path from 'path'
import colors from 'picocolors'
import { createHash } from 'crypto'
import type { BuildOptions as EsbuildBuildOptions } from 'esbuild'
import { build } from 'esbuild'
import type { ResolvedConfig } from '../config'
import {
  createDebugger,
  emptyDir,
  lookupFile,
  normalizePath,
  writeFile,
  flattenId,
  normalizeId
} from '../utils'
import { esbuildDepPlugin } from './esbuildDepPlugin'
import { init, parse } from 'es-module-lexer'
import { scanImports } from './scan'
import { transformWithEsbuild } from '../plugins/esbuild'
import { performance } from 'perf_hooks'

const debug = createDebugger('vite:deps')

export type ExportsData = ReturnType<typeof parse> & {
  // es-module-lexer has a facade detection but isn't always accurate for our
  // use case when the module has default export
  hasReExports?: true
}

export interface DepOptimizationOptions {
  /**
   * By default, Vite will crawl your index.html to detect dependencies that
   * need to be pre-bundled. If build.rollupOptions.input is specified, Vite
   * will crawl those entry points instead.
   *
   * If neither of these fit your needs, you can specify custom entries using
   * this option - the value should be a fast-glob pattern or array of patterns
   * (https://github.com/mrmlnc/fast-glob#basic-syntax) that are relative from
   * vite project root. This will overwrite default entries inference.
   */
  entries?: string | string[]
  /**
   * Force optimize listed dependencies (must be resolvable import paths,
   * cannot be globs).
   */
  include?: string[]
  /**
   * Do not optimize these dependencies (must be resolvable import paths,
   * cannot be globs).
   */
  exclude?: string[]
  /**
   * Hold back server start when doing the initial pre-bundling.
   * Default is false. Set to true for testing purposes, or in situations
   * where the pre Vite 2.9 strategy is required
   */
  holdBackServerStart?: boolean
  /**
   * 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
   * - `keepNames` takes precedence over the deprecated `optimizeDeps.keepNames`
   *
   * https://esbuild.github.io/api
   */
  esbuildOptions?: Omit<
    EsbuildBuildOptions,
    | 'bundle'
    | 'entryPoints'
    | 'external'
    | 'write'
    | 'watch'
    | 'outdir'
    | 'outfile'
    | 'outbase'
    | 'outExtension'
    | 'metafile'
  >
  /**
   * @deprecated use `esbuildOptions.keepNames`
   */
  keepNames?: boolean
}

export interface OptimizeDepsResult {
  /**
   * After a re-optimization, the internal bundled chunks may change
   * and a full page reload is required if that is the case
   * If the files are stable, we can avoid the reload that is expensive
   * for large applications
   */
  alteredFiles: boolean
}

export interface OptimizeDepsProcessing {
  promise: Promise<OptimizeDepsResult | undefined>
  resolve: (result?: OptimizeDepsResult) => void
}

export interface OptimizedDepInfo {
  file: string
  src: string
  needsInterop?: boolean
  browserHash?: string
  fileHash?: string
  /**
   * During optimization, ids can still be resolved to their final location
   * but the bundles may not yet be saved to disk
   */
  processing: Promise<OptimizeDepsResult | undefined>
}

export interface DepOptimizationMetadata {
  /**
   * The main hash is determined by user config and dependency lockfiles.
   * This is checked on server startup to avoid unnecessary re-bundles.
   */
  hash: string
  /**
   * The browser hash is determined by the main hash plus additional dependencies
   * discovered at runtime. This is used to invalidate browser requests to
   * optimized deps.
   */
  browserHash: string
  /**
   * Metadata for each already optimized dependency
   */
  optimized: Record<string, OptimizedDepInfo>
  /**
   * Metadata for each newly discovered dependency after processing
   */
  discovered: Record<string, OptimizedDepInfo>
  /**
   * During optimization, ids can still be resolved to their final location
   * but the bundles may not yet be saved to disk
   */
  processing: Promise<OptimizeDepsResult | undefined>
}

export async function optimizeDeps(
  config: ResolvedConfig,
  force = config.server.force,
  asCommand = false,
  currentData: DepOptimizationMetadata | null = null,
  newDeps?: Record<string, OptimizedDepInfo>, // missing imports encountered after server has started
  ssr?: boolean,
  processing: OptimizeDepsProcessing = newOptimizeDepsProcessingPromise()
): Promise<DepOptimizationMetadata> {
  config = {
    ...config,
    command: 'build'
  }

  const { root, logger, cacheDir } = config
  const log = asCommand ? logger.info : debug

  const dataPath = path.join(cacheDir, '_metadata.json')
  const mainHash = getDepHash(root, config)

  const data: DepOptimizationMetadata = {
    hash: mainHash,
    browserHash: mainHash,
    optimized: {},
    discovered: {},
    processing: processing.promise
  }

  if (!force) {
    let prevData: DepOptimizationMetadata | undefined
    try {
      prevData = JSON.parse(fs.readFileSync(dataPath, 'utf-8'))
    } catch (e) {}
    // hash is consistent, no need to re-bundle
    if (prevData && prevData.hash === data.hash) {
      log('Hash is consistent. Skipping. Use --force to override.')
      for (const o of Object.keys(prevData.optimized)) {
        prevData.optimized[o].processing = processing.promise
      }
      setTimeout(() => processing.resolve(), 0)
      return { ...prevData, discovered: {}, processing: processing.promise }
    }
  }

  if (fs.existsSync(cacheDir)) {
    emptyDir(cacheDir)
  } else {
    fs.mkdirSync(cacheDir, { recursive: true })
  }
  // a hint for Node.js
  // all files in the cache directory should be recognized as ES modules
  writeFile(
    path.resolve(cacheDir, 'package.json'),
    JSON.stringify({ type: 'module' })
  )

  let deps: Record<string, string>
  if (!newDeps) {
    // Initial optimizeDeps at server start. Perform a fast scan using esbuild to
    // find deps to pre-bundle and include user harcoded dependencies

    let missing: Record<string, string>
    ;({ deps, missing } = await scanImports(config))

    const missingIds = Object.keys(missing)
    if (missingIds.length) {
      processing.resolve()
      throw new Error(
        `The following dependencies are imported but could not be resolved:\n\n  ${missingIds
          .map(
            (id) =>
              `${colors.cyan(id)} ${colors.white(
                colors.dim(`(imported by ${missing[id]})`)
              )}`
          )
          .join(`\n  `)}\n\nAre they installed?`
      )
    }

    const include = config.optimizeDeps?.include
    if (include) {
      const resolve = config.createResolver({ asSrc: false })
      for (const id of include) {
        // normalize 'foo   >bar` as 'foo > bar' to prevent same id being added
        // and for pretty printing
        const normalizedId = normalizeId(id)
        if (!deps[normalizedId]) {
          const entry = await resolve(id)
          if (entry) {
            deps[normalizedId] = entry
          } else {
            processing.resolve()
            throw new Error(
              `Failed to resolve force included dependency: ${colors.cyan(id)}`
            )
          }
        }
      }
    }

    // update browser hash
    data.browserHash = getOptimizedBrowserHash(data.hash, deps)

    // We generate the mapping of dependency ids to their cache file location
    // before processing the dependencies with esbuild. This allow us to continue
    // processing files in the importAnalysis and resolve plugins
    for (const id in deps) {
      const entry = deps[id]
      data.optimized[id] = {
        file: getOptimizedFilePath(id, cacheDir),
        src: entry,
        browserHash: data.browserHash,
        processing: processing.promise
      }
    }
  } else {
    // Missing dependencies were found at run-time, optimizeDeps called while the
    // server is running
    deps = depsFromOptimizedInfo(newDeps)

    // Clone optimized info objects, fileHash, browserHash may be changed for them
    for (const o of Object.keys(newDeps)) {
      data.optimized[o] = { ...newDeps[o] }
    }

    // update global browser hash, but keep newDeps individual hashs until we know
    // if files are stable so we can avoid a full page reload
    data.browserHash = getOptimizedBrowserHash(data.hash, deps)
  }

  // We prebundle dependencies with esbuild and cache them, but there is no need
  // to wait here. Code that needs to access the cached deps needs to await
  // the optimizeDepsMetadata.processing promise
  prebundleDeps()

  return data

  async function prebundleDeps() {
    const qualifiedIds = Object.keys(deps)

    if (!qualifiedIds.length) {
      writeFile(dataPath, JSON.stringify(data, null, 2))
      log(`No dependencies to bundle. Skipping.\n\n\n`)
      processing.resolve()
      return data
    }

    const total = qualifiedIds.length
    const maxListed = 5
    const listed = Math.min(total, maxListed)
    const extra = Math.max(0, total - maxListed)
    const depsString = colors.yellow(
      qualifiedIds.slice(0, listed).join(`\n  `) +
        (extra > 0 ? `\n  (...and ${extra} more)` : ``)
    )
    if (!asCommand) {
      if (!newDeps) {
        // This is auto run on server start - let the user know that we are
        // pre-optimizing deps
        logger.info(colors.green(`Pre-bundling dependencies:\n  ${depsString}`))
        logger.info(
          `(this will be run only when your dependencies or config have changed)`
        )
      }
    } else {
      logger.info(colors.green(`Optimizing dependencies:\n  ${depsString}`))
    }

    // esbuild generates nested directory output with lowest common ancestor base
    // this is unpredictable and makes it difficult to analyze entry / output
    // mapping. So what we do here is:
    // 1. flatten all ids to eliminate slash
    // 2. in the plugin, read the entry ourselves as virtual files to retain the
    //    path.
    const flatIdDeps: Record<string, string> = {}
    const idToExports: Record<string, ExportsData> = {}
    const flatIdToExports: Record<string, ExportsData> = {}

    const { plugins = [], ...esbuildOptions } =
      config.optimizeDeps?.esbuildOptions ?? {}

    await init
    for (const id in deps) {
      const flatId = flattenId(id)
      const filePath = (flatIdDeps[flatId] = deps[id])
      const entryContent = fs.readFileSync(filePath, 'utf-8')
      let exportsData: ExportsData
      try {
        exportsData = parse(entryContent) as ExportsData
      } catch {
        debug(
          `Unable to parse dependency: ${id}. Trying again with a JSX transform.`
        )
        const transformed = await transformWithEsbuild(entryContent, filePath, {
          loader: 'jsx'
        })
        // Ensure that optimization won't fail by defaulting '.js' to the JSX parser.
        // This is useful for packages such as Gatsby.
        esbuildOptions.loader = {
          '.js': 'jsx',
          ...esbuildOptions.loader
        }
        exportsData = parse(transformed.code) as ExportsData
      }
      for (const { ss, se } of exportsData[0]) {
        const exp = entryContent.slice(ss, se)
        if (/export\s+\*\s+from/.test(exp)) {
          exportsData.hasReExports = true
        }
      }
      idToExports[id] = exportsData
      flatIdToExports[flatId] = exportsData
    }

    const define: Record<string, string> = {
      'process.env.NODE_ENV': JSON.stringify(config.mode)
    }
    for (const key in config.define) {
      const value = config.define[key]
      define[key] = typeof value === 'string' ? value : JSON.stringify(value)
    }

    const start = performance.now()

    const result = await build({
      absWorkingDir: process.cwd(),
      entryPoints: Object.keys(flatIdDeps),
      bundle: true,
      format: 'esm',
      target: config.build.target || undefined,
      external: config.optimizeDeps?.exclude,
      logLevel: 'error',
      splitting: true,
      sourcemap: true,
      outdir: cacheDir,
      ignoreAnnotations: true,
      metafile: true,
      define,
      plugins: [
        ...plugins,
        esbuildDepPlugin(flatIdDeps, flatIdToExports, config, ssr)
      ],
      ...esbuildOptions
    })

    const meta = result.metafile!

    // the paths in `meta.outputs` are relative to `process.cwd()`
    const cacheDirOutputPath = path.relative(process.cwd(), cacheDir)

    for (const id in deps) {
      const optimizedInfo = data.optimized[id]
      optimizedInfo.needsInterop = needsInterop(
        id,
        idToExports[id],
        meta.outputs,
        cacheDirOutputPath
      )
      const output =
        meta.outputs[path.relative(process.cwd(), optimizedInfo.file)]
      if (output) {
        // We only need to hash the output.imports in to check for stability, but adding the hash
        // and file path gives us a unique hash that may be useful for other things in the future
        optimizedInfo.fileHash = getHash(
          data.hash + optimizedInfo.file + JSON.stringify(output.imports)
        )
      }
    }

    // This only runs when missing deps are processed. Previous optimized deps are stable if
    // the newly discovered deps don't have common chunks with them. Comparing their fileHash we
    // can find out if it is safe to keep the current browser state. If one of the file hashes
    // changed, a full page reload is needed
    let alteredFiles = false
    if (currentData) {
      alteredFiles = Object.keys(currentData.optimized).some((dep) => {
        const currentInfo = currentData.optimized[dep]
        const info = data.optimized[dep]
        return (
          !info?.fileHash ||
          !currentInfo?.fileHash ||
          info?.fileHash !== currentInfo?.fileHash
        )
      })
      debug(`optimized deps have altered files: ${alteredFiles}`)
    }

    if (alteredFiles) {
      // Overrite individual hashs with the new global browserHash, a full page reload is required
      // New deps that ended up with a different hash replaced while doing analysis import are going to
      // return a not found so the browser doesn't cache them. And will properly get loaded after the reload
      for (const id in deps) {
        data.optimized[id].browserHash = data.browserHash
      }
    }

    writeFile(dataPath, JSON.stringify(data, metadataStringifyReplacer, 2))

    debug(`deps bundled in ${(performance.now() - start).toFixed(2)}ms`)
    processing.resolve({ alteredFiles })
  }
}

export function newOptimizeDepsProcessingPromise(): OptimizeDepsProcessing {
  let resolve: (result?: OptimizeDepsResult) => void
  const promise = new Promise((_resolve) => {
    resolve = _resolve
  }) as Promise<OptimizeDepsResult | undefined>
  return { promise, resolve: resolve! }
}

// Convert to { id: src }
export function depsFromOptimizedInfo(
  depsInfo: Record<string, OptimizedDepInfo>
) {
  return Object.fromEntries(
    Object.entries(depsInfo).map((d) => [d[0], d[1].src])
  )
}

export function getOptimizedFilePath(id: string, cacheDir: string) {
  return normalizePath(path.resolve(cacheDir, flattenId(id) + '.js'))
}

function getHash(text: string) {
  return createHash('sha256').update(text).digest('hex').substring(0, 8)
}

export function getOptimizedBrowserHash(
  hash: string,
  deps: Record<string, string>,
  missing?: Record<string, string>
) {
  // update browser hash
  return getHash(
    hash + JSON.stringify(deps) + (missing ? JSON.stringify(missing) : '')
  )
}

export function isOptimizedDepFile(id: string, config: ResolvedConfig) {
  return id.startsWith(normalizePath(config.cacheDir))
}

export function createIsOptimizedDepUrl(config: ResolvedConfig) {
  const { root, cacheDir } = config

  // determine the url prefix of files inside cache directory
  const cacheDirRelative = normalizePath(path.relative(root, cacheDir))
  const cacheDirPrefix = cacheDirRelative.startsWith('../')
    ? // if the cache directory is outside root, the url prefix would be something
      // like '/@fs/absolute/path/to/node_modules/.vite'
      `/@fs/${normalizePath(cacheDir).replace(/^\//, '')}`
    : // if the cache directory is inside root, the url prefix would be something
      // like '/node_modules/.vite'
      `/${cacheDirRelative}`

  return function isOptimizedDepUrl(url: string): boolean {
    return url.startsWith(cacheDirPrefix)
  }
}

function metadataStringifyReplacer(key: string, value: any) {
  return key !== 'processing' && key !== 'discovered' ? value : undefined
}

// https://github.com/vitejs/vite/issues/1724#issuecomment-767619642
// a list of modules that pretends to be ESM but still uses `require`.
// this causes esbuild to wrap them as CJS even when its entry appears to be ESM.
const KNOWN_INTEROP_IDS = new Set(['moment'])

function needsInterop(
  id: string,
  exportsData: ExportsData,
  outputs: Record<string, any>,
  cacheDirOutputPath: string
): boolean {
  if (KNOWN_INTEROP_IDS.has(id)) {
    return true
  }
  const [imports, exports] = exportsData
  // entry has no ESM syntax - likely CJS or UMD
  if (!exports.length && !imports.length) {
    return true
  }

  // if a peer dependency used require() on a ESM dependency, esbuild turns the
  // ESM dependency's entry chunk into a single default export... detect
  // such cases by checking exports mismatch, and force interop.
  const flatId = flattenId(id) + '.js'
  let generatedExports: string[] | undefined
  for (const output in outputs) {
    if (
      normalizePath(output) ===
      normalizePath(path.join(cacheDirOutputPath, flatId))
    ) {
      generatedExports = outputs[output].exports
      break
    }
  }

  if (
    !generatedExports ||
    (isSingleDefaultExport(generatedExports) && !isSingleDefaultExport(exports))
  ) {
    return true
  }
  return false
}

function isSingleDefaultExport(exports: readonly string[]) {
  return exports.length === 1 && exports[0] === 'default'
}

const lockfileFormats = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']

function getDepHash(root: string, config: ResolvedConfig): string {
  let content = lookupFile(root, lockfileFormats) || ''
  // also take config into account
  // only a subset of config options that can affect dep optimization
  content += JSON.stringify(
    {
      mode: config.mode,
      root: config.root,
      resolve: config.resolve,
      assetsInclude: config.assetsInclude,
      plugins: config.plugins.map((p) => p.name),
      optimizeDeps: {
        include: config.optimizeDeps?.include,
        exclude: config.optimizeDeps?.exclude
      }
    },
    (_, value) => {
      if (typeof value === 'function' || value instanceof RegExp) {
        return value.toString()
      }
      return value
    }
  )
  return createHash('sha256').update(content).digest('hex').substring(0, 8)
}