Deno & Bun

The WorkOS SDK fully supports modern JavaScript runtimes like Deno and Bun with automatic runtime detection and optimized builds.

Deno

Installation

Deno uses npm specifiers to import packages directly:

import { WorkOS } from 'npm:@workos-inc/node';

Or use an import map for cleaner imports:

deno.json

{
  "imports": {
    "@workos-inc/node": "npm:@workos-inc/node@^8.7.0"
  }
}

Then import normally:

import { WorkOS } from '@workos-inc/node';

Runtime Detection

The SDK automatically uses the Deno-optimized build via conditional exports:

{
  "exports": {
    ".": {
      "deno": {
        "types": "./lib/index.d.ts",
        "default": "./lib/index.js"
      }
    }
  }
}

Basic Usage

main.ts

import { WorkOS } from 'npm:@workos-inc/node';

const workos = new WorkOS(Deno.env.get('WORKOS_API_KEY'));

// List users
const { data: users } = await workos.userManagement.listUsers();
console.log(users);

Environment Variables

Deno uses Deno.env to access environment variables:

const workos = new WorkOS(Deno.env.get('WORKOS_API_KEY'));

Or use a .env file with the --env flag:

.env

WORKOS_API_KEY=sk_test_1234567890
WORKOS_CLIENT_ID=client_1234567890

deno run --allow-env --allow-net --env main.ts

Permissions

Deno requires explicit permissions. The WorkOS SDK needs:

deno run --allow-net --allow-env main.ts

Required permissions:

--allow-net: For making HTTP requests to WorkOS API
--allow-env: For reading environment variables

Deno Deploy

The SDK works seamlessly with Deno Deploy:

main.ts

import { WorkOS } from 'npm:@workos-inc/node';

const workos = new WorkOS(Deno.env.get('WORKOS_API_KEY'));

Deno.serve(async (req) => {
  const url = new URL(req.url);

  if (url.pathname === '/users') {
    try {
      const { data: users } = await workos.userManagement.listUsers();
      return Response.json(users);
    } catch (error) {
      return Response.json(
        { error: error.message },
        { status: 500 }
      );
    }
  }

  return new Response('Not Found', { status: 404 });
});

Deploy with:

deployctl deploy --project=my-project main.ts

Fresh Framework

Using WorkOS in a Fresh application:

routes/api/users.ts

import { Handlers } from '$fresh/server.ts';
import { WorkOS } from 'npm:@workos-inc/node';

const workos = new WorkOS(Deno.env.get('WORKOS_API_KEY'));

export const handler: Handlers = {
  async GET(_req, _ctx) {
    try {
      const { data: users } = await workos.userManagement.listUsers();
      return Response.json(users);
    } catch (error) {
      return Response.json(
        { error: error.message },
        { status: 500 }
      );
    }
  },
};

Testing with Deno

main_test.ts

import { assertEquals } from 'https://deno.land/[email protected]/assert/mod.ts';
import { WorkOS } from 'npm:@workos-inc/node';

Deno.test('WorkOS SDK initializes', () => {
  const workos = new WorkOS('sk_test_1234');
  assertEquals(typeof workos.userManagement.listUsers, 'function');
});

Deno.test('lists users', async () => {
  const workos = new WorkOS(Deno.env.get('WORKOS_API_KEY'));
  const { data: users } = await workos.userManagement.listUsers();
  assertEquals(Array.isArray(users), true);
});

Run tests:

deno test --allow-net --allow-env

Bun

Installation

Bun has a fast npm-compatible package manager:

bun add @workos-inc/node

Runtime Detection

The SDK automatically uses the Bun-optimized build:

{
  "exports": {
    ".": {
      "bun": {
        "types": "./lib/index.d.ts",
        "import": "./lib/index.js",
        "require": "./lib/index.cjs"
      }
    }
  }
}

Basic Usage

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

// List users
const { data: users } = await workos.userManagement.listUsers();
console.log(users);

Environment Variables

Bun automatically loads .env files:

.env

WORKOS_API_KEY=sk_test_1234567890
WORKOS_CLIENT_ID=client_1234567890

import { WorkOS } from '@workos-inc/node';

// Bun automatically loads .env
const workos = new WorkOS(process.env.WORKOS_API_KEY);

Or use Bun.env:

const workos = new WorkOS(Bun.env.WORKOS_API_KEY);

Bun HTTP Server

server.ts

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const server = Bun.serve({
  port: 3000,
  async fetch(req) {
    const url = new URL(req.url);

    if (url.pathname === '/users') {
      try {
        const { data: users } = await workos.userManagement.listUsers();
        return Response.json(users);
      } catch (error) {
        return Response.json(
          { error: error.message },
          { status: 500 }
        );
      }
    }

    return new Response('Not Found', { status: 404 });
  },
});

console.log(`Server running at http://localhost:${server.port}`);

Run with:

bun run server.ts

Elysia Framework

app.ts

import { Elysia } from 'elysia';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const app = new Elysia()
  .get('/users', async () => {
    try {
      const { data: users } = await workos.userManagement.listUsers();
      return users;
    } catch (error) {
      return { error: error.message };
    }
  })
  .get('/user/:id', async ({ params }) => {
    try {
      const user = await workos.userManagement.getUser({
        userId: params.id,
      });
      return user;
    } catch (error) {
      return { error: error.message };
    }
  })
  .listen(3000);

