doe-gpu

doe-gpu is the npm package for Doe, a Zig-first WebGPU runtime for Node.js, Bun, and Deno.

It gives you a small JavaScript layer over the native Doe runtime, plus focused subpaths for compute, browser, and hybrid use cases. The package is built for people who want a leaner, explicit WebGPU runtime outside the browser.

Install

npm install doe-gpu

Why use it

• Small JS layer over the native Doe runtime
• Faster on modern consumer hardware
• Explicit failure instead of silent fallback
• One package surface across Node.js, Bun, and Deno
• Browser shim available when you want API compatibility rather than runtime replacement

Current evidence

End to end Gemma 3 inference. Positive percentages mean Doe is faster vs Dawn via Node webgpu and Bun bun-webgpu packages.

Outputs:

• Node package, AMD Vulkan: benchmark output
• Bun package, AMD Vulkan: benchmark output
• Node package, Apple Metal: benchmark output
• Bun package, Apple Metal: benchmark output

Additional benchmark outputs

ONNX Runtime (ORT) lanes and broader follow-up work live in the repo status page. Read docs/status.md for the current scope and artifacts.

Usage

import { gpu } from "doe-gpu";

const device = await gpu.requestDevice();
const result = await device.compute({
  code: `@group(0) @binding(0) var<storage, read_write> data: array<f32>;
         @compute @workgroup_size(64) fn main(@builtin(global_invocation_id) id: vec3u) {
           data[id.x] = data[id.x] * 2.0;
         }`,
  inputs: [new Float32Array([1, 2, 3, 4])],
  output: { type: Float32Array, size: 16 },
  workgroups: 1,
});

Subpaths

• doe-gpu: default native-runtime surface
• doe-gpu/compute: narrower compute-focused surface
• doe-gpu/browser: browser wrapper over the browser's built-in WebGPU runtime
• doe-gpu/hybrid: hybrid/local fallback surface

Runtime requirements

• Node.js 18+ for the default package surface
• a matching optional platform package or a built/preinstalled Doe native library
• Bun and Deno are supported through the package entrypoints in exports

The doe-gpu package is the JS front door. Native artifacts are expected to arrive through one of these paths:

• npm-installed optional platform packages such as doe-gpu-darwin-arm64 and doe-gpu-linux-x64
• a local workspace build under runtime/zig/zig-out/
• explicit DOE_WEBGPU_LIB / DOE_LIB overrides
• local debug prebuilds under packages/doe-gpu/prebuilds/<platform-arch>/

If the native addon or shared library is missing, the package fails explicitly instead of silently falling back to another runtime.

Publish packaging

Cross-platform npm install support is package-based, not host-magic:

• doe-gpu publishes the JS wrapper and declares optional platform packages
• doe-gpu-<platform>-<arch> publishes the native bin/ payload for that host

The platform package bin payload includes:

• doe_napi.node
• libwebgpu_doe.<dylib|so> or webgpu_doe.dll
• doe-build-metadata.json
• metadata.json

Before publishing a platform package, stage its bin/ directory from a built workspace:

cd packages/doe-gpu-darwin-arm64
npm run stage

Release order matters:

1. Build the native artifacts on the target host for each platform package.
2. Bump doe-gpu-<platform>-<arch> to the release version it will publish.
3. Run npm run stage in that platform package.
4. Verify packages/doe-gpu with npm run test:smoke, npm run test:integration, and npm pack --dry-run.
5. Publish the platform package versions first. On Apple, publish doe-gpu-darwin-arm64 only after Linux is already published.
6. Publish doe-gpu only after every platform package version referenced in its optionalDependencies is already live on npm.

Important distinction

The default package, /compute, and /hybrid subpaths are Doe native-runtime surfaces.

doe-gpu/browser is different. It wraps the browser's incumbent WebGPU implementation so code written against doe-gpu can run in a browser, but it does not mean Doe has replaced the browser runtime.

Repo-adjacent surfaces

createDoeRuntime() and runDawnVsDoeCompare() remain available for repo-adjacent environments that already have Doe runtime or compare assets.

Deeper runtime internals, benchmark workflows, and status live in the repo:

• repo overview: README.md
• runtime internals: runtime/zig/README.md
• benchmarks and evidence: bench/README.md
• current status: docs/status.md
• browser integration: browser/chromium/README.md

Legacy package names

These legacy package names are deprecated in favor of doe-gpu:

• @simulatte/webgpu
• @simulatte/webgpu-doe

License

Apache-2.0. See docs/licensing.md.