{"id":12935,"library":"build-worker","title":"Cloudflare Worker Builder with esbuild","description":"build-worker is a utility that bundles Cloudflare Workers using esbuild, offering a significantly faster alternative to webpack-based solutions like Wrangler v1. It was developed to fill a gap while Cloudflare's official Wrangler v2 (now Wrangler v3) was not yet fully production-ready, as both leverage esbuild for bundling. The package, currently at version 0.3.4, applies an esbuild configuration similar to that used by Wrangler, streamlining the build process for Workers. A key feature is the automatic replacement of the `IS_CLOUDFLARE_WORKER` global variable with `true` during the build, enabling developers to write environment-specific code. Its release cadence is likely irregular, tied to the evolution of Cloudflare's official tooling.","status":"active","version":"0.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/brillout/build-worker","tags":["javascript","typescript"],"install":[{"cmd":"npm install build-worker","lang":"bash","label":"npm"},{"cmd":"yarn add build-worker","lang":"bash","label":"yarn"},{"cmd":"pnpm add build-worker","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler used by build-worker for compiling Cloudflare Workers.","package":"esbuild","optional":false}],"imports":[{"note":"The package primarily uses named ESM exports, unsuitable for CommonJS `require`.","wrong":"const { buildWorker } = require('build-worker')","symbol":"buildWorker","correct":"import { buildWorker } from 'build-worker'"}],"quickstart":{"code":"import { buildWorker } from 'build-worker';\nimport path from 'node:path';\n\nconst entryFile = path.resolve(process.cwd(), 'worker.js');\nconst outFile = path.resolve(process.cwd(), 'dist/worker.js');\n\n// Imagine 'worker.js' contains your Cloudflare Worker code\n// e.g., `export default { async fetch(request) { return new Response('Hello Worker!'); } };`\n\nawait buildWorker({\n  entry: entryFile,\n  out: outFile,\n  debug: false // Set to true for easier debugging (disables minification)\n});\n\nconsole.log(`Cloudflare Worker bundled from ${entryFile} to ${outFile}`);","lang":"typescript","description":"Demonstrates programmatic bundling of a Cloudflare Worker using the `buildWorker` function."},"warnings":[{"fix":"Pin the exact package version in your `package.json` (e.g., `\"build-worker\": \"0.3.4\"`) to prevent automatic updates that could introduce breaking changes.","message":"As a pre-1.0 package (version 0.3.4), `build-worker` may introduce breaking changes in minor or patch releases without strictly adhering to semantic versioning. It is advisable to pin exact versions to avoid unexpected build failures.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Consider migrating to the official `wrangler` CLI for bundling Cloudflare Workers. Refer to Cloudflare's documentation on `wrangler` for its esbuild integration and configuration options.","message":"The primary utility of `build-worker` is likely to diminish as Cloudflare's official `wrangler` CLI (v3+) has fully embraced esbuild for Worker bundling and is now considered stable and production-ready. Direct use of `wrangler` is the recommended path for new projects.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"During development, use `build-worker --entry worker.js --out dist/worker.js --debug` or `await buildWorker({ ..., debug: true })`.","message":"Debugging Cloudflare Workers can be difficult with minified code. The `--debug` CLI flag or `debug: true` programmatic option should be explicitly enabled during development to disable minification and improve code readability for troubleshooting.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure that any code checking for `IS_CLOUDFLARE_WORKER` is only executed within the `build-worker` context. The recommended check is `if (typeof IS_CLOUDFLARE_WORKER !== 'undefined' && IS_CLOUDFLARE_WORKER === true)`.","message":"The `IS_CLOUDFLARE_WORKER` global is a `build-worker` specific injection. Code relying on it will not function correctly or might throw a `ReferenceError` if bundled with other tools or run outside the Cloudflare Worker environment without explicit polyfills.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Confirm `build-worker` is used for bundling. The correct conditional check is `if (typeof IS_CLOUDFLARE_WORKER !== 'undefined' && IS_CLOUDFLARE_WORKER === true)`.","cause":"The code using `IS_CLOUDFLARE_WORKER` was either not processed by `build-worker`, or the conditional check was incorrect, causing the reference to an undefined global.","error":"ReferenceError: IS_CLOUDFLARE_WORKER is not defined"},{"fix":"Verify the `entry` path in your `package.json` script or programmatic configuration. Ensure the file exists and is accessible from where `build-worker` is run.","cause":"The entry point file specified (e.g., `worker.js`) does not exist at the given path relative to the current working directory, or `build-worker` lacks proper permissions.","error":"Error: Could not resolve 'worker.js' in '...' "},{"fix":"Consult `esbuild` documentation or the `build-worker` source for advanced configuration options. For JSX, ensure `jsxFactory` and `jsxFragment` are configured if needed.","cause":"Underlying esbuild configuration issues, often related to unsupported syntax (like JSX without configuration) or incorrect module resolution for specific dependencies within your worker code.","error":"Failed to load '...' (was: esbuild: The JSX factory option is not set. Consider `jsxFactory: 'React.createElement'`.)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"build-worker"}