feat: add ESBuild-based edge bundler

[trieloff]

Summary

This PR introduces EdgeESBuildBundler as an alternative to the webpack-based EdgeBundler, building upon and expanding the work in PR #89.

• New EdgeESBuildBundler: Uses ESBuild (already available via @fastly/js-compute) for faster bundling with platform: 'browser' for Service Worker compatibility
• CLI integration: Support for --bundler esbuild flag to select the new bundler
• Fastly module handling: ESBuild plugin to properly externalize fastly:* modules
• Local runtime validation: Integration tests that verify bundles work with both Cloudflare wrangler and Fastly viceroy local runtimes

Key Changes

• Add src/EdgeESBuildBundler.js extending BaseBundler directly
• Add test fixture test/fixtures/esbuild-action/ for testing
• Add integration tests in test/build.esbuild.test.js
• Add fs-extra and esbuild as direct dependencies

Test plan

• Unit tests pass (55 passing)
• ESLint passes (0 errors)
• Local Cloudflare wrangler validation (detects "cloudflare" platform)
• Local Fastly viceroy validation (detects "fastly" platform)
• CI pipeline tests

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a major release when merged.

[trieloff]

needs work.

[trieloff]

Suggested change

	"esbuild": "^0.25.0",
	"esbuild": "0.25.0",

prefer exact versions

[trieloff]

good idea. implement that, if they are installed

[trieloff]

Suggested change

	* Copyright 2021 Adobe. All rights reserved.
	* Copyright 2025 Adobe. All rights reserved.

wrong year

[Copilot]

Pull request overview

This PR introduces a modern ESBuild-based bundler (EdgeESBuildBundler) to replace the webpack-based EdgeBundler for edge compute platforms (Cloudflare Workers and Fastly Compute@Edge). The new bundler offers faster build times and better platform compatibility.

Key Changes

• New ESBuild bundler: Implements EdgeESBuildBundler with ESBuild for faster bundling, platform-specific module handling (fastly:* externals), and local validation support
• Fastly runtime abstraction: Creates fastly-runtime.js module to centralize Fastly module imports and enable better testing via mocking
• Enhanced platform detection: Updates edge adapter to dynamically detect Cloudflare vs Fastly environments and route requests accordingly
• Secret store migration: Moves from Fastly Dictionaries to Secret Stores for better security and parameter management
• Comprehensive testing: Adds extensive unit and integration tests for the new bundler with local runtime validation

Reviewed changes

Copilot reviewed 34 out of 36 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
src/EdgeESBuildBundler.js	New ESBuild-based bundler with validation support
src/template/fastly-runtime.js	Centralized Fastly module loading abstraction
src/template/edge-index.js	Updated platform detection with async handler resolution
src/template/fastly-adapter.js	Refactored to use fastly-runtime and Secret Stores
src/template/cloudflare-adapter.js	Enhanced worker name extraction from hostname
src/template/polyfills/fetch.js	Improved fetch polyfill with backend auto-resolution
src/template/context-logger.js	Updated logger to use fastly-runtime abstraction
src/ComputeAtEdgeDeployer.js	Migrated from Dictionaries to Secret Stores
src/CloudflareDeployer.js	Added lowercase normalization for consistency
src/FastlyGateway.js	Simplified by removing package parameter management
src/index.js	Updated plugin exports to use EdgeESBuildBundler
test/build.esbuild.test.js	Comprehensive ESBuild bundler tests with local validation
test/edge-integration.test.js	New integration tests for both Cloudflare and Fastly
test/fastly-adapter.test.js	Enhanced tests with mocking via esmock
test/fixtures/esbuild-action/*	New test fixture for ESBuild bundler validation
test/fixtures/edge-action/src/index.js	Enhanced with logging tests and environment detection
package.json	Added esbuild, fs-extra, esmock, wrangler dependencies
.env.example	New environment variable template for credentials

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The finally block attempts to kill the wrangler process, but there's no guarantee the process has time to clean up. Consider adding a small delay after kill() or waiting for the process to exit:

if (wranglerProcess) {
  wranglerProcess.kill('SIGTERM');
  // Wait a bit for graceful shutdown
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

This pattern appears twice (wrangler and fastly validation), so the same improvement applies to both.

[Copilot]

The bundler was changed from 'webpack' to 'esbuild' in a skipped test. Since this test is skipped anyway, this change may not be intentional or might cause the test to fail when it's re-enabled. Consider verifying if this change is necessary.

[Copilot]

The JSDoc comment for the wrappedFetch function is incomplete. It should document the backend option and the platform-specific behavior:

/**
 * Wrapped fetch that supports the cacheOverride option and automatic backend resolution for Fastly
 * @param {string|Request} resource - URL or Request object
 * @param {object} [options] - Fetch options
 * @param {CacheOverride} [options.cacheOverride] - Cache override configuration
 * @param {string|object} [options.backend] - Fastly backend (auto-resolved from hostname if not provided)
 * @returns {Promise<Response>} Fetch response
 */

