octokit.js: one package, three clients, and a tsconfig you must edit

The package is three libraries, and you only need one of them

The `octokit` package is described as the all-batteries-included GitHub SDK for browsers, Node.js and Deno, and it is really an integration of three separate libraries.

The first is the API client, which covers REST API requests, GraphQL API queries and authentication. The second is the App client, which covers GitHub Apps and installations, webhooks and OAuth. The third is the Action client, a pre-authenticated API client scoped to a single repository, which is the one you want inside a GitHub Action.

The consequence is that you are picking a bundle rather than an API. If you only need REST calls, the README points at the standalone minimal Octokit, `@octokit/core`, and calls the decomposable part of the design the tradeoff between functionality and bundle size.

In a browser there is no bundler step, just an esm.sh import

The three runtimes are handled with three different instructions. On Node you install the package and import from it:

import { Octokit, App } from "octokit";

In a browser you skip the install and import from a URL inside a module script:

<script type="module">
import { Octokit, App } from "https://esm.sh/octokit";
</script>

Deno does the same thing with a type suffix on the URL:

import { Octokit, App } from "https://esm.sh/octokit?dts";

So there is no documented build step for a browser page, which is convenient for a demo and means the same import specifier does not work everywhere. If you bundle, you are resolving a different specifier than the one in the README.

Conditional exports break older module resolution, and the fix is two tsconfig keys

The README puts an IMPORTANT note directly under the usage table, and it is the first thing to hit in a TypeScript project. Because the package uses conditional exports, your tsconfig.json needs `"moduleResolution": "node16"` and `"module": "node16"`.

Conditional exports are how the package serves different entry points per environment and per import style. Older resolution settings ignore the exports map and look for a file path instead, so the import fails or the types go missing. The README links the TypeScript documentation on package.json exports and an external guide on transitioning to ESM.

The practical consequence is a floor on your build configuration, not just on your Node version. A CommonJS project that cannot move cannot use this package, and that is a reason to reach for the smaller `@octokit/core` or to call fetch yourself.

userAgent is mandatory, and your string is prepended to the default

Setting a user agent is required for all requests sent to GitHub's platform APIs. The default looks like `octokit.js/v1.2.3 Node.js/v8.9.4 (macOS High Sierra; x64)`, and the recommendation is to set your own, which prepends the default one:

const octokit = new Octokit({
  userAgent: "my-app/v1.2.3",
});

Prepend, not replace, is the detail worth remembering. The SDK version and the runtime identification stay in the header, so GitHub's logs still tell you which client made the call.

The other constructor options in the same table are `authStrategy`, a function defaulting to `@octokit/auth-token`, `auth`, which takes a personal access token as a string or an object unless you changed the strategy, and `baseUrl`. The advanced `request` object adds `request.signal` for an AbortController, `request.fetch` to replace the built-in fetch, and `request.timeout`, which is Node only and defaults to 0.

baseUrl is the whole GitHub Enterprise Server story

Pointing the client at a GitHub Enterprise Server instance is one option rather than a second client. Set `options.baseUrl` to the root URL of the API, and for a host at `github.acme-inc.com` that means:

const octokit = new Octokit({
  baseUrl: "https://github.acme-inc.com/api/v3",
});

The `/api/v3` suffix is the part people leave out. Enterprise Server exposes its REST API under a versioned path, and the client does not add it for you.

Beyond that, the README's table of contents shows the rest of the surface you inherit with the API client: proxy servers (Node.js only) with a section on missing fetch, the `octokit.rest` endpoint methods against `octokit.request()`, pagination for both REST and GraphQL, media type formats, request error handling through `@octokit/request-error`, and schema previews for GraphQL.

The dependency list is the architecture: eight @octokit packages

Look at what the package depends on and the shape of the library is visible. `@octokit/core` is the client itself. `@octokit/plugin-rest-endpoint-methods` is what produces the `octokit.rest.*` methods, and `@octokit/plugin-paginate-rest` and `@octokit/plugin-paginate-graphql` are the two pagination strategies. `@octokit/plugin-throttling` and `@octokit/plugin-retry` handle rate limits and transient failures, `@octokit/request-error` gives you the error type, and `@octokit/types` carries the declarations.

The App side is three more: `@octokit/app` for Apps and installations, `@octokit/webhooks` for verifying and dispatching webhooks, and `@octokit/oauth-app` for OAuth, which the table of contents splits into an App server flow and a browser flow.

That composition is also the extension story. The README's own claim is that a missing feature can be added with plugins, by hooking into the request or webhook lifecycle, or by implementing your own authentication strategy, and that a few lines can assemble a smaller Octokit from these pieces. The feature list claims 100% test coverage across the libraries and extensive TypeScript declarations.

The manifest says 0.0.0-development, npm says 5.0.5

The version field in the repository's package.json reads `0.0.0-development`, which is not a mistake and not a broken release process. The manifest also carries a `release` section with a branch pattern, and the development dependencies include semantic-release-plugin-update-version-in-files, so the published version is derived from commit messages when a release branch is cut.

What reaches npm is a normal semver line: v5.0.5 on 2025-10-31, v5.0.4 on 2025-10-17 and v5.0.3 on 2025-05-27. The last push to main was on 2026-10-28.

Two build details are worth copying if you fork it. `build` runs a script from `scripts/` and then tsc against tsconfig.json, and `test` runs vitest with coverage, with the lint step wired in as `pretest`. There is a separate `test:typescript` script that type checks a fixture file with `--strict` and `--exactOptionalPropertyTypes`, which is how the declarations get validated against real code.

Editorial conclusion

octokit suits a Node or Deno service that talks to GitHub across REST, GraphQL, webhooks and App installations, and that wants one dependency instead of five. It does not suit a CommonJS project that cannot move to node16 module resolution, and it is heavier than you need if you only call one endpoint, because the README's own answer for that is to build a smaller Octokit from the underlying libraries. Verify three things before you install: that your tsconfig sets module and moduleResolution to node16, since the package relies on conditional exports and will not resolve otherwise, whether you need the App client and the Action client at all, and what your userAgent string says, because GitHub requires one on every request and the default identifies the SDK rather than your application.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. octokit/octokit.js on GitHub
4. README
5. Releases