chore: centralize debug codes

.github/contributing.md

@@ -75,6 +75,10 @@ test('?raw import', async () => {
 })
 ```
 
+## Debug Logging
+
+You can set the DEBUG environment variable to turn on debugging logs. E.g. `DEBUG="vite:resolve"`. To see all debug logs you can set `DEBUG="vite:*"`, but be warned that it will be quite noisy. You can see the list of all available debug scopes in [debugger.ts](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/debugger.ts).
+
 ## Pull Request Guidelines
 
 - Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch.

packages/vite/src/node/config.ts

@@ -8,13 +8,8 @@ import {
   ServerOptions
 } from './server'
 import { CSSOptions } from './plugins/css'
-import {
-  createDebugger,
-  isExternalUrl,
-  isObject,
-  lookupFile,
-  normalizePath
-} from './utils'
+import { isExternalUrl, isObject, lookupFile, normalizePath } from './utils'
+import { createDebugger, DebugScopes } from './debugger'
 import { resolvePlugins } from './plugins'
 import chalk from 'chalk'
 import { ESBuildOptions } from './plugins/esbuild'
@@ -40,7 +35,7 @@ import {
 import aliasPlugin from '@rollup/plugin-alias'
 import { build } from 'esbuild'
 
-const debug = createDebugger('vite:config')
+const debug = createDebugger(DebugScopes.CONFIG)
 
 // NOTE: every export in this file is re-exported from ./index.ts so it will
 // be part of the public API.

packages/vite/src/node/debugger.ts

@@ -0,0 +1,49 @@
+import debug from 'debug'
+
+// set in bin/vite.js
+const filter = process.env.VITE_DEBUG_FILTER
+
+const DEBUG = process.env.DEBUG
+
+interface DebuggerOptions {
+  onlyWhenFocused?: boolean | string
+}
+
+export type ViteDebugScope = `vite:${string}`
+
+export function createDebugger(
+  ns: ViteDebugScope,
+  options: DebuggerOptions = {}
+): debug.Debugger['log'] {
+  const log = debug(ns)
+  const { onlyWhenFocused } = options
+  const focus = typeof onlyWhenFocused === 'string' ? onlyWhenFocused : ns
+  return (msg: string, ...args: any[]) => {
+    if (filter && !msg.includes(filter)) {
+      return
+    }
+    if (onlyWhenFocused && !DEBUG?.includes(focus)) {
+      return
+    }
+    log(msg, ...args)
+  }
+}
+
+export const DebugScopes: Record<string, ViteDebugScope> = Object.freeze({
+  CACHE: 'vite:cache',
+  CONFIG: 'vite:config',
+  DEPS: 'vite:deps',
+  ESBUILD: 'vite:esbuild',
+  HMR: 'vite:hmr',
+  LOAD: 'vite:load',
+  PLUGIN_RESOLVE: 'vite:plugin-resolve',
+  PLUGIN_TRANSFORM: 'vite:plugin-transform',
+  PROXY: 'vite:proxy',
+  RESOLVE: 'vite:resolve',
+  RESOLVE_DETAILS: 'vite:resolve-details',
+  REWRITE: 'vite:rewrite',
+  SOURCEMAP: 'vite:sourcemap',
+  SPA_FALLBACK: 'vite:spa-fallback',
+  TIME: 'vite:time',
+  TRANSFORM: 'vite:transform'
+})

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

@@ -5,18 +5,18 @@ import { createHash } from 'crypto'
 import { build, BuildOptions as EsbuildBuildOptions } from 'esbuild'
 import { ResolvedConfig } from '../config'
 import {
-  createDebugger,
   emptyDir,
   lookupFile,
   normalizePath,
   writeFile,
   flattenId
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { esbuildDepPlugin } from './esbuildDepPlugin'
 import { ImportSpecifier, init, parse } from 'es-module-lexer'
 import { scanImports } from './scan'
 
-const debug = createDebugger('vite:deps')
+const debug = createDebugger(DebugScopes.DEPS)
 
 export type ExportsData = [ImportSpecifier[], string[]] & {
   // es-module-lexer has a facade detection but isn't always accurate for our

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

@@ -10,13 +10,13 @@ import {
   OPTIMIZABLE_ENTRY_RE
 } from '../constants'
 import {
-  createDebugger,
   normalizePath,
   isObject,
   cleanUrl,
   externalRE,
   dataUrlRE
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import {
   createPluginContainer,
   PluginContainer
@@ -25,7 +25,7 @@ import { init, parse } from 'es-module-lexer'
 import MagicString from 'magic-string'
 import { transformImportGlob } from '../importGlob'
 
-const debug = createDebugger('vite:deps')
+const debug = createDebugger(DebugScopes.DEPS)
 
 const htmlTypesRE = /\.(html|vue|svelte)$/
 

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

@@ -8,7 +8,8 @@ import {
   TransformOptions,
   TransformResult
 } from 'esbuild'
-import { cleanUrl, createDebugger, generateCodeFrame } from '../utils'
+import { cleanUrl, generateCodeFrame } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { RawSourceMap } from '@ampproject/remapping/dist/types/types'
 import { SourceMap } from 'rollup'
 import { ResolvedConfig } from '..'
@@ -17,7 +18,7 @@ import { combineSourcemaps } from '../utils'
 import { find as findTSConfig, readFile as readTSConfig } from 'tsconfig'
 import { createRequire } from 'module'
 
-const debug = createDebugger('vite:esbuild')
+const debug = createDebugger(DebugScopes.ESBUILD)
 
 export interface ESBuildOptions extends TransformOptions {
   include?: string | RegExp | string[] | RegExp[]

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

@@ -9,7 +9,6 @@ import { isCSSRequest, isDirectCSSRequest } from './css'
 import {
   isBuiltin,
   cleanUrl,
-  createDebugger,
   generateCodeFrame,
   injectQuery,
   isDataUrl,
@@ -19,6 +18,7 @@ import {
   timeFrom,
   normalizePath
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import {
   debugHmr,
   handlePrunedModules,
@@ -41,7 +41,7 @@ import { makeLegalIdentifier } from '@rollup/pluginutils'
 import { shouldExternalizeForSSR } from '../ssr/ssrExternal'
 
 const isDebug = !!process.env.DEBUG
-const debugRewrite = createDebugger('vite:rewrite')
+const debugRewrite = createDebugger(DebugScopes.REWRITE)
 
 const clientDir = normalizePath(CLIENT_DIR)
 

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

@@ -12,7 +12,6 @@ import {
 import {
   isBuiltin,
   bareImportRE,
-  createDebugger,
   deepImportRE,
   injectQuery,
   isExternalUrl,
@@ -25,6 +24,7 @@ import {
   cleanUrl,
   slash
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { ViteDevServer, SSRTarget } from '..'
 import { createFilter } from '@rollup/pluginutils'
 import { PartialResolvedId } from 'rollup'
@@ -35,7 +35,7 @@ import { resolve as _resolveExports } from 'resolve.exports'
 export const browserExternalId = '__vite-browser-external'
 
 const isDebug = process.env.DEBUG
-const debug = createDebugger('vite:resolve-details', {
+const debug = createDebugger(DebugScopes.RESOLVE_DETAILS, {
   onlyWhenFocused: true
 })
 

packages/vite/src/node/server/hmr.ts

@@ -2,7 +2,8 @@ import fs from 'fs'
 import path from 'path'
 import chalk from 'chalk'
 import { createServer, ViteDevServer } from '..'
-import { createDebugger, normalizePath } from '../utils'
+import { normalizePath } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { ModuleNode } from './moduleGraph'
 import { Update } from 'types/hmrPayload'
 import { CLIENT_DIR } from '../constants'
@@ -12,7 +13,7 @@ import match from 'minimatch'
 import { Server } from 'http'
 import { cssLangRE } from '../plugins/css'
 
-export const debugHmr = createDebugger('vite:hmr')
+export const debugHmr = createDebugger(DebugScopes.HMR)
 
 const normalizedClientDir = normalizePath(CLIENT_DIR)
 

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

@@ -30,7 +30,8 @@ import {
 import { timeMiddleware } from './middlewares/time'
 import { ModuleGraph, ModuleNode } from './moduleGraph'
 import { Connect } from 'types/connect'
-import { createDebugger, ensureLeadingSlash, normalizePath } from '../utils'
+import { ensureLeadingSlash, normalizePath } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { errorMiddleware, prepareError } from './middlewares/error'
 import { handleHMRUpdate, HmrOptions, handleFileAddUnlink } from './hmr'
 import { openBrowser } from './openBrowser'
@@ -497,7 +498,7 @@ export async function createServer(
   if (!middlewareMode || middlewareMode === 'html') {
     middlewares.use(
       history({
-        logger: createDebugger('vite:spa-fallback'),
+        logger: createDebugger(DebugScopes.SPA_FALLBACK),
         // support /dir/ without explicit index.html
         rewrites: [
           {

packages/vite/src/node/server/middlewares/proxy.ts

@@ -1,13 +1,14 @@
 import * as http from 'http'
-import { createDebugger, isObject } from '../../utils'
+import { isObject } from '../../utils'
+import { createDebugger, DebugScopes } from '../../debugger'
 import httpProxy from 'http-proxy'
 import { HMR_HEADER } from '../ws'
 import { Connect } from 'types/connect'
 import { HttpProxy } from 'types/http-proxy'
 import chalk from 'chalk'
 import { ResolvedConfig } from '../..'
 
-const debug = createDebugger('vite:proxy')
+const debug = createDebugger(DebugScopes.PROXY)
 
 export interface ProxyOptions extends HttpProxy.ServerOptions {
   /**

packages/vite/src/node/server/middlewares/time.ts

@@ -1,7 +1,8 @@
 import { Connect } from 'types/connect'
-import { createDebugger, prettifyUrl, timeFrom } from '../../utils'
+import { prettifyUrl, timeFrom } from '../../utils'
+import { createDebugger, DebugScopes } from '../../debugger'
 
-const logTime = createDebugger('vite:time')
+const logTime = createDebugger(DebugScopes.TIME)
 
 export function timeMiddleware(root: string): Connect.NextHandleFunction {
   // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`

