Getting WebGPU-accelerated libraries working in DCP work functions
WebGPU compute itself works inside a DCP worker sandbox: adapters, devices, buffers, shader modules, compute pipelines and readback all behave as documented. What doesn’t automatically work is a library that wraps WebGPU with its own module-loading machinery, because that machinery assumes it runs in an ordinary web page, not in a sandbox with no page URL and no module loader. onnxruntime-web (ONNX Runtime for the web, the engine behind transformers.js) is the running example on this page. For ONNX Runtime there is a ready-made answer, the ort-webgpu-dcp package; the rest of the page explains what it solves, so you can apply the same approach to other libraries.
Step 0: Confirm the sandbox itself isn’t the problem
job.requirements.environment = { webgpu: true } is required for a slice to be scheduled onto a WebGPU-capable worker at all; without it, navigator.gpu doesn’t exist in the sandbox, by design. Bare WebGPU usage, with no external library, confirms the sandbox is sound:
async function workFunction() {
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const buf = device.createBuffer({
size: 64,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
});
device.queue.writeBuffer(buf, 0, new Float32Array(16));
// ... createShaderModule / createComputePipeline / dispatchWorkgroups / submit / mapAsync, same as any WebGPU code
return 'ok';
}
job.requirements.environment = { webgpu: true };
If a bare-WebGPU version of your work runs and a library on top of it doesn’t, the problem is the library’s module loading, not the sandbox.
ONNX Runtime: Use the ort-webgpu-dcp package
ort-webgpu-dcp is ONNX Runtime Web packaged for DCP work functions, with the native WebGPU execution provider and the WASM (CPU) execution provider. Version 1.31.1 contains onnxruntime-web 1.31.1. It has two files:
File |
Size |
Use it when |
|---|---|---|
|
38.5 MB |
You want it to run everywhere: browser and native workers. |
|
24 MB |
You target native workers (dcp-native 8 or later). It needs WebAssembly JSPI ( |
Require the file in the job, then require() it by its bare file name in the work function:
const compute = require('dcp/compute');
async function workFunction(modelBase64) {
const ort = require('ort-webgpu.js');
const bytes = Uint8Array.from(atob(modelBase64), (c) => c.charCodeAt(0));
const executionProviders =
typeof navigator !== 'undefined' && navigator.gpu ? ['webgpu'] : ['wasm'];
const session = await ort.InferenceSession.create(bytes, {
executionProviders,
});
// ... build ort.Tensor inputs and call session.run(feeds)
return session.outputNames;
}
const job = compute.for(inputSet, workFunction, [modelBase64]);
job.requires(['ort-webgpu-dcp/ort-webgpu.js']);
job.requirements.environment = { webgpu: true }; // leave out to also accept CPU-only workers
No other setup is needed. Each file is self-contained:
No module loading at run time. It’s built from the ONNX Runtime bundle entry, which has the WebAssembly glue code inline, so it never calls
import().No network fetch. The
.wasmbinary is embedded, so it never callsfetch(), which the sandbox’s origin rules would block.Sandbox settings applied.
env.wasm.numThreads = 1andenv.wasm.proxy = false: the sandbox has noSharedArrayBufferthreads and no nested workers.
Don’t set env.wasm.wasmPaths. Pointing it anywhere makes ONNX Runtime try to load its glue code with import(), which is exactly what the package avoids.
The package runs modern transformer models unmodified on WebGPU, including GroupQueryAttention with rotary embeddings and sliding-window attention. The older onnxruntime-dcp package (onnxruntime-web 1.21, JSEP execution provider) rejects those operators; prefer ort-webgpu-dcp for new work.
Note
A worker sends every module a slice requires to the sandbox in one message. Very large module sets, for example model weights published as packages alongside ONNX Runtime, fail with RangeError: Invalid string length once their combined size approaches the JavaScript string limit (about 512 MB of base64 text). Split large models across slices or jobs so each slice stays well under that.
Why WebGPU libraries break in the sandbox
A DCP work function runs from source text in a sandbox. The sandbox has no page URL to resolve relative paths against, and no module loader. Libraries such as ONNX Runtime assume both, in two places.
Dynamic import() of the WebAssembly glue
The regular ONNX Runtime entry points load a companion .mjs glue file at initialization with a dynamic import(). In a DCP sandbox this fails:
On native workers, the evaluator has no dynamic
import()support, and session creation fails withError: Not supported.In sandboxes hosted by a browser, a relative specifier has no base URL to resolve against:
TypeError: Failed to resolve module specifier './ort-wasm-simd-threaded.asyncify.mjs'.
The base URL is about:blank because import() is called from a CORS-cross-origin script.
This failure is commonly misdiagnosed. It’s not a blocked network request, so supplying the .wasm bytes through env.wasm.wasmBinary (the usual fix for the fetch() problem in Building WASM modules for DCP jobs) doesn’t help. The underlying error can also be caught and re-thrown deeper in the library, surfacing as something unrelated such as Cannot convert undefined to a BigInt.
An earlier workaround pointed env.wasm.wasmPaths.mjs at a data: URL holding the glue code. That still calls import(), so it fails on native workers. The reliable fix is to avoid import() entirely: use the library’s bundle entry point, which includes the glue inline, as ort-webgpu-dcp does.
Self-location at module load
The ONNX Runtime entry points also locate themselves when they load, through import.meta.url, document.currentScript or self.location. import.meta isn’t valid outside an ES module, and in the sandbox the other two are missing or not usable, so the module either fails to parse or throws Failed to construct 'URL': Invalid URL before any of your configuration runs.
The fix is at packaging time: replace those references with a fixed absolute URL. ort-webgpu-dcp uses a placeholder https: URL that ONNX Runtime never fetches from, because the .wasm bytes are embedded.
Packaging another library or version the same way
To package a different WebGPU-capable library, or another ONNX Runtime release, the steps that ort-webgpu-dcp follows are:
Start from the library’s bundle entry point, the one with its WebAssembly glue inlined (for ONNX Runtime,
dist/ort.webgpu.bundle.min.mjsordist/ort.jspi.bundle.min.mjs).Replace every
import.meta.urlwith a fixed absolute URL, and turn the trailingexport { ... }intomodule.exports, so the file is a plain script.Embed the
.wasmbinary as base64 and pass the decoded bytes to the library (for ONNX Runtime,env.wasm.wasmBinary), along with any sandbox settings such as a single thread.Wrap the result in
module.declare()and publish it as described in Publishing a DCP package.
Before dispatching, load the built file in Node through a small module.declare shim and run a tiny model on the WASM execution provider. Errors in steps 2 and 3 show up there in seconds instead of after a dispatch round trip.
A method for diagnosing a similar failure in a different library
If a WebGPU-capable library breaks with an unclear error inside a DCP sandbox, an escalation ladder isolates the layer at fault faster than debugging the failure in place:
Bare WebGPU, no library at all (the Step 0 example above). If this fails, the problem is in your job’s requirements or the sandbox’s WebGPU support, and everything below assumes this step passes.
The library’s lowest-level API, directly, for example
InferenceSession.create()from ONNX Runtime on a tiny model, with no framework on top. Loader failures surface here with their most specific error.The full framework, once step 2 works. Confirm it works the way your actual code will use it; there is often one more bundling wrinkle between “the raw library works” and “the framework built on it works.”
Dispatch each rung as its own minimal DCP job.
Note
This class of bug comes from the sandbox’s missing page URL and module loader, which an ordinary browser tab or a plain Web Worker has. Testing a library in a normal browser context, even in a dedicated Worker, will not reproduce it. To catch it locally, load the code through eval() or the Function() constructor rather than a <script> tag or module import.
What you have at this point
A WebGPU-capable library that initializes cleanly inside a DCP work function, with WebGPU actually doing the work rather than falling back to the CPU or crashing. Whether to request WebGPU is a separate question: WebGPU-capable workers are a smaller pool than CPU-only ones, because job.requirements.environment.webgpu restricts scheduling to workers that report GPU capability. Request it for workloads that benefit from GPU acceleration, not by default.