Environment:Openai Openai node Node 20 Runtime

Knowledge Sources	openai-node MIGRATION.md
Domains	Infrastructure, JavaScript_Runtime
Last Updated	2026-02-15 12:00 GMT

Overview

Node.js 20 LTS (or newer) runtime environment with TypeScript 4.9+ and zero runtime dependencies, required to run the OpenAI Node.js SDK v5+.

Description

This environment provides the JavaScript/TypeScript runtime context for the OpenAI Node.js SDK (v6.22.0). The SDK has zero runtime dependencies and relies entirely on built-in Web platform APIs (Fetch, ReadableStream, File, FormData, WebCrypto). Node.js 20 LTS is the minimum because it is the first LTS version to provide the global `File` class required for file uploads. The SDK also supports Deno, Bun, Cloudflare Workers, and Vercel Edge Runtime, but Node.js is the primary target.

Usage

Use this environment for all workflows that invoke the OpenAI API through the Node.js SDK: Chat Completions, Structured Output Parsing, Function Calling, Fine-Tuning, Audio Processing, Streaming, and Realtime Conversations. This is the foundational prerequisite for every Implementation page in the wiki.

System Requirements

Category	Requirement	Notes
OS	Any (Linux, macOS, Windows)	Cross-platform; platform detected at runtime
Runtime	Node.js >= 20 LTS	Required for global `File` class; also supports Deno, Bun, Edge
Language	TypeScript >= 4.9	Minimum for SDK type definitions
Test Framework	Jest >= 28	If running SDK ecosystem tests
Package Manager	npm, yarn, or pnpm	`yarn@1.22.22` used in SDK development

Dependencies

System Packages

None required — the SDK has zero runtime dependencies

NPM Packages

`openai` = 6.22.0 (the SDK itself)
`ws` >= 8.18.0 (optional peer dependency — only needed for Realtime API in Node.js)
`zod` >= 3.25 or >= 4.0 (optional peer dependency — only needed for structured output parsing helpers)

Credentials

The following environment variables are read by the SDK at initialization:

`OPENAI_API_KEY`: Required. API key for authenticating with the OpenAI API.
`OPENAI_ORG_ID`: Optional. Organization ID for scoping API requests.
`OPENAI_PROJECT_ID`: Optional. Project ID for scoping API requests.
`OPENAI_BASE_URL`: Optional. Override the default base URL (`https://api.openai.com/v1`).
`OPENAI_WEBHOOK_SECRET`: Optional. Secret for verifying webhook signatures.
`OPENAI_LOG`: Optional. Log level (`off`, `error`, `warn`, `info`, `debug`). Defaults to `warn`.

Quick Install

# Install the SDK
npm install openai

# Optional: Install peer dependencies for Realtime API and structured outputs
npm install ws zod

Code Evidence

Node.js version check from `src/internal/uploads.ts:14-26`:

export const checkFileSupport = () => {
  if (typeof File === 'undefined') {
    const { process } = globalThis as any;
    const isOldNode =
      typeof process?.versions?.node === 'string' && parseInt(process.versions.node.split('.')) < 20;
    throw new Error(
      '`File` is not defined as a global, which is required for file uploads.' +
        (isOldNode ?
          " Update to Node 20 LTS or newer, or set `globalThis.File` to `import('node:buffer').File`."
        : ''),
    );
  }
};

Cross-platform environment variable reading from `src/internal/utils/env.ts:10-18`:

export const readEnv = (env: string): string | undefined => {
  if (typeof (globalThis as any).process !== 'undefined') {
    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
  }
  if (typeof (globalThis as any).Deno !== 'undefined') {
    return (globalThis as any).Deno.env?.get?.(env)?.trim();
  }
  return undefined;
};

Platform detection from `src/internal/detect-platform.ts:21-36`:

function getDetectedPlatform(): DetectedPlatform {
  if (typeof Deno !== 'undefined' && Deno.build != null) {
    return 'deno';
  }
  if (typeof EdgeRuntime !== 'undefined') {
    return 'edge';
  }
  if (
    Object.prototype.toString.call(
      typeof (globalThis as any).process !== 'undefined' ? (globalThis as any).process : 0,
    ) === '[object process]'
  ) {
    return 'node';
  }
  return 'unknown';
}

Common Errors

Error Message	Cause	Solution
`File is not defined as a global, which is required for file uploads.`	Node.js version < 20	Upgrade to Node.js 20 LTS or newer
`Missing credentials. Please pass an apiKey, or set the OPENAI_API_KEY environment variable.`	`OPENAI_API_KEY` not set and no `apiKey` option passed	Set `OPENAI_API_KEY` in your environment or pass `apiKey` to the constructor
`It looks like you're running in a browser-like environment.`	SDK instantiated in a browser without `dangerouslyAllowBrowser: true`	Use ephemeral tokens or set `dangerouslyAllowBrowser: true` with appropriate mitigations

Compatibility Notes

Deno: Fully supported. Environment variables read via `Deno.env.get()`. Published to JSR as `@openai/openai`.
Bun: Supported. File uploads use Bun's native `BunFile` interface.
Cloudflare Workers / Vercel Edge: Supported via Edge Runtime detection. The `ws` package is not available; use `OpenAIRealtimeWebSocket` (browser WebSocket) instead of `OpenAIRealtimeWS`.
Browser: Blocked by default to prevent API key exposure. Requires `dangerouslyAllowBrowser: true` to override.
CommonJS and ESM: Both module systems supported via `dist/index.js` (CJS) and `dist/index.mjs` (ESM).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment