Works in Node.js. Breaks at the edge. Is your SDK portable?

Your SDK's package imports successfully in a worker. Its first authenticated request then fails because a dependency calls a Node.js API the runtime does not fully implement. An import test would have passed. A request test would have caught it.

Test each supported runtime with the installed package and a controlled API server. Record the runtime version and configuration with the result.

Write a support matrix with versions

List the runtimes you intend to support and their relevant configuration. A Node.js version, browser version, Bun version and Cloudflare Workers compatibility date describe more than a generic label such as “edge.”

Node's fetch documentation establishes the API available in Node, but shared API names do not guarantee identical platform capabilities. Cloudflare documents its Node.js compatibility surface, including partial support and compatibility behavior that depends on configuration.

Bun's compatibility documentation similarly distinguishes supported and incomplete Node interfaces. Check the current platform documentation and test the exact features your SDK uses.

Exercise the installed package

Test the archive a user installs, not only source imports inside the generator repository. Package exports, module formats, type declarations and bundled dependencies can change behavior after publication.

For each supported environment, install the package in a minimal application. Import its public entry point, construct a client and make a request to a controlled server. Inspect the resulting request headers, body, URL and response decoding.

Include failure paths: authentication rejection, timeout or abort, connection failure and documented error decoding. If the SDK supports streamed responses, exercise consumption and cleanup in every runtime where you advertise that feature.

Inventory platform dependencies

Look beyond fetch. The SDK or its dependencies may rely on Buffer, process environment variables, Node streams, filesystem access, custom agents, proxy handling or a particular crypto interface.

A browser also has a different security boundary. Secret API credentials must not be embedded in client-delivered code. Browser requests are subject to CORS, while server runtimes have different network and credential-management conditions.

Let consumers supply configuration explicitly where appropriate. Reading a process environment variable as an optional convenience in Node should not make importing the package fail in a browser or worker that lacks that global.

Check packaging and resource behavior

Test the advertised module entry points independently. A package can provide a browser condition that still imports a server-only dependency indirectly. A successful bundler build does not establish that the selected implementation works at runtime.

Watch cleanup and resource lifetime. Repeated client creation, abandoned response bodies and missing cancellation handling can behave differently across environments. Use a small repeated-request scenario to reveal failures that a single smoke test misses.

State which environments passed

Keep a matrix describing runtime version, transport, tested features and known configuration requirements. Unsupported features should produce a clear, documented outcome rather than fail unexpectedly after a long workflow.