This library provides seamless integration with the WorkOS API for applications written in Deno and JavaScript/TypeScript. This project benefits from the official WorkOS SDK; sincere appreciation is extended to the WorkOS project team and all contributors for their efforts.
Disclaimer: This is a community-driven port maintained by a single developer and is not an official WorkOS product.
The SDK is fully Deno-native, designed to work with Deno 2.x and Fresh 2.x with enhanced type safety and improved performance. Key features include:
- Fine-Grained Authorization (FGA): A complete implementation of WorkOS's authorization system
- Type-Safe User Management: Enhanced session handling with proper typing
- Directory Sync: Improved serialization and type-safe directory management
- Pure Deno Implementation: No compatibility layers, built for Deno from the ground up
The goal of this fork is not to mirror the existing Node SDK one-for-one, but rather to show what the WorkOS developer experience can feel like when it is built for the Deno runtime and the Fresh framework from day one.
🛠️ Ship Faster
- Zero-config: run
deno task devand start coding—no bundlers, transpliers, or package managers to configure. - First-class TypeScript and JSX/TSX support baked into the runtime eliminates "works-on-my-machine" classpath issues and reduces set-up time.
- Fresh's islands architecture keeps your pages interactive with minimal client-side JavaScript, trimming megabytes off the bundle and making Lighthouse scores happier out-of-the-box.
🔒 Safer by Default
- Deno's permission model ("–allow-net", "–allow-env", etc.) means accidental file system or network access is impossible unless you explicitly opt-in—great for CI and defence-in-depth.
- Auditable imports via import maps and cryptographically-pinned JSR packages remove the "left-pad" class of supply-chain surprises.
⚡️ Modern Runtime, Modern Performance
- Native Web APIs (fetch, web streams, URL, crypto, etc.)—no Node polyfills required.
- Built-in test runner, linter and formatter keep quality high without reaching for extra tooling.
- Edge-ready: the same code runs in Deno Deploy, Supabase Edge Functions, Vercel Edge, etc.
✅ Pros
- Deno-native: no compatibility shims, resulting in a smaller, faster bundle.
- Stricter type safety – every response object is fully annotated, reducing runtime bugs and IDE guess-work.
- Seamless Fresh 2.x integration (session cookies, islands routing, async handlers) provided out-of-the-box.
- Built-in OpenTelemetry hooks for tracing and Prometheus-friendly metrics.
- Single dependency (Deno) keeps image sizes small and simplifies CI/CD pipelines.
- JSR distribution means instant, version-pinned imports—no
npm install, no lockfiles.
- Smaller community and ecosystem compared to Node; some npm-only helpers may need a Deno port or polyfill.
- Upstream WorkOS features may arrive here after the official SDK (PRs welcome!).
- This is now a pure Deno implementation with no Node.js compatibility layer - all Node.js components have been completely removed.
- If your runtime is Node.js, you should use the official WorkOS Node.js SDK as this package no longer provides npm distribution.
💡 Bottom line: If you are already betting on Deno 2.x or Fresh 2.x—or want a permission-aware, type-safe WorkOS client that feels native to the modern Web Platform—this SDK will get you from idea to production in fewer lines of code and with stronger guarantees.
This package is a fork of the workos-inc/workos-node repository, adapted specifically for Deno and JSR compatibility. Upstream changes are tracked for reference, and semantic versioning is applied independently for this implementation.
Refer to the WorkOS API Reference maintained by the WorkOS project for detailed API documentation. Thank you to the WorkOS maintainers and contributors for their continued work.
- Deno version 2.0.0 or higher
This package is designed for Deno first. You can install it in one of two ways:
Direct import:
import { WorkOS } from "jsr:@ryantaylor/workos@^0.1.0";Or add the following to your deno.json imports:
{
"imports": {
"@ryantaylor/workos": "jsr:@ryantaylor/workos@^0.1.0"
}
}This is now a pure Deno project without Node.js support. The project has fully removed all Node.js components (package.json, package-lock.json, node_modules) and only supports Deno as the runtime environment. All CI workflows have been updated to use only Deno. This decision allows for optimizations specific to the Deno platform and eliminates the overhead of maintaining compatibility layers.
This library is published exclusively to JSR.io, a modern registry optimized for Deno and web projects. There is no npm distribution of this package.
For Deno applications, initialize the SDK as shown below:
import { WorkOS } from "@ryantaylor/workos";
const workos = new WorkOS(
Deno.env.get("WORKOS_API_KEY") ?? "",
{ clientId: Deno.env.get("WORKOS_CLIENT_ID") },
);Create a .env file at the project root with the following entries:
WORKOS_API_KEY=your_workos_api_key
WORKOS_CLIENT_ID=your_workos_client_id
SESSION_SECRET=a_strong_random_string_for_cookie_encryption
WORKOS_WEBHOOK_SECRET=your_workos_webhook_signing_secretIn production environments, it is recommended to use a secure secrets management service instead of environment files.
Launch the Fresh development server with live reload:
deno task devChanges will be reflected in real time.
This project uses import maps to manage dependencies. To ensure all imports are properly mapped, a validation tool is provided:
deno run -A scripts/check-import-map.tsThis script:
- Scans TypeScript/JavaScript files in key directories
- Identifies imports not covered by the import map
- Provides JSR-formatted suggestions for unmapped imports
To automatically fix unmapped imports, run:
deno run -A scripts/check-import-map.ts --fixWhen adding new dependencies, always update your import map to ensure proper resolution. The validation tool will help identify:
- Missing entries in your import map
- Imports that could be converted to JSR format
- Potential issues with dependency resolution
Built-in support for OpenTelemetry enables observability of SDK usage, performance, and errors. Example configuration:
const workos = new WorkOS(
Deno.env.get("WORKOS_API_KEY") ?? "",
{
clientId: Deno.env.get("WORKOS_CLIENT_ID"),
telemetry: {
enabled: true,
endpoint: "http://localhost:4318",
serviceName: "my-application",
defaultAttributes: {
environment: "production",
"deployment.version": "1.2.3",
},
debug: false,
},
},
);Telemetry data is exported in the OTLP format and can be collected by an OpenTelemetry Collector, stored in Prometheus, and visualized in Grafana.
Key metrics and traces include:
- API request latency and error rates
- Authentication attempt success/failure rates
- Directory sync operation metrics
- FGA authorization checks and performance
Recommended for production deployments:
- Setting up alerts for abnormal error rates or latency
- Monitoring authentication failures as a security measure
- Tracking API usage to ensure you stay within rate limits
- Secure environment variables via a vault or secrets management service
- Enforce CORS and security headers for application routes
- Monitor telemetry and configure alerts for abnormal patterns
- Plan for scalability and handle API rate limits appropriately
The FGA module provides a flexible, scalable authorization system that lets you model complex access control scenarios.
- Create and manage resources
- Establish relationships with warrants
- Perform authorization checks
- Query authorization relationships
- Batch operations for resources and warrants
// Initialize the FGA module
const workos = new WorkOS(Deno.env.get("WORKOS_API_KEY") ?? "");
const fga = workos.fga;
// Create a resource
const resource = await fga.createResource({
resourceType: "document",
resourceId: "doc-123",
meta: { name: "Project Plan" },
});
// Create a relationship (warrant)
await fga.writeWarrant({
subjectType: "user",
subjectId: "user-456",
relation: "editor",
resourceType: "document",
resourceId: "doc-123",
});
// Perform an authorization check
const checkResult = await fga.check({
subjectType: "user",
subjectId: "user-456",
relation: "editor",
resourceType: "document",
resourceId: "doc-123",
});
console.log("Is authorized:", checkResult.result);The User Management module provides session handling with enhanced type safety:
- Type-safe user session authentication
- Improved session management
- Clean session provider integration with Fresh
// Initialize User Management with session provider
const sessionProvider = new FreshSessionProvider();
const userManagement = workos.userManagement(sessionProvider);
// Authenticate a user and get properly typed session
const sessionAuth = await userManagement.authenticateWithCode({
clientId: Deno.env.get("WORKOS_CLIENT_ID") ?? "",
code: "authorization_code",
redirectUri: "https://your-app.com/callback",
});
// Type-safe access to user properties
console.log("User ID:", sessionAuth.user.id);
console.log("User Email:", sessionAuth.user.email);The Directory Sync module manages directory connections with type-safe interfaces:
- Retrieve directories with proper typing
- List users and groups with improved serialization
- Paginated results with consistent patterns
// Initialize Directory Sync
const directorySync = workos.directorySync;
// Get a directory with type-safe response
const directory = await directorySync.getDirectory("directory_123");
// List users with proper typing
const users = await directorySync.listUsers({
directory: "directory_123",
});
// List groups with pagination
const groups = await directorySync.listGroups({
directory: "directory_123",
limit: 10,
});A complete Fresh 2.x integration example for User Management:
// utils/workos.ts
import { WorkOS } from "@ryantaylor/workos";
import { FreshSessionProvider } from "@ryantaylor/workos/common/iron-session/fresh-session-provider";
export function initWorkOS() {
const workos = new WorkOS(
Deno.env.get("WORKOS_API_KEY") ?? "",
{ clientId: Deno.env.get("WORKOS_CLIENT_ID") },
);
// Initialize session provider for user management
const sessionProvider = new FreshSessionProvider({
cookieName: "app_session",
password: Deno.env.get("SESSION_SECRET") ?? "",
cookieOptions: {
httpOnly: true,
secure: true,
sameSite: "lax",
},
});
// Get typed user management client
const userManagement = workos.userManagement(sessionProvider);
// Get FGA client
const fga = workos.fga;
// Get Directory Sync client
const directorySync = workos.directorySync;
return { workos, userManagement, fga, directorySync, sessionProvider };
}The Deno-native approach taken in this project provides several key advantages:
- Enhanced Type Safety: Proper typing throughout the codebase prevents runtime errors
- No Compatibility Layers: Direct use of Deno APIs without Node.js compatibility shims
- Better Performance: Native implementations of key functionality
- Fresh Framework Integration: Seamless integration with Fresh 2.x
- Simplified Development: Clean, consistent API patterns across all modules
This SDK follows Semantic Versioning (SemVer): versions are formatted as X.Y.Z, where breaking changes are introduced only in major version increments.
This package is published to JSR.io, the modern registry for JavaScript and TypeScript packages. To publish new versions:
- Ensure all tests pass with
deno task test - Update version numbers in relevant files
- Create a new git tag for the version
- Run
jsr publishto publish to JSR.io
This package has been fully migrated from Node.js to Deno. All Node.js components have been removed, including package.json, package-lock.json, and node_modules. The CI workflows have also been updated to use only Deno.
If you're migrating from a Node.js application, you'll need to switch to Deno to use this SDK. There is no longer a Node.js compatibility layer or npm distribution maintained for this project. Users of the previous Node.js version should use the official WorkOS Node.js SDK instead.
Beta features are available via Beta release tags. Pinning to a specific version is advised to avoid unexpected breaking changes.
- Install Deno from the official website
- Clone this repository
- Copy
.env.exampleto.envand fill in your WorkOS API keys - Run
deno task devto start the development server
The test suite uses Deno's built-in testing capabilities:
# Run all tests
deno task test
# Run tests in watch mode during development
deno task test:watch
# Run tests with coverage
deno task test:coverageFor more details about our testing approach, see docs/test-coverage.md.
This project leverages Deno's built-in tools for code quality:
# Format code
deno fmt
# Check types
deno check- All tests use Deno's native testing framework
- HTTP requests are mocked using utilities in
tests_deno/utils/ - Coverage is tracked using Deno's built-in coverage tools
- HTML coverage reports can be generated with
deno task coverage:html
Contributions are welcome. Please review the guidelines in CONTRIBUTING.md for commit conventions and pull request procedures.
Hoser made in fabrique au 🇨🇦
Maintained by Ryan Taylor (@ryantaylor).