Suggested change

	* Wrapped fetch that supports the cacheOverride option and automatic backend resolution for Fastly
	* Wrapped fetch that supports the cacheOverride option and automatic backend resolution for Fastly.
	*
	* On Fastly, if the `backend` option is not provided, it is automatically resolved from the resource's hostname.
	* On Cloudflare, the `cacheOverride` option is translated to Cloudflare-specific cache options.
	* On other platforms, the function falls back to the standard fetch behavior.
	*
	* @param {string|Request} resource - URL or Request object to fetch.
	* @param {object} [options] - Fetch options.
	* @param {CacheOverride} [options.cacheOverride] - Cache override configuration.
	* @param {string|object} [options.backend] - Fastly backend to use for the request. If not provided on Fastly, it is auto-resolved from the resource's hostname.
	* @returns {Promise<Response>} Fetch response.

[Copilot]

The copyright year in this new file is 2024, but according to the PR metadata, it's currently December 2025. The copyright should be 2025 to match the current year.

Suggested change

	* Copyright 2024 Adobe. All rights reserved.
	* Copyright 2025 Adobe. All rights reserved.

[Copilot]

The while loop uses a blocking pattern with Date.now() checks. Consider using async/await with a loop counter instead of time-based polling to make the logic clearer and avoid potential timing issues:

async waitForServer(url, timeout = 10000, interval = 500) {
  const maxAttempts = Math.floor(timeout / interval);
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(url);
      if (response.ok || response.status < 500) {
        return true;
      }
    } catch {
      // Server not ready yet, continue polling
    }
    await new Promise((resolve) => setTimeout(resolve, interval));
  }
  return false;
}

[Copilot]

The CacheOverride class is missing JSDoc documentation for the constructor, which would help users understand the parameters and options. Consider adding:

/**
 * Unified CacheOverride class that works across Fastly and Cloudflare platforms
 * @param {string|object} modeOrInit - Either a mode string ('pass', 'override', 'none') or init object
 * @param {object} [init] - Optional init object when mode is first param
 * @param {number} [init.ttl] - Time-to-live in seconds
 * @param {string} [init.cacheKey] - Custom cache key
 * @param {string} [init.surrogateKey] - Surrogate keys for cache purging (space-separated)
 */

[Copilot]

The validateBundle() method performs local validation by starting servers and making HTTP requests. This method should document:

1. That it requires external tools (wrangler/fastly CLI) to be installed
2. That it starts local servers on random ports
3. That it may take significant time to complete
4. What the return value represents

Consider adding comprehensive JSDoc:

/**
 * Validates the edge bundle using wrangler (Cloudflare) or viceroy (Fastly) if available.
 * This method performs local validation by:
 * 1. Starting a local development server (wrangler or fastly CLI)
 * 2. Making an HTTP request to validate the bundle works
 * 3. Stopping the server
 * 
 * Requirements:
 * - wrangler CLI must be installed for Cloudflare validation
 * - fastly CLI must be installed for Fastly validation
 * 
 * @returns {Promise<{wrangler?: boolean, fastly?: boolean}>} Validation results for each platform
 */

Suggested change

	* Starts a local server, makes an HTTP request to validate, then stops the server.
	* @returns {Promise<{wrangler?: boolean, fastly?: boolean}>} Validation results
	*
	* This method performs local validation by:
	* 1. Starting a local development server (wrangler or fastly CLI) on a random port.
	* 2. Making an HTTP request to validate that the bundle works as expected.
	* 3. Stopping the server after validation.
	*
	* Requirements:
	* - The `wrangler` CLI must be installed and available in the system PATH for Cloudflare validation.
	* - The `fastly` CLI must be installed and available in the system PATH for Fastly validation.
	*
	* Side Effects:
	* - Starts and stops local servers on random ports.
	* - May use system resources and network ports temporarily.
	*
	* Performance:
	* - This method may take significant time to complete, depending on server startup and validation.
	*
	* @returns {Promise<{wrangler?: boolean, fastly?: boolean}>}
	* An object indicating validation results for each platform:
	* - `wrangler`: true if Cloudflare validation succeeded, false if failed, undefined if not attempted.
	* - `fastly`: true if Fastly validation succeeded, false if failed, undefined if not attempted.

[Copilot]

There are multiple debug console.log() statements throughout this file (lines 22, 26, 31-34, 40, 45, 52-53, 56-57, 60-61, 67, 70, 74, 80, 85, 90, 95, 97, 102, 107, 114). These should either be removed for production code or guarded behind a debug flag. Consider using a debug utility or removing them:

const DEBUG = false; // or process.env.DEBUG_EDGE === 'true'
const log = DEBUG ? console.log : () => {};

Debug logging in production can impact performance and leak implementation details.

[Copilot]

There's a trailing space after "deployments" on line 8.

Suggested change

	# Cloudflare API token for Workers deployments
	# Cloudflare API token for Workers deployments

[Copilot]

The Promise-based get trap in the env Proxy returns a Promise, which means accessing context.env.FOO will return a Promise, not the actual value. This requires consumers to use await context.env.FOO everywhere. While this is shown in the test fixtures, it could be error-prone. Consider documenting this behavior clearly in code comments:

// Load SecretStore dynamically and access secrets
// NOTE: All env property accesses return Promises and must be awaited:
//   const value = await context.env.FOO;
return getSecretStore().then((SecretStore) => {