DEV Community: Oleg Sidorkin

Detecting WebGPU support, the right way

Oleg Sidorkin — Thu, 18 Jun 2026 22:09:24 +0000

WebGPU is shipping in more browsers every release, but "is it supported here?" is trickier than a one-liner. Here's how to detect it correctly, why the obvious check is wrong, and how to fall back cleanly.

The check most people write (and why it's not enough)

if (navigator.gpu) {
  // WebGPU supported... right?
}

navigator.gpu existing only tells you the API surface is present. It does not mean you can actually render. The browser can expose navigator.gpu and still hand you no usable GPU because the device has no compatible adapter, WebGPU is disabled in settings, or the driver is blocklisted. You only know once you ask for an adapter.

The correct detection

async function getWebGPU() {
  if (!('gpu' in navigator)) return { supported: false, reason: 'no-api' }
  let adapter
  try {
    adapter = await navigator.gpu.requestAdapter()
  } catch (e) {
    return { supported: false, reason: 'request-failed' }
  }
  if (!adapter) return { supported: false, reason: 'no-adapter' }
  const device = await adapter.requestDevice()
  return { supported: true, adapter, device }
}

requestAdapter() is the real gate. It returns null when there's no usable GPU, which is the case the navigator.gpu check silently misses. Both requestAdapter() and requestDevice() are async, so detection has to be async too.

Support isn't all-or-nothing

Two devices that both "support WebGPU" can differ a lot. The adapter tells you what this one can actually do:

const adapter = await navigator.gpu.requestAdapter()
console.log([...adapter.features])     // e.g. 'texture-compression-bc', 'float32-filterable'
console.log(adapter.limits.maxTextureDimension2D)
console.log(adapter.limits.maxComputeWorkgroupSizeX)

If your app needs a specific feature (a compression format, timestamp queries, a higher limit), check adapter.features.has('...') and the relevant adapter.limits before you rely on it. Requesting a feature on a device that lacks it throws.

Falling back to WebGL 2

Most real apps want WebGPU when available and WebGL 2 otherwise:

async function pickRenderer() {
  if ('gpu' in navigator && (await navigator.gpu.requestAdapter())) return 'webgpu'
  const gl = document.createElement('canvas').getContext('webgl2')
  return gl ? 'webgl2' : 'none'
}

Engines like three.js and Babylon.js do this internally with a WebGPU backend and a WebGL 2 fallback, so if you're on one of those you mostly get it for free. If you're writing to the API directly, do the check yourself.

See a browser's real WebGPU profile without writing code

To eyeball what a given browser actually reports, its adapter, every standard feature with green/red status, the limits as a table, plus a live render test that confirms it really works, I put together a free tool:

WebGL & WebGPU Checker

Handy for triaging "works on my machine" bug reports: have the reporter open it and paste what they see.

Recap

navigator.gpu only means the API exists, not that you can render.
Detect by awaiting requestAdapter() and checking for a non-null result.
Read adapter.features and adapter.limits before relying on anything specific.
Fall back to WebGL 2 when WebGPU isn't available.

Fix 'SharedArrayBuffer is not defined': a practical guide to cross-origin isolation

Oleg Sidorkin — Thu, 18 Jun 2026 21:10:09 +0000

If you've ever seen this in the console:

Uncaught ReferenceError: SharedArrayBuffer is not defined

or your multithreaded WebAssembly quietly fell back to a single thread, the cause is almost always the same thing: your page is not cross-origin isolated. Here's what that means, why the browser does it, and exactly how to fix it.

TL;DR

Send these two headers on the response for the document that loads your code:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Then confirm in the console:

console.log(self.crossOriginIsolated) // should be true

When it's true, SharedArrayBuffer is available and Wasm threads work. The rest of this post is the why, the gotchas, and how to verify it without writing code.

Why the browser blocks SharedArrayBuffer

SharedArrayBuffer lets multiple threads share memory, which is what makes multithreaded WebAssembly possible. But shared memory also enables very high-precision timers, and those make Spectre-style side-channel attacks easier. After Spectre, browsers pulled SharedArrayBuffer and only give it back when your page proves it isn't sharing a process with untrusted cross-origin content. That proof is cross-origin isolation.

A page becomes cross-origin isolated when it sends both:

Cross-Origin-Opener-Policy: same-origin — cuts the link to other top-level windows so your page gets its own browsing context group.
Cross-Origin-Embedder-Policy: require-corp — says every subresource must explicitly opt in to being loaded by you.

With both in place, the browser flips self.crossOriginIsolated to true and restores SharedArrayBuffer.

The mistake almost everyone makes: CORP is not COEP

This one burns a lot of people. There's a third, similarly named header:

Cross-Origin-Resource-Policy: cross-origin

Cross-Origin-Resource-Policy (CORP) is set by a subresource (an image, a script, a font) to declare who is allowed to embed it. It does not isolate your document. If you set CORP on your HTML page expecting SharedArrayBuffer to show up, nothing happens, because that's not what CORP does.

The two headers that isolate the page are COOP and COEP. CORP comes into play only as a way for your subresources to satisfy COEP (more on that below). Keep them straight:

COOP + COEP → set on your document, turn isolation on.
CORP → set on subresources, lets them keep loading once COEP is on.

Check whether you're actually isolated

One line in the console:

self.crossOriginIsolated // true once COOP + COEP are correct

If it's false, the headers aren't reaching the page. The two usual reasons:

Wrong origin. You set the headers on a CDN subdomain, but not on the origin actually serving index.html. Isolation is decided by the document's own response headers.
Host strips them. Some static hosts (GitHub Pages and friends) don't let you set custom response headers at all, so they never arrive.

Setting the headers

nginx:

add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;

Express:

app.use((req, res, next) => {
  res.set('Cross-Origin-Opener-Policy', 'same-origin')
  res.set('Cross-Origin-Embedder-Policy', 'require-corp')
  next()
})

Can't control the headers (GitHub Pages, itch.io, some CDNs): use a service-worker shim like coi-serviceworker, which injects the headers client-side. It's how a lot of Godot and Unity web exports get threads working on hosts that won't set headers for you.

The side effect to plan for

Once COEP: require-corp is on, every cross-origin subresource has to opt in, or the browser refuses to load it. Each third-party image, script, or font now needs either:

Cross-Origin-Resource-Policy: cross-origin (or same-site) on its own response, or
proper CORS (Access-Control-Allow-Origin) plus a crossorigin attribute on the tag.

So turning on isolation can break third-party assets until you fix them. If a CDN you use won't send CORP/CORS, you'll need to proxy or self-host those files. This is the part that turns a "two header" change into an afternoon, so budget for it.

Verify any URL without writing code

To save the back-and-forth, I built a small free tool that fetches a URL's response headers and tells you whether it's actually cross-origin isolated, with the COOP/COEP values and the CORP-vs-COEP gotcha called out:

Cross-Origin Isolation Checker

There's also a longer, copy-paste walkthrough with server configs for more setups here:

Enable Wasm threads (SharedArrayBuffer) with COOP/COEP

Recap

SharedArrayBuffer is gated behind cross-origin isolation (a post-Spectre security move).
Isolate the page with COOP: same-origin + COEP: require-corp on the document.
CORP is a different header for subresources, it does not isolate your page.
Confirm with self.crossOriginIsolated === true.
Expect to fix cross-origin subresources that COEP now blocks.

Get those right and SharedArrayBuffer, and your Wasm threads, come back.