webgpu

library1.4.0jsnpmunverified

The `webgpu` package provides a native WebGPU implementation for Node.js, leveraging Google's Dawn project. Currently at version 0.4.0, it sees frequent minor updates, aligning with the ongoing development of the WebGPU standard and Dawn itself. Its primary purpose is to enable server-side GPU computation and rendering without a browser environment, allowing developers to execute WGSL shaders and manage GPU resources directly within Node.js applications. A key differentiator is its direct integration with native GPU drivers via Dawn, contrasting with browser-based WebGPU which runs within a web page context. It is not intended for testing web pages or providing web platform APIs like canvas or video elements, but rather for headless GPU operations such as rendering to textures and running compute shaders.

ai-ml data

npm install webgpu

github ↗package ↗

INSTALL

IMPORT

SIG · WEBGPU

webgpu

ai-mljavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

create

✓ import { create } from 'webgpu';

✗ const { create } = require('webgpu');

This function is the primary entry point to obtain the `GPU` object, which is then typically assigned to `navigator.gpu` in a Node.js context. ESM import is standard.

globals

✓ import { globals } from 'webgpu';

✗ const { globals } = require('webgpu');

This object contains global WebGPU constructor functions (e.g., `GPUDevice`, `GPUBuffer`) which are commonly assigned to `globalThis` to emulate browser-like WebGPU API access.

GPU

✓ import type { GPU } from '@webgpu/types';

While `webgpu` ships its own types, direct type imports for core WebGPU interfaces like `GPU` are typically sourced from the `@webgpu/types` package for consistency with the WebGPU specification's TypeScript definitions.

This quickstart initializes a WebGPU context in Node.js, obtains a GPU adapter and device, and demonstrates creating a simple GPU buffer. It highlights the use of `create` and `globals` and the typical setup flow for headless WebGPU operations.

import { create, globals } from 'webgpu'; // Assign WebGPU global constructors to globalThis for browser-like API access Object.assign(globalThis, globals); // Create the navigator.gpu object const navigator = { gpu: create([ // Optional: Pass Dawn-specific options, e.g., enabling unsafe APIs or specifying a backend // "enable-dawn-features=allow_unsafe_apis,dump_shaders", // "backend=vulkan", // or 'metal', 'd3d12', 'opengl', 'null', etc. ]), }; async function runWebGPU() { try { // Request an adapter (physical GPU) const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance', }); if (!adapter) { console.error('No WebGPU adapter found.'); return; } // Request a device (logical GPU connection) const device = await adapter.requestDevice(); // Log device info (example) console.log('WebGPU Device obtained:', device); console.log('Adapter name:', adapter.name); // Perform some WebGPU operations (e.g., compute shader, rendering to texture) // For a full example, refer to the package's GitHub repository. // Example: Create a buffer const buffer = device.createBuffer({ size: 16, usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC, mappedAtCreation: true, }); new Uint32Array(buffer.getMappedRange()).set([1, 2, 3, 4]); buffer.unmap(); console.log('Created a GPU buffer.'); } catch (error) { console.error('WebGPU initialization failed:', error); } finally { // Important: Release global reference to allow Node.js process to exit gracefully // if the GPU object was assigned to globalThis or another long-lived global. // delete globalThis.navigator; // console.log('WebGPU resources released, if applicable.'); } } runWebGPU();

Debug

Known issues

gotchaNode.js Process Lifetime: If the object returned by `create()` (which often represents the `GPU` interface and its underlying native context) is assigned to a global variable (e.g., `globalThis.navigator`), the Node.js process will not exit gracefully as the GPU context remains active in the background.

fix

Explicitly remove the global reference to the `GPU` object (e.g., `delete globalThis.navigator`) when WebGPU resources are no longer needed to allow the Node.js process to terminate.

affects: >=0.1.0

gotchaMisconception of Use Case: This package provides a headless WebGPU implementation for Node.js; it does not emulate a web browser environment. It therefore lacks browser-specific APIs like `HTMLCanvasElement`, `HTMLVideoElement`, or `HTMLImageElement` integration, making it unsuitable for testing browser-based WebGPU applications.

fix

For testing WebGPU in a browser context, tools like Puppeteer are recommended. This package is designed for server-side, off-screen GPU computation.

affects: >=0.1.0

gotchaBug Reporting Location: Bugs related to the core WebGPU implementation or the underlying Dawn project should be filed in the Chromium issue tracker, not the `node-webgpu` GitHub repository, as this package primarily serves as a build and npm publishing mechanism for Dawn's Node.js plugin.

fix

Consult the project's README for links to the appropriate issue trackers (e.g., Chromium issue tracker for Dawn/WebGPU bugs).

affects: >=0.1.0

gotchaBackend and Adapter Configuration: Specifying non-existent `backend` or `adapter` options in the `create()` function will cause an error that prints a list of valid options to the console. This requires inspecting stderr/console output to correct configuration.

fix

Review the error messages for available backends and adapters, then update the `create()` options with a valid string from the list. Alternatively, omit `backend` or `adapter` to let Dawn select defaults.

affects: >=0.1.0

breakingWebGPU API Volatility: The WebGPU specification is still evolving, and the underlying Dawn implementation frequently updates to track these changes. This means that API signatures or behaviors might undergo breaking changes in minor or even patch releases, necessitating updates to consuming code.

fix

Pin exact package versions (`npm install --save-exact webgpu`) and thoroughly test when updating. Consult the Dawn and WebGPU specification changelogs for anticipated API shifts.

affects: >=0.1.0

Errors

Common errors & fixes

Error: no suitable backends found

An invalid or unavailable GPU `backend` (e.g., 'vulkan', 'metal') was specified in the `create([])` options.

fix

Provide a valid backend name from the list printed in the error message, or omit the `backend` option to let Dawn select an appropriate one automatically for the current system.

Error: no suitable backends found\nAvailable adapters: * backend: 'metal', name: 'Apple M1 Max'

An invalid GPU `adapter` name was passed in the `create([])` options, leading Dawn to list available adapters instead of initializing.

fix

Use one of the `name` values from the `Available adapters:` list in your `create([])` call, or rely on `navigator.gpu.requestAdapter()` with `powerPreference` for adapter selection.

Node.js process does not exit

The object returned by `webgpu.create()` (representing the GPU context) is held in a global or long-lived reference, preventing Node.js from gracefully terminating because the underlying native GPU threads are still active.

fix

Explicitly remove the global reference to the WebGPU object (e.g., `delete globalThis.navigator`) once all GPU operations are complete and the context is no longer needed.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

node.jsrequiredRuntime environment for the package. Requires at least Node.js version 18.

@webgpu/typesoptionalProvides TypeScript type definitions for the WebGPU standard, enabling type-safe GPU programming. While not a direct runtime dependency, it's essential for TypeScript users.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dawn-gpu/node-webgpu ↗

packagehttps://www.npmjs.com/package/webgpu ↗