{"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/6ff1d8b0d8c134e867a397eef39702a223ebef9e/pkg/api/serve_wasm.go#L1-L22","documentation":"Returned by the WebAssembly build of esbuild's API (pkg/api/serve_wasm.go, compiled with //go:build js && wasm). The serve API spins up a TCP listener, which is impossible in a browser/WASM environment (no raw sockets). To save ~2.7MB, the WASM build stubs out Serve() to always return this error. There is no way to enable serving from the browser bundle.","triggerScenarios":"Importing esbuild's WASM package (esbuild-wasm) and calling context.Serve(...) or the serve API. The WASM-only Serve override at serve_wasm.go:11 unconditionally returns the error.","commonSituations":"Using esbuild-wasm in the browser and attempting to start a dev server; code written against the native esbuild that is later pointed at the wasm build; a feature-detection gap where serve is called without checking the runtime.","solutions":["Use the native (non-WASM) esbuild package if you need the serve API.","Feature-detect: do not call Serve() when running under WASM.","Run your own HTTP server in Node/host and use esbuild-wasm only for bundling.","Branch your code: serve with native esbuild, build-only with wasm."],"exampleFix":"// before (browser)\nimport * as esbuild from 'esbuild-wasm';\nawait esbuild.context(opts).Serve({ port: 8000 }); // not supported\n\n// after\nimport * as esbuild from 'esbuild'; // native build\nawait esbuild.context(opts).Serve({ port: 8000 });","handlingStrategy":"validation","validationCode":"const isWasm = typeof WebAssembly !== 'undefined' && /wasm/i.test(esbuild.version || '');\nif (isWasm) throw new Error('serve API unsupported in WASM; use native esbuild');","typeGuard":"function isWasmServeUnsupportedError(e) { return /serve.*not supported.*WebAssembly/.test(e?.message || ''); }","tryCatchPattern":"try { await ctx.Serve(opts); } catch (e) { if (isWasmServeUnsupportedError(e)) { /* switch to native esbuild or skip serving */ } throw e; }","preventionTips":["Use native esbuild (not esbuild-wasm) when you need serve.","Feature-detect the runtime before calling Serve().","Run your own HTTP server and use WASM only for bundling.","Branch code paths for browser vs Node."],"tags":["esbuild","serve","wasm","browser","platform"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}