Sailfish Map Utilities

Supported Platforms

• [ ] Cloudflare workers ("Wrangler") - requires manual effort: upload-sourcemap-to-sailfish ${api_key} must be called before your build
• [ ] Vite watch mode (vite --watch) requires manual effort

Canvas worker-shim auto-injection (injectWorkerShim)

Customers whose Web Worker renders into a transferred OffscreenCanvas must otherwise hand-add import "@sailfish-ai/recorder/canvas-worker"; at the very top of that worker so the canvas-recorder hooks install before the worker grabs its 2D/WebGL context. Setting the opt-in injectWorkerShim plugin option performs that prepend automatically for detected worker-entry modules.

• Off by default. Pass injectWorkerShim: true to inject the default specifier (@sailfish-ai/recorder/canvas-worker), or injectWorkerShim: { importSpecifier: "..." } for a custom one.
• Idempotent. It never double-injects — including when the customer already added the import by hand (any import form: bare, named, default, namespace, or require).
• Conservative heuristic. A module is treated as a worker entry when its id matches *.worker.{ts,tsx,js,jsx,mts,mjs}, or the source installs a message handler on the worker global scope and references OffscreenCanvas/transferControlToOffscreen/a 2D|webgl getContext. A false positive is inert (the shim does nothing until the SDK starts recording); a false negative just reverts to the hand-added import.

All five bundler entrypoints share the same implementation (stamping/workerShim.ts → maybeInjectWorkerShim):

| Bundler | Draw-site stamping | injectWorkerShim | | --- | --- | --- | | Vite (./vite) | yes | yes | | webpack (./webpack) | yes | yes (threaded to the enforce:'pre' stamp loader) | | Rollup (./rollup) | yes | yes | | esbuild (./esbuild) | yes | yes | | tsc transformer (./transformer) | yes | n/a (worker-shim handled by the bundler plugins above) |

Unsupported / partial bundlers

• Next.js Turbopack — Next 15 makes Turbopack the default dev compiler, and it can be opted into for builds. Turbopack does not run SWC wasm plugins and ignores experimental.swcPlugins, so neither click-to-code stamping nor worker-shim injection happen on the Turbopack path. Use the webpack build for anything you want stamped (next build --webpack / drop --turbo), or fall back to the recorder's runtime canvas hooks. @sailfish-ai/sf-swc-plugin's withSailfish() helper detects Turbopack and warns/throws accordingly — see that package's README.
• Parcel — no Sailfish plugin exists for Parcel today; it is unsupported. Parcel projects should migrate the relevant build to one of the supported bundlers above, or rely on the recorder's runtime fallback for canvas capture.