console.log(`Server running at http://localhost:${app.server?.port}`);

Hono Framework

app.ts

import { Hono } from 'hono';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const app = new Hono();

app.get('/users', async (c) => {
  try {
    const { data: users } = await workos.userManagement.listUsers();
    return c.json(users);
  } catch (error) {
    return c.json({ error: error.message }, 500);
  }
});

export default {
  port: 3000,
  fetch: app.fetch,
};

Testing with Bun

Bun has a built-in test runner:

workos.test.ts

import { describe, test, expect } from 'bun:test';
import { WorkOS } from '@workos-inc/node';

describe('WorkOS SDK', () => {
  test('initializes correctly', () => {
    const workos = new WorkOS('sk_test_1234');
    expect(workos).toBeDefined();
    expect(typeof workos.userManagement.listUsers).toBe('function');
  });

  test('lists users', async () => {
    const workos = new WorkOS(process.env.WORKOS_API_KEY);
    const { data: users } = await workos.userManagement.listUsers();
    expect(Array.isArray(users)).toBe(true);
  });
});

Run tests:

bun test

Performance Benefits

Bun is significantly faster than Node.js for many operations:

Faster Package Installation

Bun’s package manager is 10-100x faster than npm:

bun add @workos-inc/node  # Much faster than npm install

Faster Startup Time

Bun starts TypeScript files directly without transpilation:

bun run app.ts  # No build step needed

Faster HTTP Requests

Bun’s native fetch implementation is optimized for performance.

Runtime Comparison

Node.js

Most mature ecosystem
Largest package compatibility
Industry standard
Slower startup and execution

Deno

Secure by default (permissions)
Native TypeScript support
Built-in tooling
Web Standards API

Bun

Fastest performance
Built-in TypeScript
npm compatibility
Fast package manager

Ecosystem Testing

The WorkOS SDK includes automated runtime compatibility tests:

const tests: Record<string, { cmd: string; args: string[] }> = {
  'node-cjs': {
    cmd: 'node',
    args: ['-e', `console.log('✅ Node CJS:', require("${lib}/index.cjs").WorkOS.name)`],
  },
  'node-esm': {
    cmd: 'node',
    args: ['-e', `import("${lib}/index.js").then(m => console.log('✅ Node ESM:', m.WorkOS.name))`],
  },
  deno: {
    cmd: 'deno',
    args: ['eval', `import("${lib}/index.js").then(m => console.log('✅ Deno:', m.WorkOS.name))`],
  },
  'bun-cjs': {
    cmd: 'bun',
    args: ['-e', `console.log('✅ Bun CJS:', require("${lib}/index.cjs").WorkOS.name)`],
  },
  'bun-esm': {
    cmd: 'bun',
    args: ['-e', `import("${lib}/index.js").then(m => console.log('✅ Bun ESM:', m.WorkOS.name))`],
  },
};

Run compatibility checks:

npm run check:runtimes

Troubleshooting

Deno: Permission Denied

Ensure you grant the necessary permissions:

deno run --allow-net --allow-env main.ts

Deno: Module Not Found

Use the npm: specifier for npm packages:

import { WorkOS } from 'npm:@workos-inc/node';

Bun: TypeScript Errors

Bun supports TypeScript natively. Ensure your tsconfig.json is compatible:

tsconfig.json

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "module": "ESNext",
    "target": "ESNext",
    "moduleResolution": "bundler"
  }
}

Bun: Module Resolution

Bun uses its own module resolution algorithm. If you encounter issues, try:

bun pm cache rm
bun install --force

Next Steps

Node.js Runtime

Learn about Node.js-specific features

Edge Workers

Deploy to Cloudflare Workers or Vercel Edge

User Management

Manage users and authentication

Webhooks

Handle WorkOS webhook events

Getting Started

Core Concepts

Runtime Support

Deno

Installation

Runtime Detection

Basic Usage

Environment Variables

Permissions

Deno Deploy

Fresh Framework

Testing with Deno

Bun

Installation

Runtime Detection

Basic Usage

Environment Variables

Bun HTTP Server

Elysia Framework

Hono Framework

Testing with Bun

Performance Benefits

Runtime Comparison

Node.js

Deno

Bun

Ecosystem Testing

Troubleshooting

Next Steps

Node.js Runtime

Edge Workers

User Management

Webhooks

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Runtime Support

​Deno

​Installation

​Runtime Detection

​Basic Usage

​Environment Variables

​Permissions

​Deno Deploy

​Fresh Framework

​Testing with Deno

​Bun

​Installation

​Runtime Detection

​Basic Usage

​Environment Variables

​Bun HTTP Server

​Elysia Framework

​Hono Framework

​Testing with Bun

​Performance Benefits

​Runtime Comparison

Node.js

Deno

Bun

​Ecosystem Testing

​Troubleshooting

​Next Steps

Node.js Runtime

Edge Workers

User Management

Webhooks

Build docs developers (and LLMs) love

Deno

Installation

Runtime Detection

Basic Usage

Environment Variables

Permissions

Deno Deploy

Fresh Framework

Testing with Deno

Bun

Installation

Runtime Detection

Basic Usage

Environment Variables

Bun HTTP Server

Elysia Framework

Hono Framework

Testing with Bun

Performance Benefits

Runtime Comparison

Ecosystem Testing

Troubleshooting

Next Steps