packages/vite/src/node/server/middlewares/transform.ts

@@ -3,7 +3,6 @@ import { ViteDevServer } from '..'
 import { Connect } from 'types/connect'
 import {
   cleanUrl,
-  createDebugger,
   injectQuery,
   isImportRequest,
   isJSRequest,
@@ -13,6 +12,7 @@ import {
   removeTimestampQuery,
   unwrapId
 } from '../../utils'
+import { createDebugger, DebugScopes } from '../../debugger'
 import { send } from '../send'
 import { transformRequest } from '../transformRequest'
 import { isHTMLProxy } from '../../plugins/html'
@@ -30,7 +30,7 @@ import { isCSSRequest, isDirectCSSRequest } from '../../plugins/css'
  */
 const NEW_DEPENDENCY_BUILD_TIMEOUT = 1000
 
-const debugCache = createDebugger('vite:cache')
+const debugCache = createDebugger(DebugScopes.CACHE)
 const isDebug = !!process.env.DEBUG
 
 const knownIgnoreList = new Set(['/', '/favicon.ico'])

packages/vite/src/node/server/pluginContainer.ts

@@ -58,7 +58,6 @@ import { combineSourcemaps } from '../utils'
 import MagicString from 'magic-string'
 import { FSWatcher } from 'chokidar'
 import {
-  createDebugger,
   ensureWatchedFile,
   generateCodeFrame,
   isObject,
@@ -68,6 +67,7 @@ import {
   prettifyUrl,
   timeFrom
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { FS_PREFIX } from '../constants'
 import chalk from 'chalk'
 import { ResolvedConfig } from '../config'
@@ -127,11 +127,11 @@ export async function createPluginContainer(
   const isDebug = process.env.DEBUG
 
   const seenResolves: Record<string, true | undefined> = {}
-  const debugResolve = createDebugger('vite:resolve')
-  const debugPluginResolve = createDebugger('vite:plugin-resolve', {
+  const debugResolve = createDebugger(DebugScopes.RESOLVE)
+  const debugPluginResolve = createDebugger(DebugScopes.PLUGIN_RESOLVE, {
     onlyWhenFocused: 'vite:plugin'
   })
-  const debugPluginTransform = createDebugger('vite:plugin-transform', {
+  const debugPluginTransform = createDebugger(DebugScopes.PLUGIN_TRANSFORM, {
     onlyWhenFocused: 'vite:plugin'
   })
 

packages/vite/src/node/server/sourcemap.ts

@@ -1,10 +1,10 @@
 import path from 'path'
 import { promises as fs } from 'fs'
 import { Logger } from '../logger'
-import { createDebugger } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 
 const isDebug = !!process.env.DEBUG
-const debug = createDebugger('vite:sourcemap', {
+const debug = createDebugger(DebugScopes.SOURCEMAP, {
   onlyWhenFocused: true
 })
 

packages/vite/src/node/server/transformRequest.ts

@@ -6,22 +6,22 @@ import { SourceDescription, SourceMap } from 'rollup'
 import { ViteDevServer } from '..'
 import chalk from 'chalk'
 import {
-  createDebugger,
   cleanUrl,
   prettifyUrl,
   removeTimestampQuery,
   timeFrom,
   ensureWatchedFile,
   isObject
 } from '../utils'
+import { createDebugger, DebugScopes } from '../debugger'
 import { checkPublicFile } from '../plugins/asset'
 import { ssrTransform } from '../ssr/ssrTransform'
 import { injectSourcesContent } from './sourcemap'
 import { isFileServingAllowed } from './middlewares/static'
 
-const debugLoad = createDebugger('vite:load')
-const debugTransform = createDebugger('vite:transform')
-const debugCache = createDebugger('vite:cache')
+const debugLoad = createDebugger(DebugScopes.LOAD)
+const debugTransform = createDebugger(DebugScopes.TRANSFORM)
+const debugCache = createDebugger(DebugScopes.CACHE)
 const isDebug = !!process.env.DEBUG
 
 export interface TransformResult {