{"record":{"id":"410705585aa98802","repo":"evanw/esbuild","slug":"the-serve-api-is-not-supported-when-using-webass","errorCode":null,"errorMessage":"The \"serve\" API is not supported when using WebAssembly","messagePattern":"The \"serve\" API is not supported when using WebAssembly","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/api/serve_wasm.go","lineNumber":11,"sourceCode":"//go:build js && wasm\n// +build js,wasm\n\npackage api\n\nimport \"fmt\"\n\n// Remove the serve API in the WebAssembly build. This removes 2.7mb of stuff.\n\nfunc (*internalContext) Serve(ServeOptions) (ServeResult, error) {\n\treturn ServeResult{}, fmt.Errorf(\"The \\\"serve\\\" API is not supported when using WebAssembly\")\n}\n\ntype apiHandler struct {\n}\n\nfunc (*apiHandler) broadcastBuildResult(BuildResult, map[string]string) {\n}\n\nfunc (*apiHandler) stop() {\n}\n","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/pkg/api/serve_wasm.go#L1-L22","documentation":"The serve API (ctx.serve()) is intentionally stripped from the WebAssembly build of esbuild to save approximately 2.7MB of binary size. The serve_wasm.go file replaces the Serve method with a stub that always returns this error. This is a compile-time platform restriction, not a runtime misconfiguration.","triggerScenarios":"Using the esbuild-wasm package and calling ctx.serve(...) on a context created via esbuild-wasm's context() function.","commonSituations":"Switching from the native 'esbuild' package to 'esbuild-wasm' for browser/wasm compatibility without updating code that calls serve(), or environments that require the wasm build but still reference serve mode.","solutions":["Use the native 'esbuild' package instead of 'esbuild-wasm' if you need serve mode","Implement your own HTTP server that wraps esbuild-wasm's build() output","Detect the wasm environment at runtime and skip serve calls, providing an alternative dev server"],"exampleFix":"// before\nimport * as esbuild from 'esbuild-wasm'\nconst ctx = await esbuild.context(opts)\nawait ctx.serve({ port: 8000 })\n// after\nimport * as esbuild from 'esbuild'\nconst ctx = await esbuild.context(opts)\nawait ctx.serve({ port: 8000 })","handlingStrategy":"type-guard","validationCode":"import * as esbuildNative from 'esbuild'\nimport * as esbuildWasm from 'esbuild-wasm'\nconst isWasm = typeof WebAssembly !== 'undefined' && typeof window !== 'undefined'\nconst esbuild = isWasm ? esbuildWasm : esbuildNative\nif (isWasm) {\n  console.warn('Serve API is not available in the WebAssembly build')\n}","typeGuard":"function isServeSupported(esbuildModule) {\n  // The wasm build stubs Serve to always error; check by feature-detecting\n  return typeof esbuildModule.serve !== 'undefined' &&\n    esbuildModule.toString().indexOf('wasm') === -1\n}\n// Or detect the wasm package directly:\nconst isWasmBuild = esbuild.versions?.wasm === true","tryCatchPattern":"try {\n  await ctx.serve(serveOptions)\n} catch (e) {\n  if (e.message.includes('not supported when using WebAssembly')) {\n    console.warn('Serve not available in WASM; falling back to manual server')\n    // implement alternative dev server\n  } else {\n    throw e\n  }\n}","preventionTips":["Detect whether you are using esbuild or esbuild-wasm before calling serve","Use the native esbuild package when serve mode is required","Implement a fallback HTTP server for wasm-only environments"],"tags":["esbuild","wasm","serve","platform"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}