🌐 Canonical repository is on GitHub —
codecloud-dev/moxwebgpuis the single source of truth: please file all issues and pull requests there. The Gitee mirror is a read-only copy synced hourly for faster access in mainland China.
English · 中文 · 📖 Docs · 🚀 Live demo
⭐ If moxwebgpu is useful to you, please give it a star — it helps more people run GPU compute in the browser!
This is an early-stage project — bugs exist, and probably plenty of them. I'm not pretending it's perfect. Every pitfall you hit and every gripe you have is a chance to help make it better.
- 💥 Crashed / black screen / won't run? → File a bug report
- 💡 Want a feature? → Open a feature request
- 🗯️ Just want to rant or nitpick? → Issues are welcome too, label it whatever 😄
I read every issue and fix what I can, fast. Let's grow this from "runs" to "delightful" 💪
📑 目录 · Contents
Raw WebGPU compute is powerful but brutal: adapter/device boilerplate, WGSL pipelines, bind groups, manual buffer lifecycles, staging readbacks — and validation errors are silent (a broken shader just turns your dispatch into a no-op and your output into zeros).
moxwebgpu = MoX + WebGPU: a WebGPU general-purpose compute (GPGPU) framework. It wraps all of the boilerplate behind three layers:
Tensor gpu.tensor([1,2,3]).add(1).relu().sum().item() ← the only layer you touch
Lazy graph topo-sorted, one submit, refcount-recycled buffers
Core BufferPool (power-of-two buckets) · PipelineCache (WGSL hash) · raw Kernel
- One unified API — reductions, broadcasting and elementwise ops share one calling convention
- Lazy by default — a whole chain dispatches once on
.item(); intermediates never leak - 30+ GPU ops — elementwise, two-phase tree reductions, argmax/argmin, 16×16-tiled matmul, fused softmax, strided slicing/concat, zero-copy reshape
- Reverse-mode autodiff built in —
.withGrad()/.backward()fill.gradlazily; train models entirely in the browser (since v1.0) - Silent-failure defense — shader compile errors surfaced with line/column via
getCompilationInfo() - 99 passing tests — 66 unit tests (CPU-only,
pnpm test) + 33 GPU e2e (value-compared against CPU references), green even on GPU-less machines via SwiftShader + xvfb - Zero runtime dependencies, ESM + CJS + IIFE + d.ts, ~30 KB browser bundle
moxwebgpu is a standalone open-source library: rebuilding, properly, the WebGPU general-purpose compute capability that "should be simple" in the browser.
| Project | Status | One-liner |
|---|---|---|
| moxwebgpu | live (this repo) | WebGPU GPGPU framework |
✅ Published to npm: package name
@codecloud-dev/moxwebgpu(currentversion: 1.1.4). OIDC token-less publish flow is wired up (.github/workflows/publish.yml). Install via npm below, or build from source.
Browser <script> (zero build):
<script src="https://unpkg.com/@codecloud-dev/moxwebgpu/dist/moxwebgpu.browser.js"></script>
<script>
const gpu = await MoxWebGPU.mox.init();
console.log(await gpu.tensor([1, 2, 3]).sum().item()); // 6
</script>npm (Node / bundlers):
npm install @codecloud-dev/moxwebgpu # pnpm add @codecloud-dev/moxwebgpu / yarn add @codecloud-dev/moxwebgpuimport { mox } from '@codecloud-dev/moxwebgpu'; // ESM
// const { mox } = require('moxwebgpu'); // CJSFrom source:
git clone https://github.com/codecloud-dev/moxwebgpu.git
cd moxwebgpu && pnpm install && pnpm buildWebGPU requires a secure context:
localhostor https. Chrome/Edge 113+ ship it by default.
const gpu = await mox.init();const r = await gpu.tensor([1, 2, 3, 4])
.add(1).relu().mul(10).sum().item(); // 140 — dispatches onceconst A = gpu.tensor([[1, 2, 3], [10, 20, 30]]); // [2,3]
await A.add(gpu.tensor([1, 2, 3])).toArray(); // row broadcast
await A.mul(gpu.tensor([2, 3])).toArray(); // col broadcast
await A.add(gpu.tensor([1, 2])); // ❌ throws — no implicit broadcastingawait gpu.tensor([[1, 2], [3, 4]]).matmul(gpu.tensor([[5, 6], [7, 8]])).toArray();
// [19, 22, 43, 50] — 16×16 workgroup tiling
const x = gpu.tensor([[1, 2, 3, 4], [5, 6, 7, 8]]);
await x.sum().item(); // 36 global → [1]
await x.sum(-1).toArray(); // [10, 26] last axis
await x.sum(0).toArray(); // [6, 8, 10, 12] axis 0 → [4]
const t3 = gpu.tensor(Array.from({ length: 24 }, (_, i) => i), { shape: [2, 3, 4] });
await t3.sum(1).toArray(); // [12,15,18,21,48,51,54,57] — any axis of any rank; negative axes count from the end
await x.max().item(); // 8
await x.argmax().item(); // 7 (first occurrence wins)
await x.softmax().toArray(); // numerically stable, row sums = 1await v.slice(2, 4).toArray(); // strided slice (≤4D)
await a.concat(b, 0).toArray(); // concat on any axis
const w = v.reshape([2, 5]); // zero-copy view
await gpu.tensor([1.7, -3.9]).cast('i32').toArray(); // [1, -3] (trunc toward zero)t.max() // global reduce → [1]
t.max(-1) // reduce along last axis (any axis works: t.max(0), t.sum(-2), …)
t.max(other) // elementwise with another tensor
// unambiguous aliases: maxReduce / minReduceSince v1.0 moxwebgpu ships reverse-mode automatic differentiation layered directly on top of the lazy graph — an OpDef is pure metadata + codegen, each op carries a backward, and the reverse graph reuses the same ops. The GPU is touched only when you read a gradient.
import { mox } from '@codecloud-dev/moxwebgpu';
const gpu = await mox.init();
const x = gpu.tensor([1, 2, 3, 4]).withGrad(); // mark a differentiable leaf
const loss = x.mul(x).sum(); // L = Σ x²
loss.backward(); // backprop
console.log(await x.grad.toArray()); // [2, 4, 6, 8] = dL/dxThree things to know:
.withGrad(): marks a leaf as requiring gradients (other leaves are skipped by default)..backward(): walks the scalar loss in reverse-topological order, filling.gradon everyrequiresGradleaf. The whole pass only builds the lazy graph — it never touches the GPU until youawait x.grad.toArray().- Broadcast-correct: binary-op gradients use
sumToto reduce back to the smaller operand's shape;sum/mean/softmaxgradients broadcast back viaexpand.
// A minimal linear layer, forward + backward
const W = gpu.tensor([[0.1, 0.2], [0.3, 0.4]]).withGrad();
const inp = gpu.tensor([1, 1]);
const pred = W.matmul(inp); // [2]
const loss = pred.mul(pred).sum(); // Σ pred²
loss.backward();
console.log(await W.grad.toArray()); // dL/dW, same shape as WOps with a registered backward: add/sub/mul/div (scalars and broadcast included), neg/abs/exp/log/sqrt/square/relu/sigmoid/tanh, matmul, sum/mean (global and any axis), softmax (last axis, numerically stable).
On the roadmap: layernorm / embedding / conv1d, pass fusion, Web Worker execution — planned for 1.0.x, not in this release.
This is moxwebgpu's most underrated capability: it doesn't just do one-off GPGPU compute — it runs a full autodiff + gradient-descent training loop right in the browser. Data never leaves the page, no backend required; any laptop / phone / Raspberry Pi with WebGPU can train. Combined with the
<script>-tag SDK above, any site can let a visitor's GPU train a small model on the spot.
The core logic below trains linear regression (least squares / MSE); the gradients really are computed on the GPU:
const gpu = await mox.init();
const X = gpu.tensor([[0], [1], [2], [3]]);
const Y = gpu.tensor([[1], [3], [5], [7]]); // y ≈ 2x + 1
const lr = 0.05;
let W = gpu.tensor([[0]]).withGrad(); // differentiable parameters
let b = gpu.tensor([[0]]).withGrad();
for (let step = 0; step < 200; step++) {
const pred = X.matmul(W).add(b); // ŷ = X·W + b
const diff = pred.sub(Y);
const loss = diff.mul(diff).mean(); // MSE
loss.backward(); // gradients fill W.grad / b.grad (lazy, still on graph)
// Hand-written SGD: read the updated values back, then rebuild differentiable leaves.
W = gpu.tensor(await W.sub(W.grad.mul(lr)).toArray()).withGrad();
b = gpu.tensor(await b.sub(b.grad.mul(lr)).toArray()).withGrad();
}
console.log('trained W, b =', await W.toArray(), await b.toArray()); // ≈ [[2]], [[1]]- Forward and backward stay on the lazy graph:
backward()only builds the graph and fills.grad; nothing is dispatched until youawait ...toArray()— no per-step CPU↔GPU round-trips. - No built-in optimizers yet: training hand-writes
W = W - lr * W.gradas above.SGD / Adamare on the roadmap. - Trainable leaves need
withGrad(): only marked leaves accumulate.grad, saving GPU memory.
🔥 Two-layer MLP (hidden layer + sigmoid)
Linear regression is one line; real models are multi-layer. The same hand-written SGD trains a two-layer MLP (input → hidden sigmoid → output):
const w1 = gpu.tensor([[0.1, -0.2], [0.3, 0.4]]).withGrad();
const b1 = gpu.tensor([0.0, 0.0]).withGrad();
const w2 = gpu.tensor([[0.2], [-0.1]]).withGrad();
const b2 = gpu.tensor([0.0]).withGrad();
const x = gpu.tensor([[1, 0], [0, 1]]);
const y = gpu.tensor([[1], [0]]);
for (let i = 0; i < 300; i++) {
const h = x.matmul(w1).add(b1).sigmoid();
const pred = h.matmul(w2).add(b2);
const diff = pred.sub(y);
diff.mul(diff).mean().backward(); // autodiff handles matmul / bias / sigmoid / broadcast
w1 = w1.sub(w1.grad.mul(lr)); b1 = b1.sub(b1.grad.mul(lr));
w2 = w2.sub(w2.grad.mul(lr)); b2 = b2.sub(b2.grad.mul(lr));
}Backprop handles matmul / bias add / sigmoid / broadcast automatically — you only write the forward pass, one backward(), and the parameter update.
const k = gpu.kernel(`
@group(0) @binding(0) var<storage, read> a: array<f32>;
@group(0) @binding(1) var<storage, read_write> b: array<f32>;
@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid: vec3u) {
b[gid.x] = a[gid.x] * 2.0 + 1.0;
}`);
const a = gpu.tensor([1, 2, 3, 4, 5]);
const out = gpu.pool.acquire(5, 'f32'); // GpuDataBuffer, elements = 5
// Pass the GpuDataBuffer (not .buffer): readback length follows buf.elements → exactly 5
const res = await k.run([a.data, out], { elements: 5 }); // → Float32Array(5) [3, 5, 7, 9, 11]k.run() = dispatch + readback in one call; k.dispatch() dispatches only. Custom WGSL goes through the same pipeline cache and compile checks.
Readback length:
run()prefers theGpuDataBuffer.elementscount of pooled output buffers (the raw GPUBuffer is rounded up to a power-of-two bucket, so reading its full size would include padding). A bareGPUBufferfalls back to its raw size.
| Option | Type | Notes |
|---|---|---|
adapter |
GPUAdapter |
skip requestAdapter |
powerPreference |
'low-power' | 'high-performance' |
|
requestAdapterOptions |
GPURequestAdapterOptions |
passthrough |
| Member | Notes |
|---|---|
tensor(data, opts?) |
nested arrays / TypedArray; opts.shape optional |
kernel(code, opts?) |
workgroupSize / entryPoint / output / dtype |
readback(buf) |
GPU buffer → CPU TypedArray |
info() |
{ vendor, architecture, device, description } |
pool / pipelines / scheduler |
advanced |
destroy() |
release everything |
| Category | Members |
|---|---|
| Props | shape ndim dtype size |
| Shape | reshape(...dims | number[]) zero-copy (-1 ok), transpose() (2D) |
| Binary | add sub mul div pow (Tensor or scalar), rsub rdiv |
| Unary | neg abs exp log sqrt sin cos tanh floor ceil relu sigmoid square sign |
| Reduce | sum mean max min (no arg = global; -1/0 = axis; max(t) = elementwise), argmax argmin (→ u32) |
| Range | clamp(lo, hi), slice(start, size) (≤4D), concat(other, axis?) |
| NN | softmax() |
| Dtype | cast('f32' | 'i32' | 'u32'), toFloat() |
| Readback | await toArray() / await toBuffer() / await item() |
| Release | destroy() |
| API | Notes |
|---|---|
k.run(buffers, { elements } | { workgroups }) |
dispatch + readback |
k.dispatch(buffers, [wx, wy, wz]) |
dispatch only |
pool.acquire(elements, dtype) / acquireUniform(bytes) |
strictly separate pools |
pool.release / releaseUniform / live / pooled / clear() |
stats & teardown |
| Family | Ops | GPU strategy |
|---|---|---|
| Elementwise | add sub mul div pow min max clamp + rsub rdiv | 1D / 2D row/col broadcast uniforms |
| Unary (14) | neg abs exp log sqrt sin cos tanh floor ceil relu sigmoid square sign | single pass |
| Global reduce | sum mean max min argmax argmin | two-phase tree (wg=64, chunk=8) |
| Axis reduce | sum(-1), 2D sum(0) (via transpose) |
one workgroup per row |
| Matrix | matmul | 16×16 tile, workgroup-memory accumulation |
| Shape | transpose (2D), slice (≤4D), concat, reshape (zero-copy) | generic ND gather/copy (vec4 uniforms) |
| NN | softmax | fused 3-pass per row |
| Dtype | cast f32↔i32↔u32 | single pass, truncation |
| Autodiff | .withGrad() / .backward() / .grad on differentiable leaves |
reverse graph reuses forward ops, broadcast-correct via sumTo/expand, GPU touched only on read |
| dtype | WGSL | bytes | readback |
|---|---|---|---|
f32 |
f32 |
4 | Float32Array |
i32 |
i32 |
4 | Int32Array |
u32 |
u32 |
4 | Uint32Array |
All uniform blocks are 16-byte aligned; copy-family kernels use a 64-byte vec4-based block. Two hard-won lessons are baked into the design — see docs/ARCHITECTURE.md §8:
- ±Infinity is illegal in WGSL const-expressions → reduction identities ride in a uniform slot at runtime.
- Array strides in the uniform address space are inconsistently implemented across backends; vec4 member layout is not → copy kernels use vec4 dimensions (208 B → 64 B, too).
WebGPU validation errors don't throw — objects go invalid, dispatches become no-ops. moxwebgpu's PipelineCache calls getCompilationInfo() after creating every ShaderModule and turns compile errors into readable line/column messages.
| Error (excerpt) | Meaning |
|---|---|
moxwebgpu: WebGPU is not available here... |
no secure context / unsupported browser |
moxwebgpu: no suitable GPU adapter |
adapter blocked; update drivers |
moxwebgpu: broadcast failed ... |
shapes neither equal nor broadcastable |
moxwebgpu: slice range [...] out of bounds |
slice OOB |
moxwebgpu: axis ... reduce is not supported |
this op has no axis-reduce form (e.g. argmax); omit the argument for a global reduce |
moxwebgpu: mean requires f32 input |
mean is f32-only; cast integers first (cast('f32')) |
pnpm bench, medians on SwiftShader (pure-CPU GPU emulation, same env as CI), full dispatch + readback path:
| Workload | Time | Throughput |
|---|---|---|
| add 1M f32 (scalar) | tens of ms | — |
| matmul [512×512]·[512×512] | ~890 ms | ~0.3 GFLOP/s |
| sum 1M f32 (two-phase tree) | ~69 ms | — |
| add→relu→mul→sum 1M chain | ~285 ms | — |
SwiftShader emulates a GPU on CPU — treat these as cross-regression numbers only. On real hardware the same code typically runs 10–100× faster.
Built-in performance design: lazy graph (one readback per chain), refcounted intermediates + power-of-two buckets (near-zero steady-state allocation), WGSL-hash pipeline cache.
| Suite | Count | Coverage |
|---|---|---|
tests/unit/ |
66 | byte-level uniform encoders, WGSL codegen, topo sort, OpDef shapes, autograd, regression |
tests/gpu/ |
33 | elementwise / broadcast / unary chains / lazy chains / matmul ×3 / all reductions / argmax / softmax / slice / concat / reshape views / deep pipelines / raw Kernel |
tests/gpu/bench/ |
bench | elementwise / matmul / reduce / chain (medians) |
GPU cases are value-compared against CPU reference implementations — not "didn't crash" tests.
# xvfb supplies a virtual display; Chrome's SwiftShader Vulkan ICD is the GPU
export VK_ICD_FILENAMES=/opt/google/chrome/vk_swiftshader_icd.json
# full Chromium (headless-shell has WebGPU stripped) + key flags
chromium --enable-unsafe-webgpu --enable-features=Vulkan --no-sandbox
# must load an https (or localhost) page for a secure contexttests/gpu/harness.ts automates all of it: detect Chrome + ICD → launch → open https page → inject dist/moxwebgpu.browser.js → run each case in-page and compare against CPU references. GitHub Actions runs the same recipe (.github/workflows/ci.yml).
| Command | What it does |
|---|---|
pnpm build |
tsup → ESM / CJS / IIFE + d.ts |
pnpm test |
66 unit tests |
pnpm test:gpu |
33 GPU e2e (auto SwiftShader/xvfb) |
pnpm test:all |
both |
pnpm bench |
micro-benchmarks |
pnpm demo |
build + serve the demo page (:5173) |
pnpm exec tsc --noEmit |
type check |
🌐 Try it live (no install):https://codecloud-dev.github.io/moxwebgpu/demo/ — your GPU, computing in front of you.
examples/browser/index.html is a self-contained liquid-glass demo — aurora ambient light, cursor-following glow, glass cards with backdrop filters. Four cards, all genuinely running on WebGPU: chained ops, 128² matmul, softmax with row-sum check, 1M-element reductions.
pnpm demo # → http://localhost:5173moxwebgpu/
├── src/
│ ├── index.ts # exports + installTensorOps + version
│ ├── core/ # context · dtype · buffer(pool) · kernel
│ ├── graph/ # lazy(DAG/OpDef) · pipelineCache · scheduler
│ └── tensor/ # tensor.ts · codegen.ts · ops/{elementwise,reduce,matmul,shape,nn}
├── tests/
│ ├── unit/ # unit tests (core / autograd / regression, 66 total)
│ └── gpu/ # harness · ref(CPU) · 3 suites + bench/
├── scripts/run-gpu-tests.sh # VK_ICD + xvfb wrapper
├── examples/browser/index.html # liquid-glass demo
├── docs/ARCHITECTURE.md # deep dive: uniforms, scheduler, post-mortems
├── assets/logo.svg # liquid-glass logo
└── .github/workflows/ci.yml # CI: typecheck + build + unit + SwiftShader e2e
Want to add an op? OpDef = pure metadata (shape inference + codegen) → two to five steps, see docs/ARCHITECTURE.md §5.
- v0.1 — three-layer architecture, 30+ ops, 33 real GPU e2e tests, liquid-glass demo
- v0.2 — arbitrary-axis reductions (any rank / negative axes), integer reduction fixes, scheduler temp recycling
- v1.0 — reverse-mode autodiff on the lazy graph, backward for matmul/softmax/sum/mean, token-free OIDC publishing to npm
- npm first publish (
@codecloud-dev/moxwebgpu, currently1.1.4) + docs site live - More NN ops: layernorm / embedding / conv1d
- Adjacent-elementwise op pass fusion (fewer dispatches)
- Run inside a Web Worker / OffscreenCanvas
- f16 / bf16 dtypes, SGD / Adam optimizers
- tensor-core-friendly matmul (double buffering), ecosystem integrations
Q: My browser console says navigator.gpu is undefined?
A: WebGPU needs Chrome/Edge 113+ and a secure context (https or localhost). Opening via file:// won't work — use pnpm demo to start a local server.
Q: Results are all zeros / garbage?
A: 99% of the time it's a silent WGSL compile failure (no-op). moxwebgpu prints compile errors to the console with line/column numbers — fix the shader accordingly. Using the built-in ops avoids this entirely.
Q: How does this relate to TensorFlow.js / transformers.js?
A: They are model-centric — prebuilt models for inference. moxwebgpu is op-centric — NumPy-like raw compute power plus an escape hatch, exactly the general GPGPU foundation they don't provide.
Q: Does it support training (backprop)?
A: Yes. Since v1.0 reverse-mode autodiff is built in: call .withGrad() on leaves, build the forward graph, then .backward() fills .grad (lazily — GPU is touched only on read). See Autodiff.
Q: Why does pnpm test:gpu pass on my machine — I don't have an NVIDIA card?
A: SwiftShader — Chrome's pure-software Vulkan implementation. The GPU test recipe does not require a real GPU, and CI runs the same way.
Q: Do i32/u32 multiplies overflow?
A: They follow WGSL semantics (bitwise wrap-around). Reduction identities, encoders, and readback views all handle this per dtype.
Issues and PRs welcome. Keep PRs focused; add tests for behavior changes. GPU-affecting changes should run pnpm test:gpu locally (SwiftShader works on any machine).
moxwebgpu is an independently developed, free and open-source project, and will keep being maintained. If it saves you time writing WebGPU boilerplate, a ⭐ star goes a long way — it is what helps others find the project.
If it is useful in your work, you can also support development:
- Afdian: https://afdian.com/a/cloudharbor
Stars, shares, or telling me where you use it are the best support. See FUNDING.yml for the channels.
MIT © codecloud-dev. Designed by codecloud-dev; code co-written with AI, human-reviewed.
