feat: Universal runtime compatibility for Node.js SDK v8 - fixes import resolution across all target runtimes

[nicknisi]

Description

This PR implements comprehensive universal runtime compatibility for the WorkOS Node.js SDK v8, addressing critical module resolution issues that prevented the package from working correctly across different JavaScript runtimes.

Problem Statement

The current v8 build configuration with tsup and bundle: false created incompatible import patterns:

• CJS files attempted to require() ESM files (.js extension)
• ESM files imported without explicit file extensions, breaking strict runtimes like Deno
• Standalone Node.js execution failed due to cross-format imports
• Edge Runtime and Cloudflare Workers compatibility was broken

Solution Overview

Phase 1: Import Path Rewriting ✅

• Implemented custom fixImportsPlugin to rewrite import paths during build
• ESM builds now use explicit .js extensions for all relative imports
• CJS builds use .cjs extensions for internal module references
• Maintains bundler compatibility while fixing standalone runtime execution

Phase 2: Enhanced Export Mapping ✅

• Added runtime-specific export conditions for optimal module resolution
• Separate TypeScript type paths for CJS (.d.cts) and ESM (.d.ts)
• Dedicated worker builds for edge runtimes (workerd, edge-light)
• Performance-ordered conditions for faster resolution

Phase 3: Comprehensive Testing Infrastructure ✅

• Created ecosystem compatibility test suite covering 6 runtime scenarios
• Manual validation commands for immediate testing
• Automated CI/CD workflow with matrix strategy testing Node.js 18/20, Deno, and Bun
• Fail-fast smoke tests for quick compatibility validation

Runtime Compatibility Matrix

Runtime	CJS Build	ESM Build	Status	Notes
Next.js/webpack	✅	✅	Working	Bundler handles resolution
Node.js standalone	✅	✅	FIXED	Import rewriting resolved cross-format issues
Deno	N/A	✅	FIXED	Explicit .js extensions now provided
Bun	✅	✅	Working	Enhanced with runtime-specific exports
Edge Runtime	✅	✅	FIXED	Dedicated worker builds
Cloudflare Workers	✅	✅	FIXED	Optimized for workerd environment

Key Technical Changes

1. Custom Import Rewriter Plugin (scripts/fix-imports-plugin.ts)

   • Transforms relative imports to include appropriate file extensions
   • Format-aware: .js for ESM, .cjs for CommonJS
   • Preserves external module imports unchanged

2. Enhanced Package.json Exports

   {
     "exports": {
       ".": {
         "types": {
           "require": "./lib/cjs/index.d.cts",
           "import": "./lib/esm/index.d.ts"
         },
         "workerd": "./lib/esm/index.worker.js",
         "edge-light": "./lib/esm/index.worker.js", 
         "deno": "./lib/esm/index.js",
         "bun": {
           "import": "./lib/esm/index.js",
           "require": "./lib/cjs/index.cjs"
         },
         "node": {
           "import": "./lib/esm/index.js",
           "require": "./lib/cjs/index.cjs"
         },
         "import": "./lib/esm/index.js",
         "require": "./lib/cjs/index.cjs",
         "default": "./lib/esm/index.js"
       }
     }
   }

3. CI/CD Integration (.github/workflows/runtime-tests.yml)

   • Matrix strategy testing across Node.js versions and alternative runtimes
   • Automated validation on every PR and push
   • Quick smoke tests for immediate feedback

Testing Results

All 6 runtime scenarios now pass:

• ✅ Node.js CJS: WorkOSNode
• ✅ Node.js ESM: WorkOSNode
• ✅ Deno: WorkOSNode
• ✅ Bun CJS: WorkOSNode
• ✅ Bun ESM: WorkOSNode
• ✅ Worker: Module resolution successful

Verification Commands

# Node.js CJS
node -e "console.log('CJS:', require('./lib/cjs/index.cjs').WorkOS.name)"

# Node.js ESM  
node -e "import('./lib/esm/index.js').then(m => console.log('ESM:', m.WorkOS.name))"

# Deno
deno eval "import('./lib/esm/index.js').then(m => console.log('Deno:', m.WorkOS.name))"

# Bun
bun -e "console.log('Bun:', require('./lib/cjs/index.cjs').WorkOS.name)"

# Comprehensive test suite
pnpm check:runtimes

Backward Compatibility

• ✅ No breaking changes to existing API surface
• ✅ Bundler compatibility maintained (Next.js, webpack, Vite, etc.)
• ✅ Tree-shaking still works properly
• ✅ Package size unchanged (unbundled builds)
• ✅ TypeScript support enhanced with improved type resolution

Risk Mitigation

• Extensive testing across all target runtimes before merge
• Automated CI validation prevents regressions
• Rollback plan available (revert to bundle: true if needed)
• Industry-standard patterns based on OpenAI SDK, Drizzle ORM practices

Documentation

[ ] Yes

This change improves internal module resolution and doesn't affect the public API, so no documentation updates are required.

[greptile-apps]

PR Summary

Major refactoring of the WorkOS Node.js SDK build system to enable universal runtime compatibility across Node.js, Deno, Bun, and Edge environments.

• New fixImportsPlugin in tsup config transforms import paths to ensure proper extension resolution (.js for ESM, .cjs for CommonJS)
• Enhanced package exports with runtime-specific conditions for optimal module resolution across environments
• Added comprehensive runtime testing suite via new ecosystem-check.ts and GitHub workflow for automated validation
• Removed legacy worker.spec.ts in favor of new ecosystem testing infrastructure
• Modernized linting configuration from tslint to eslint in TypeScript interface files

_{7 files reviewed, 2 comments
Edit PR Review Bot Settings | Greptile}

[greptile-apps]

logic: Windows path handling might still fail if path contains spaces. Use JSON.stringify() for full path escaping

[Copilot]

Pull Request Overview

This PR restructures the SDK build and package configuration to ensure universal runtime compatibility across Node.js, Deno, Bun, and edge environments by splitting ESM/CJS outputs with correct file extensions, enhancing package exports, and replacing the Jest worker spec with a comprehensive ecosystem check script.

• Split tsup config into separate ESM and CJS builds using an import-rewriting plugin.
• Updated package.json exports, main/module/types paths, and dev dependencies.
• Removed the Jest worker spec in favor of a multi-runtime scripts/ecosystem-check.ts suite and added a CI workflow.

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tsup.config.ts	Separated ESM/CJS builds and added the fixImportsPlugin.
src/workos.ts	Reformatted the WorkOS constructor signature for readability.
src/worker.spec.ts	Removed the Jest worker spec test.
src/sso/interfaces/authorization-url-options.interface.ts	Updated the ESLint disable comment for the empty interface.
scripts/ecosystem-check.ts	Introduced a comprehensive runtime compatibility check script.
package.json	Adjusted entry points, exports, type paths, and added new dev deps.
.github/workflows/runtime-tests.yml	Added CI workflow for runtime compatibility checks.

Comments suppressed due to low confidence (2)

tsup.config.ts:43

• The CJS build entry configuration excludes *.test.ts but not *.spec.ts, causing spec files to be included in the CJS output. Consider adding !src/**/*.spec.ts to the exclude patterns.

      'src/**/*.ts',