Providers and factories

This page explains how you create a provider, what every provider contains and how the Lite factories differ.

Factories

github() and the other provider functions return a factory. A factory holds the options and builds the provider when you call create(). No request goes out until you call a method on the provider.

import { github } from 'forges/github'

const factory = github({
  auth: { type: 'token', token: process.env.GITHUB_TOKEN! },
})
const gh = factory.create()

createForges() accepts factories and calls create() on each one. This lets you describe providers in one place and build them where you need them.

The provider interface

Every provider has the same shape. It has kind, instance, baseUrl and capabilities, plus namespaces for the operations: repos, threads, notifications, checks, ci, contents, releases, webhooks, search, securityAlerts, installations, users and sources. Reviews live on threads. The provider API reference lists them.

All namespaces exist on all providers. An operation the forge lacks is present and rejects, so TypeScript doesn't force a cast at each call site. Use can() to decide at run time.

Escape hatch

provider.request() sends a request to an endpoint relative to baseUrl, or to an absolute HTTP(S) URL, with the provider's authentication, user agent, timeout and error mapping. Use it for an endpoint that the model doesn't cover.

A request to another origin leaves out the provider's credentials and default headers.

Lite factories

Every provider except pushin.eu has a second factory, such as githubLite(). It builds the same provider without webhook ingestion. A browser doesn't receive deliveries, so a Lite bundle leaves out signature verification and payload translation. See Browser bundles.

Subpath exports

Each provider has its own subpath, such as forges/gitlab. The root entry re-exports all of them. The package declares sideEffects: false, so bundlers can tree-shake the root entry, and a subpath import states the dependency.

Writing your own

A provider is one call to defineForgeProvider(). See Write a provider.