Universal Build Hooks (Part 2): transform / buildEnd / generateBundle / writeBundle

transform(
  code: string,       // Module source code (result after the previous plugin processed it)
  id: string,         // Module path (returned by resolveId)
  options?: {
    ssr?: boolean     // Whether we're in an SSR environment
  }
): TransformResult | null

type TransformResult =
  | string // Modify code only, provide no map
  | null // No modification; pass to the next plugin
  | { code: string; map?: SourceMap } // Modify code and provide a source map

transform(code, id) {
  if (!id.endsWith(".ts") && !id.endsWith(".tsx")) return null

  // Replace environment variable placeholders
  const result = code.replace(/__APP_VERSION__/g, JSON.stringify("1.2.3"))
  return { code: result, map: null }
},

import MagicString from "magic-string"
import type { Plugin } from "vite"

export function replacePlugin(replacements: Record<string, string>): Plugin {
  return {
    name: "vite-plugin-replace",
    transform(code, id) {
      if (!Object.keys(replacements).some((key) => code.includes(key))) {
        return null // Fast path: nothing to process
      }

      const ms = new MagicString(code)

      for (const [from, to] of Object.entries(replacements)) {
        let index = code.indexOf(from)
        while (index !== -1) {
          ms.overwrite(index, index + from.length, to)
          index = code.indexOf(from, index + 1)
        }
      }

      return {
        code: ms.toString(),
        // generateMap produces a source map that precisely corresponds to the original code
        map: ms.generateMap({ hires: true }),
      }
    },
  }
}

Original code: src/App.tsx
         │
         ▼
[pre] vite-plugin-define.transform  → Replace import.meta.env.*
         │ (modified code)
         ▼
[normal] @vitejs/plugin-react.transform → JSX → JS
         │
         ▼
[normal] vite:esbuild.transform     → TypeScript type stripping
         │
         ▼
[post] (no post transform)
         │
         ▼
Final JS code + source map chain

transform(code, id) {
  // 1. Filter by file type (filter first, process later — avoid unnecessary work)
  if (!/\.(ts|tsx|js|jsx)$/.test(id)) return null

  // 2. Filter out node_modules (usually don't need processing)
  if (id.includes("node_modules")) return null

  // 3. Filter specific paths
  if (id.includes("__tests__")) return null

  // 4. Fast path: if the code doesn't contain what we need to process
  if (!code.includes("__REPLACE_ME__")) return null

  // 5. Actual processing
  return { code: code.replace("__REPLACE_ME__", "replaced"), map: null }
},

buildEnd(error) {
  if (error) {
    console.error("[my-plugin] Build failed:", error.message)
    cleanup()
    return
  }
  console.log("[my-plugin] Build complete, processed", processedCount, "modules")
},

generateBundle(
  options: OutputOptions,
  bundle: OutputBundle,     // All output files (chunks + assets)
  isWrite: boolean          // Whether files will be written to disk (false when using generate)
): void

bundle = {
  "assets/logo-HASH.png": {
    type: "asset",
    fileName: "assets/logo-HASH.png",
    source: Buffer,
  },
  "index.js": {
    type: "chunk",
    fileName: "index.js",
    code: "...",           // Final JS code
    modules: {...},        // Module information
    imports: [...],        // Other chunks this chunk depends on
    exports: [...],        // Exported names
    isEntry: true,
    facadeModuleId: "...", // The corresponding entry file
  },
}

generateBundle(_, bundle) {
  const sizes: { name: string; size: number }[] = []

  for (const [fileName, output] of Object.entries(bundle)) {
    if (output.type === "chunk") {
      sizes.push({
        name: fileName,
        size: Buffer.byteLength(output.code, "utf-8"),
      })
    }
  }

  sizes.sort((a, b) => b.size - a.size)
  console.log("\nBundle size analysis:")
  sizes.forEach(({ name, size }) => {
    console.log(`  ${name}: ${(size / 1024).toFixed(1)} KB`)
  })
},

generateBundle(options, bundle) {
  // Inject a new file into the bundle
  this.emitFile({
    type: "asset",
    fileName: "bundle-stats.json",
    source: JSON.stringify({
      chunks: Object.keys(bundle).filter(k => bundle[k].type === "chunk"),
      assets: Object.keys(bundle).filter(k => bundle[k].type === "asset"),
      timestamp: new Date().toISOString(),
    }, null, 2),
  })
},

generateBundle(_, bundle) {
  // Remove sourcemap files from the output (if you don't need to publish them)
  for (const fileName of Object.keys(bundle)) {
    if (fileName.endsWith(".map")) {
      delete bundle[fileName]
    }
  }
},

writeBundle(options, bundle) {
  console.log(`Output written to ${options.dir}`)

  // Good for: triggering notifications after writing, uploading to CDN, sending Slack messages, etc.
  Object.keys(bundle).forEach(fileName => {
    console.log(`  ✓ ${fileName}`)
  })
},

// Implement a bundle analysis plugin that, after a build completes:
// 1. Prints the size (in KB) of each chunk
// 2. Flags chunks over 200KB with a warning (⚠️)
// 3. Generates a bundle-report.json file in the dist/ directory

import type { Plugin } from "vite"

export function bundleReporter(): Plugin {
  return {
    name: "vite-plugin-bundle-reporter",
    apply: "build",
    generateBundle(options, bundle) {
      // TODO:
      // 1. Iterate over all chunks in the bundle
      // 2. Calculate the size of each chunk
      // 3. Print the report
      // 4. Use this.emitFile to generate bundle-report.json
    },
  }
}