Investigate long-term support for Vercel Edge runtime in ably-js

[VeskeR]

Important notes regarding Vercel Edge runtime:

1. When importing a package in the Vercel Edge runtime, Vercel selects a browser bundle from the available bundles provided by the package in node_modules, as explained by a Vercel staff member in this GitHub issue:

So you are correct in that we decided to pick the browser field for the edge runtime, as we felt it was closer to what the runtime was capable of than Node.js (since you cannot use Node.js APIs in Edge, and browsers are usually fully spec-compliant also, compared to polyfills/packages.)

For ably-js, this means that in Vercel Edge runtimes, our web platform bundle will be selected.

2. The Vercel Edge runtime provides only a subset of Web APIs. For APIs that are typically available in other runtimes, the Vercel Edge runtime replaces them with functions that throw [SOME API] is not supported in the Edge Runtime. errors. This complicates the usage of polyfill libraries that rely on checks like if (!global.someFunction) { // define polyfill function } to determine if some functionality needs to be polyfilled.

3. Due to the specifics of Vercel Edge runtime implementation, new errors may arise due to the limited available APIs and differences in runtime behaviors. For example, we've encountered next issues so far when running Realtime functionality in the Vercel Edge runtime: Fix errors when receiving WebSocket data in Vercel Edge runtime and indefinitely creating new connections #1731, Fix "setImmediate is not supported" errors when using Realtime client in the Vercel Edge runtime #1732

---

Currently, the ably-js v1 Rest client cannot be used out-of-the-box in the Vercel Edge runtime. We encounter a "ReferenceError: window is not defined" error because our web bundle uses window at the top level, which is not available in the Vercel Edge runtime. To address this, we need to use the following workaround when exporting configs for our serverless functions (found by @owenpearson in #1265 (comment)):

export const config = {
  runtime: 'edge',
  unstable_allowDynamic: ['/node_modules/ably/**'], // this is required to run ably-js v1 in vercel edge runtime
};

However, it seems that this workaround does not work when using the ably-js v1 Rest client on frontend pages with Vercel Edge runtime (in SSR), as it still throws "ReferenceError: window is not defined" error.

Note

Using the Vercel Edge runtime for the frontend is still experimental, as indicated by Next.js output when attempting to build such project: Error: Page /BasicUsage provided runtime 'edge', the edge runtime for rendering is currently experimental. Use runtime 'experimental-edge' instead.. And when switched to experimental-edge: ⚠ You are using an experimental edge runtime, the API might change.

The ably-js v1 Realtime client does not work in the Vercel Edge runtime due to the Error: A Node.js API is used (setImmediate) which is not supported in the Edge Runtime. error.

---

The ably-js v2 Rest client currently works out-of-the-box in the Vercel Edge runtime but only in serverless functions and only when using the Rest client. No workaround like the one needed for ably-js v1 is required.
However, using the Realtime client or attempting to render frontend pages with Vercel Edge runtime results in the Error: A Node.js API is used (setImmediate) which is not supported in the Edge Runtime. error. See #1732 issue for the fix.
The white screen of death when using Vercel Edge runtime to render frontend pages can be avoided by adding:

// @ts-ignore
if (typeof EdgeRuntime === 'string') {
  return null;
}

before creating an Ably.Realtime instance on the frontend. This will ensure that when the page is server rendered in the Vercel Edge runtime, we don't instantiate a Realtime instance there, which would otherwise cause the rendering to crash.

Since we do not recommend using the Realtime API in serverless environments anyway (see #1582 (comment)) and recommend Ably's Webhooks to achieve desired behavior in serverless functions, we should consider whether to address Realtime API-related errors in Vercel Edge runtime or prevent users from using it altogether in this runtime.

---

For long-term support of Vercel Edge runtime, we can explore having a separate bundle for Vercel Edge runtime using the edge-light value in exports field in our package.json. Support for this export field value is currently in draft proposal state (runtime keys draft document, wintercg github proposal issue) and is not well-documented, but it appears to be supported by the Vercel codebase, as seen in this file.

This approach would allow us to isolate Vercel Edge runtime-specific logic in a separate bundle and make additional changes if required to fix certain functionalities.

┆Issue is synchronized with this Jira Task by Unito