{"id":16660,"library":"octokit-from-auth","title":"Octokit From Auth","description":"octokit-from-auth simplifies the instantiation of a GitHub Octokit client, abstracting away the complexities of authentication token resolution. It automatically attempts to retrieve a token from `process.env.GH_TOKEN` or by executing `gh auth token` via the `get-github-auth-token` package. The library offers two functions: `octokitFromAuth`, which rejects if no token is found, and `octokitFromAuthSafe`, which resolves to an unauthenticated Octokit instance if no token is available. The current stable version is 0.3.2. Releases are consistent, primarily for dependency updates and minor fixes, with new features introduced in minor versions. It ships with TypeScript types and requires Node.js >=18.3.0. This package differentiates itself by offering a robust, opinionated, and flexible approach to Octokit instantiation and authentication, minimizing boilerplate for interacting with the GitHub API.","status":"active","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/JoshuaKGoldberg/octokit-from-auth","tags":["javascript","typescript"],"install":[{"cmd":"npm install octokit-from-auth","lang":"bash","label":"npm"},{"cmd":"yarn add octokit-from-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add octokit-from-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for creating GitHub API clients.","package":"octokit","optional":false},{"reason":"Used internally to resolve authentication tokens from environment variables or `gh auth token` CLI.","package":"get-github-auth-token","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS `require` will fail. Use named imports for functions.","wrong":"const { octokitFromAuth } = require('octokit-from-auth');","symbol":"octokitFromAuth","correct":"import { octokitFromAuth } from 'octokit-from-auth';"},{"note":"Use named imports; there is no default export. This function returns an unauthenticated Octokit if no token is found.","wrong":"import octokitFromAuthSafe from 'octokit-from-auth';","symbol":"octokitFromAuthSafe","correct":"import { octokitFromAuthSafe } from 'octokit-from-auth';"},{"note":"While octokit-from-auth returns an Octokit instance, the `Octokit` type itself comes from `@octokit/core`, which is a peer/transitive dependency.","wrong":"import { Octokit } from 'octokit-from-auth';","symbol":"Octokit","correct":"import { Octokit } from '@octokit/core';"}],"quickstart":{"code":"import { octokitFromAuth, octokitFromAuthSafe } from 'octokit-from-auth';\n\nasync function run() {\n  // Attempt to create an authenticated Octokit instance.\n  // It will use process.env.GH_TOKEN or `gh auth token` if available.\n  // This function will throw an error if no auth token is found.\n  try {\n    const authenticatedOctokit = await octokitFromAuth();\n    const { data: user } = await authenticatedOctokit.request('GET /user');\n    console.log(`Authenticated as ${user.login}.`);\n  } catch (error) {\n    console.warn(`Could not create authenticated Octokit: ${error.message}`);\n    console.warn('Falling back to safe, unauthenticated Octokit...');\n\n    // Create an Octokit instance that is unauthenticated if no token is found.\n    const unauthenticatedOctokit = await octokitFromAuthSafe();\n    const { data: publicUser } = await unauthenticatedOctokit.request('GET /users/{username}', {\n      username: 'octokit',\n    });\n    console.log(`Accessed public user ${publicUser.login} without authentication.`);\n  }\n}\n\nrun();\n","lang":"typescript","description":"Demonstrates creating both authenticated and unauthenticated Octokit instances using `octokitFromAuth` and `octokitFromAuthSafe`, handling potential authentication failures gracefully."},"warnings":[{"fix":"Use `octokitFromAuthSafe` for scenarios where an unauthenticated Octokit is acceptable, or ensure `process.env.GH_TOKEN` is set or `gh auth token` is configured and available.","message":"The `octokitFromAuth` function will throw an error if it cannot resolve an authentication token. If you need to proceed without authentication when a token is unavailable, use `octokitFromAuthSafe` instead.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project uses `type: \"module\"` in `package.json` or uses `.mjs` files for ESM, and upgrade your Node.js runtime to `18.3.0` or newer.","message":"This package is ESM-only and requires Node.js version 18.3.0 or higher. Attempting to use it in a CommonJS environment or with older Node.js versions will result in import errors.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Consult the changelog for `@octokit/core` (or the specific Octokit package you use) for `v5` to understand potential breaking changes in the underlying API. Update any code directly calling Octokit methods or properties that might have changed.","message":"The underlying `octokit` dependency was updated to `v5` in version 0.3.2. While `octokit-from-auth` itself aims for API stability, direct interactions with the returned `Octokit` instance may be affected by breaking changes introduced in `octokit@v5`.","severity":"breaking","affected_versions":">=0.3.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Convert your consuming script to an ES module by using `import` statements and ensuring your `package.json` specifies `\"type\": \"module\"` or by renaming your file to `.mjs`.","cause":"Attempting to `require()` an ESM-only package in a CommonJS module.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/octokit-from-auth/dist/index.js from .../my-script.js not supported."},{"fix":"Set the `GH_TOKEN` environment variable (e.g., `GH_TOKEN=gho_... node my-script.js`), or ensure the GitHub CLI (`gh`) is installed and authenticated, or explicitly pass an `auth` option to `octokitFromAuth({ auth: 'YOUR_TOKEN' })`.","cause":"The `octokitFromAuth` function could not find an authentication token from `process.env.GH_TOKEN`, `gh auth token`, or the provided options.","error":"Error: No GitHub auth token could be found."}],"ecosystem":"npm"}