Webgpu Core Cross Browser

WebGPU Cross-Browser Compatibility

Write WebGPU code that runs on Chrome, Safari, and Firefox by feature-detecting every optional capability instead of assuming the Chrome feature set everywhere.

Quick Reference

WebGPU 1.0-stable baseline: Chrome 113+, Safari 26+, Firefox 141+.

Browser support matrix (verified against caniuse and the Chrome WebGPU blog, 2026-05):

The masterplan label "Safari 18" was wrong: WebKit shipped WebGPU in the Safari 26 / iOS 26 family. NEVER cite "Safari 18" as the WebGPU baseline.

Dawn (Chrome) optional-feature timeline. Safari and Firefox lag these dates and may never expose some entries:

Three feature-detection surfaces (full signatures in references/methods.md):

Decision Tree

Code uses a capability beyond the WebGPU 1.0 core set?
├── It is a host-side optional FEATURE (shader-f16, timestamp-query,
│   texture-compression-bc, subgroups, ...)?
│   ├── adapter.features.has("<name>") === true?
│   │   └── Add "<name>" to requiredFeatures. After requestDevice,
│   │       confirm device.features.has("<name>").
│   └── adapter.features.has("<name>") === false?
│       └── OMIT it. Run a degraded code path that does not need it.
│
├── It is an optional WGSL language feature?
│   ├── navigator.gpu.wgslLanguageFeatures.has("<name>") === true?
│   │   └── Emit shader code that uses it.
│   └── false?
│       └── Emit the baseline-WGSL shader variant instead.
│
├── It is the canvas texture format?
│   └── ALWAYS navigator.gpu.getPreferredCanvasFormat(). NEVER hard-code.
│
├── It needs a non-default LIMIT?
│   └── Read adapter.limits.<name>. Request via requiredLimits only if the
│       adapter reports a good-enough value; otherwise reduce the workload.
│
└── It is a featureLevel tier?
    └── Default "core". Use "compatibility" only to deliberately target
        OpenGL ES 3.1 / D3D11-class hardware (reduced limits and features).

Core Patterns

Pattern 1: ALWAYS feature-detect on the adapter before requiredFeatures

requestDevice rejects when requiredFeatures names a feature the adapter does not list. Chrome exposes a feature; Safari or Firefox may not. ALWAYS filter the wanted features against adapter.features.has so the same code degrades instead of breaking.

const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error("No WebGPU adapter");

const wanted = ["timestamp-query", "shader-f16", "texture-compression-bc"];
const requiredFeatures = wanted.filter((f) => adapter.features.has(f));
const device = await adapter.requestDevice({ requiredFeatures });

Pattern 2: ALWAYS confirm enabled features on device.features

adapter.features is what the adapter could grant. device.features is what the negotiated device actually has. ALWAYS branch runtime code paths on device.features.has(name), NEVER on adapter.features, because a feature is usable only when it was both supported and requested.

const useF16 = device.features.has("shader-f16");
const shaderCode = useF16 ? shaderF16Variant : shaderF32Variant;

Pattern 3: ALWAYS detect optional WGSL features before emitting them

Optional WGSL language features are reported by navigator.gpu.wgslLanguageFeatures, a set-like object. An enable or requires directive for a feature the browser lacks is a shader-creation error. ALWAYS gate the shader variant on wgslLanguageFeatures.has(name).

const wgsl = navigator.gpu.wgslLanguageFeatures;
const hasReadonlyWriteable =
  wgsl.has("readonly_and_readwrite_storage_textures");
// Emit the shader variant that matches what this browser supports.

Pattern 4: ALWAYS use getPreferredCanvasFormat for the canvas

navigator.gpu.getPreferredCanvasFormat() returns "bgra8unorm" or "rgba8unorm" depending on the platform. Safari can differ from Chrome. ALWAYS configure the canvas with this value. NEVER hard-code a format string.

const format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format, alphaMode: "premultiplied" });

Pattern 5: ALWAYS query adapter.limits, request only what you need

Default limits differ by browser and adapter. requiredLimits starts from the spec defaults. ALWAYS read adapter.limits.<name> before requesting a higher value, and request only the limits the code actually needs so the app stays portable to weaker adapters.

const needed = 256 * 1024 * 1024;
const requiredLimits =
  adapter.limits.maxStorageBufferBindingSize >= needed
    ? { maxStorageBufferBindingSize: needed }
    : {};
const device = await adapter.requestDevice({ requiredLimits });

Pattern 6: NEVER depend on timeline or batching timing side effects

Browsers batch and schedule GPU work differently. Chrome, Safari, and Firefox flush the queue at different points. ALWAYS synchronize explicitly with queue.onSubmittedWorkDone() or buffer.mapAsync(). NEVER assume work has completed because a later call appeared to see its result in one browser.

queue.submit([commandBuffer]);
await queue.onSubmittedWorkDone(); // explicit, portable synchronization
await stagingBuffer.mapAsync(GPUMapMode.READ);

Common Anti-Patterns

1. Putting an optional feature in requiredFeatures without checking adapter.features. WHY it fails: requestDevice rejects on every browser lacking the feature, so the app runs in Chrome and breaks in Safari and Firefox.

2. Hard-coding "bgra8unorm" (or "rgba8unorm") as the canvas format. WHY it fails: the preferred format is platform-dependent. A hard-coded format costs a conversion on some devices and can mismatch the swap chain on Safari.

3. Assuming a capability exists because Chrome supports it. WHY it fails: Dawn ships features first (shader-f16 Chrome 120, subgroups Chrome 134). Safari 26.0-26.5 is partial and Firefox lags on compression sets, timestamp queries, and new WGSL extensions. Code built on Chrome-only assumptions throws or produces wrong output on the other engines.

Critical Warnings

• NEVER add a GPUFeatureName to requiredFeatures without adapter.features.has(name) returning true first.
• NEVER hard-code the canvas format. ALWAYS call navigator.gpu.getPreferredCanvasFormat().
• NEVER emit an enable or requires WGSL directive without checking navigator.gpu.wgslLanguageFeatures.has(name).
• NEVER assume Safari ships every feature Chrome ships. Safari 26.0-26.5 is partial support; Firefox is disabled by default on most platforms.
• NEVER cite "Safari 18" as the WebGPU baseline. WebGPU shipped in Safari 26 / iOS 26.
• NEVER depend on how aggressively a browser batches GPU work. Synchronize with onSubmittedWorkDone() or mapAsync().
• NEVER size resources against adapter.limits. Default limits differ per browser; request via requiredLimits and size against device.limits.

Reference Files

• references/methods.md : the feature-detection API surface, including adapter.features.has, device.features.has, navigator.gpu.wgslLanguageFeatures, and getPreferredCanvasFormat.
• references/examples.md : verified feature-detection and graceful-degradation code for cross-browser WebGPU apps.
• references/anti-patterns.md : cross-browser mistakes with WHY-it-fails explanations.

Related Skills

• webgpu-core-limits-features : the limit and feature negotiation algorithm.
• webgpu-core-architecture : the adapter / device / queue initialization chain.
• webgpu-syntax-canvas-context : configuring GPUCanvasContext and the canvas texture format.