Browser support

The browser backend uses SharedArrayBuffer for its synchronous virtual filesystem, which means your page must be cross-origin isolated. Without the right headers, the browser runtime degrades to a partial mode or refuses to boot.

The server backend does not depend on browser OPFS or SharedArrayBuffer, but the page still needs normal browser support for the SDK, fetch, and WebSocket transport.

Required headers

Your page must respond with:

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

…and every same-origin asset must respond with:

Cross-Origin-Resource-Policy: same-origin

Once all three are present, globalThis.crossOriginIsolated evaluates to true and SharedArrayBuffer becomes available.

Firefox is strict about CORP. Without Cross-Origin-Resource-Policy: same-origin on every sub-resource, Firefox blocks access to SharedArrayBuffer even when the page itself is cross-origin isolated. Chromium tolerates the omission today; Firefox does not. Set CORP everywhere.

Configuring Next.js

// next.config.ts
export default {
  async headers() {
    return [
      {
        source: '/your-runtime-route/:path*',
        headers: [
          { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
          { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
        ],
      },
      {
        source: '/_next/static/:path*',
        headers: [{ key: 'Cross-Origin-Resource-Policy', value: 'same-origin' }],
      },
    ];
  },
};

Scope the COOP / COEP headers to the routes that actually need Verklet — they break third-party <iframe> and <img> embeds that don't return CORP headers themselves.

Preview CSP

Runtime previews use isolated subdomains under https://*.preview.verklet.com. If your CSP restricts frames, add that wildcard to frame-src and, for older browsers, child-src. SDK calls through runtime.fetchPreview() are routed inside the runtime and do not require browser network access to the preview domain.

Browser matrix

Footnotes

1. WebKit OPFS — Real Safari supports OPFS, but Playwright's WebKit build throws UnknownError on the first navigator.storage.getDirectory() call. The runtime detects this via an availability probe at boot and sets capabilities.opfs = false rather than crashing. Persist+restore skips cleanly when OPFS is unavailable.

2. Unknown — The feature has not yet been exercised by the cross-browser smoke harness. Behaviour may differ from Chromium; explicit testing is needed before marking the cell supported or partial.

Detecting capabilities

If you need to render a fallback when the host can't support Verklet:

import { detectCapabilities } from '@verklet/sdk';

const caps = await detectCapabilities();
if (!caps.crossOriginIsolated || !caps.sharedArrayBuffer) {
  // show a "open in a modern browser" message, or a static fallback
}