octokit.js

Octokit is the official GitHub SDK for JavaScript, bundling GitHub’s core Octokit libraries into a single, universal package. It combines a REST and GraphQL API client, a GitHub App and OAuth client, and a pre-authenticated Action client, so you can call any part of GitHub’s platform APIs from browsers, Node.js, or Deno.

Built as a thin, pre-configured composition over @octokit/core and its plugin ecosystem, Octokit ships with authentication, automatic pagination, request retries, and rate-limit throttling wired in by default, while remaining fully decomposable and extendable through plugins.

What You Get

• A unified Octokit client exposing typed REST endpoint methods (octokit.rest.*), a raw octokit.request(), and GraphQL queries against GitHub’s APIs.
• App and OAuthApp clients for GitHub App authentication, installation tokens, webhook handling, and OAuth flows, including a ready-made Node middleware.
• Built-in best-practice plugins: automatic pagination (REST and GraphQL), request retries, and rate-limit/secondary-rate-limit throttling enabled by default.
• Full TypeScript declarations and 100% test coverage across the underlying libraries, with universal ESM builds for browser, Node, and Deno.

Common Use Cases

• Building GitHub integrations, bots, and automation that read from and write to the REST and GraphQL APIs.
• Authenticating as a GitHub App and acting on behalf of installations to open issues, manage repos, or respond to events.
• Handling GitHub webhooks and OAuth login flows in a Node server via the provided App SDK and middleware.
• Scripting repository tasks inside GitHub Actions with the pre-authenticated Action client.

Under The Hood

Architecture — Octokit is a deliberately thin composition layer rather than a monolith. src/octokit.ts takes Octokit from @octokit/core and applies five plugins — restEndpointMethods, paginateRest, paginateGraphQL, retry, and throttling — then calls .defaults() to bake in a userAgent and default onRateLimit/onSecondaryRateLimit handlers. src/app.ts similarly wraps @octokit/app and @octokit/oauth-app, calling .defaults({ Octokit }) so the App and OAuthApp clients construct pre-configured Octokit instances. src/index.ts re-exports Octokit, App, OAuthApp, createNodeMiddleware, and RequestError, giving a single import surface over the whole library family.

Tech Stack — Written in TypeScript (ESM, with a type: module package and Node >= 20). Its runtime dependencies are entirely the scoped @octokit/* packages (core, app, oauth-app, the paginate/retry/throttling/rest-endpoint plugins, request-error, types, webhooks). Build uses a custom scripts/build.mjs plus tsc and esbuild; tests run on Vitest with v8 coverage; nock and mockdate provide HTTP and time mocking. Conditional exports require consumers to use node16 module resolution.

Code Quality — The library states 100% test coverage across its underlying libraries. This top-level package keeps test/ focused on integration and smoke concerns (app.test.ts, smoke.test.ts) plus a typescript-validate.ts type-level test run under strict tsc flags. The throttle callbacks are cleanly separated and annotated with v8-ignore preserve comments; naming is consistent and idiomatic. Because the real logic lives in the composed @octokit/* packages, this repo is intentionally small and readable.

API Design — Ergonomics are a core selling point. A single new Octokit({ auth }) yields typed octokit.rest.* methods, a raw octokit.request(), GraphQL queries, and automatic pagination, with retries and throttling on by default so most users need no configuration. Authentication is swappable via authStrategy, and App/OAuthApp collapse multi-step GitHub App flows into a few lines. The README is extensive with copy-paste examples for browsers, Deno, and Node, keeping the getting-started boilerplate minimal.