Skip to main content
The WorkOS Node.js SDK is built to work seamlessly across multiple JavaScript runtimes, from traditional Node.js servers to modern edge computing platforms.

​
Supported Runtimes

The SDK provides runtime-specific builds optimized for each environment:

Node.js

Node.js 20.15.0 and higher with full feature support

Edge Workers

Cloudflare Workers, Vercel Edge Functions, and Convex

Deno

Deno runtime with native TypeScript support

Bun

Bun runtime for high-performance JavaScript

​
Automatic Runtime Detection

The SDK uses the Node.js exports field to automatically select the correct build for your runtime:
package.json
{
  "exports": {
    ".": {
      "workerd": "./lib/index.worker.js",      // Cloudflare Workers
      "edge-light": "./lib/index.worker.js",   // Vercel Edge
      "deno": "./lib/index.js",                // Deno
      "bun": "./lib/index.js",                 // Bun
      "convex": "./lib/index.worker.js",       // Convex
      "import": "./lib/index.js",              // Node.js ESM
      "require": "./lib/index.cjs",            // Node.js CJS
      "default": "./lib/index.js"
    }
  }
}
You don’t need to configure anything - just import the SDK normally and it will use the appropriate build.

​
Runtime Differences

​
Standard Build (index.js / index.cjs)

Used by Node.js, Deno, and Bun:
  • Full Node.js API access
  • User-Agent header support
  • process.emitWarning() for deprecation warnings
  • Supports both ESM and CommonJS

​
Worker Build (index.worker.js)

Used by Cloudflare Workers, Vercel Edge, and Convex:
  • Web Standards API only (no Node.js APIs)
  • Limited header customization
  • console.warn() for warnings instead of process.emitWarning()
  • Optimized for edge runtime constraints
Both builds use the same SubtleCrypto API for cryptographic operations, ensuring consistent webhook verification and JWT handling across all runtimes.

​
Module Formats

The SDK is distributed in multiple module formats:
  • Modern JavaScript module format
  • Native import/export syntax
  • Tree-shakeable for smaller bundle sizes
  • Default for Node.js, Deno, Bun, and edge runtimes
  • Traditional Node.js module format
  • Uses require() and module.exports
  • Bundles ESM-only dependencies for compatibility
  • Available for Node.js and Bun

​
Getting Started

Choose your runtime to see specific installation and usage instructions:

Node.js

Traditional server-side JavaScript

Edge Workers

Cloudflare Workers and Vercel Edge

Deno & Bun

Modern JavaScript runtimes

​
Requirements

{
  "engines": {
    "node": ">=20.15.0"
  }
}

​
Manual Runtime Selection

In rare cases where you need to manually select the worker build, you can import it directly: 
import { WorkOS } from '@workos-inc/node/worker';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
Manual runtime selection is rarely needed. The automatic runtime detection works for 99% of use cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us