{"record":{"id":"40281503b4ccb44c","repo":"evanw/esbuild","slug":"cannot-use-the-watch-api-in-this-environment","errorCode":null,"errorMessage":"Cannot use the \"watch\" API in this environment","messagePattern":"Cannot use the \"watch\" API in this environment","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/shared/common.ts","lineNumber":1068,"sourceCode":"                  // In that situation we didn't get an \"on-end\" message since\n                  // Go thought it wasn't necessary. In that situation, we\n                  // trigger another rebuild below so that Go will (almost\n                  // surely) send us an \"on-end\" message next time. I suspect\n                  // that this is a very rare case, so the performance impact\n                  // of building twice shouldn't really matter. It also only\n                  // happens when \"rebuild()\" is used with \"watch()\" and/or\n                  // \"serve()\".\n                  triggerAnotherBuild()\n                }\n              })\n            }\n            triggerAnotherBuild()\n          })\n          return latestResultPromise\n        },\n\n        watch: (options = {}) => new Promise((resolve, reject) => {\n          if (!streamIn.hasFS) throw new Error(`Cannot use the \"watch\" API in this environment`)\n          const keys: OptionKeys = {}\n          const delay = getFlag(options, keys, 'delay', mustBeInteger)\n          checkForInvalidFlags(options, keys, `in watch() call`)\n          const request: protocol.WatchRequest = {\n            command: 'watch',\n            key: buildKey,\n          }\n          if (delay) request.delay = delay\n          sendRequest<protocol.WatchRequest, null>(refs, request, error => {\n            if (error) reject(new Error(error))\n            else resolve(undefined)\n          })\n        }),\n\n        serve: (options = {}) => new Promise((resolve, reject) => {\n          if (!streamIn.hasFS) throw new Error(`Cannot use the \"serve\" API in this environment`)\n          const keys: OptionKeys = {}\n          const port = getFlag(options, keys, 'port', mustBeValidPortNumber)","sourceCodeStart":1050,"sourceCodeEnd":1086,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L1050-L1086","documentation":"Thrown by the context's `watch()` method (lib/shared/common.ts:1068) when `streamIn.hasFS` is false. Watch mode monitors source files for changes and triggers rebuilds, which fundamentally requires filesystem access. The browser/WASM build sets `hasFS: false` (lib/npm/browser.ts:142), so watch is unavailable there.","triggerScenarios":"Creating a build context via the browser/WASM esbuild API and then calling `context.watch()` on the returned context object.","commonSituations":"Reusing a dev-server/watch script that worked in Node inside a browser playground; building a web-based live-reload tool around esbuild-wasm.","solutions":["Use the native node esbuild package where `hasFS` is true so `watch()` works.","Implement your own change detection at a higher level (e.g. re-run `rebuild()` on external events) instead of relying on esbuild's `watch()`.","Guard the `watch()` call with an environment check and skip it in browser contexts."],"exampleFix":"// before\nconst ctx = await esbuild.context(opts);\nawait ctx.watch();\n// after (browser/wasm — watch not supported)\nconst ctx = await esbuild.context(opts);\nawait ctx.rebuild();\n// implement your own change triggering around ctx.rebuild()","handlingStrategy":"validation","validationCode":"const canWatch = typeof process !== 'undefined' && !!process.versions && !!process.versions.node;\nif (canWatch) await ctx.watch();","typeGuard":"function supportsWatch(): boolean {\n  return typeof process !== 'undefined' && !!process.versions && !!process.versions.node;\n}","tryCatchPattern":null,"preventionTips":["Keep watch-mode scripts in a Node-only entry point.","Guard dev-server features behind an environment check for browser playgrounds."],"tags":["environment","filesystem","browser","wasm","watch"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}