Contributing

Purpose and Scope

This page explains how to contribute to openai-node, the official TypeScript and JavaScript library for the OpenAI API. The repository is unusual because most SDK files are generated from OpenAI's API description rather than authored by hand. As a contributor, the most important first step is deciding whether a change belongs in generated SDK code, in a safe hand-maintained area, in an example, or in an upstream issue. The repository welcomes contributions, but the pull request template sets expectations that manually edited generated code may not be merged as-is.

Sources: CONTRIBUTING.md, .github/pull_request_template.md, package.json

The development workflow uses the package manager version pinned in package.json, currently expressed through the packageManager field as pnpm@11.5.1. The contributing guide explicitly says other package managers may work but are not officially supported for repository development. That matters because scripts such as build, test, lint, fix, and tsn are defined in package metadata and are the common interface for local validation. Treat those scripts as the supported entry points instead of inventing alternate local commands.

Sources: CONTRIBUTING.md, package.json

Relevant Source Files

CONTRIBUTING.md - Defines local setup, generated-source guidance, example workflow, test workflow, linting and formatting commands, source usage, and publishing notes.
.github/pull_request_template.md - Sets contributor expectations for auto-generated code and requires acknowledgment that a pull request may not be merged.
package.json - Provides the package identity, pinned pnpm version, development scripts, distribution entrypoints, dependency metadata, and publish-related configuration.

Environment Setup

Install the exact pnpm major and version family expected by the repository before running development commands. The contributing guide provides a portable command that reads package.json, extracts the pinned pnpm version, and installs that version globally. It also warns not to rely on Corepack being available. This is a practical reproducibility constraint: if your local package manager resolves, installs, or executes dependencies differently, you may see failures that maintainers cannot reproduce.

Sources: CONTRIBUTING.md, package.json

PNPM_VERSION=$(node -p "require('./package.json').packageManager.replace(/^pnpm@/, '')")
npm install --global "pnpm@$PNPM_VERSION"

After pnpm is available, the supported bootstrap is intentionally short: install dependencies, then build the SDK. The build command writes output files to dist/, which is also where package.json points its public package entrypoints through main, types, and the export map. Running the build early confirms that generated and hand-maintained TypeScript compile into the published package shape before you invest time in tests or examples.

Sources: CONTRIBUTING.md, package.json

pnpm install
pnpm build

Generated Source Expectations

Most of the SDK is generated code. The pull request template states this very directly: the code in the repository is auto-generated and is not meant to be edited manually. It recommends opening an issue instead, while still allowing contributors to open a pull request to share an improvement. The required checkbox asks contributors to acknowledge that the repository is auto-generated and that the pull request may not be merged. This is not a rejection of contributions; it is a routing rule for changes that must survive future regeneration.

Sources: CONTRIBUTING.md, .github/pull_request_template.md

The contributing guide adds a more precise distinction. Manual modifications to generated code can persist between generations, but they may produce merge conflicts when generator output changes. By contrast, the generator will never modify src/lib/ or examples/. If you need to change reusable handwritten logic, look for the hand-maintained library area. If you need to demonstrate usage, prefer an example. If you need to change generated API shapes or resources, expect that the durable fix may need to happen in the generator or API specification pipeline rather than only in this repository.

Sources: CONTRIBUTING.md, .github/pull_request_template.md

Examples and Local Source Usage

Examples are the safest place to add runnable guidance because every file under examples/ is outside generator control. The contributing guide gives a pattern for adding an executable TypeScript example and running it through the repository's tsn script. This is useful when a contribution is about demonstrating a workflow, validating a bug report, or showing a newly supported option. Keep examples focused and executable, because they often become the easiest artifact for maintainers and users to inspect.

Sources: CONTRIBUTING.md, package.json

// add an example to examples/<your-example>.ts
 
#!/usr/bin/env -S npm run tsn -- -T

chmod +x examples/<your-example>.ts
npm run tsn -- -T examples/<your-example>.ts

You can also consume the repository directly from source while developing a dependent application. The contributing guide documents two approaches: installing from the Git repository or linking a local clone globally with pnpm and then linking it into another package. Use these flows when you need to verify SDK behavior inside a real application before submitting a report or pull request. Remember that the package still builds to dist/, so source-linked testing should be paired with the normal build workflow.

Sources: CONTRIBUTING.md, package.json

npm install git+ssh://git@github.com:openai/openai-node.git

git clone https://www.github.com/openai/openai-node
cd openai-node
pnpm link --global
cd ../my-package
pnpm link --global openai

Validation Workflow

The repository exposes validation through package scripts rather than ad hoc commands. pnpm test delegates to ./scripts/test; pnpm lint delegates to ./scripts/lint; and pnpm fix delegates to ./scripts/format. The contributing guide notes that most tests require a mock server against the OpenAPI spec and shows ./scripts/mock as the setup command before running the test suite. Use the mock server path for normal SDK tests unless a specific change explicitly requires live credentials or provider-specific validation.

Sources: CONTRIBUTING.md, package.json

./scripts/mock
pnpm test
pnpm lint
pnpm fix

Formatting and linting are both part of the contribution contract. The repository uses Prettier and ESLint, with pnpm lint for checking and pnpm fix for automatic formatting and lint fixes. Running both before opening a pull request reduces review noise, especially in a generated-code repository where maintainers need to distinguish meaningful hand-written changes from formatting churn. If a generated file changes unexpectedly, re-check whether your edit belongs in a generated area or in a hand-maintained example or library file.

Sources: CONTRIBUTING.md, package.json

Pull Request and Release Expectations

Before opening a pull request, include a clear description under the template's “Changes being requested” section and add any reproduction steps, related issues, or design context under “Additional context & links.” The template's auto-generated-code warning is part of the review process, so do not remove it. A good contribution explains whether the change is an example, a hand-maintained helper, a documentation improvement, or a proposed generated-code patch that maintainers may need to route through another pipeline.

Sources: .github/pull_request_template.md, CONTRIBUTING.md

Publishing is normally handled by the automated release pull request pipeline. The contributing guide says changes made through that pipeline should publish to npm automatically. If a release must be made outside that path, maintainers can use the Publish NPM GitHub workflow with the required secret, or manually run bin/publish-npm with NPM_TOKEN set. The package metadata reinforces that this is a public Apache-2.0 package named openai, but publishing should remain a maintainer operation, not part of ordinary contribution testing.

Sources: CONTRIBUTING.md, package.json

Practical Next Steps

For most contributors, the safest path is: install the pinned pnpm, run pnpm install, run pnpm build, make the smallest change in a non-generated area when possible, validate with linting and tests, and then open a pull request with context. If your goal is to change an API resource or generated type, open an issue or explain the generator impact in the pull request. If your goal is to teach usage, add or update an example, because examples are explicitly protected from generator rewrites.

Sources: CONTRIBUTING.md, .github/pull_request_template.md, package.json

Ask a question...