---
title: "Providers and factories"
description: "How provider functions, factories and Lite variants fit together."
canonical_url: "https://forges.link/concepts/providers"
---
# Providers and factories

> How provider functions, factories and Lite variants fit together.

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

## Factories

Functions such as `github()` don't create a provider right away. They return a factory, which holds the options you passed and builds the provider when you call `create()`. No request goes out until you call a method on the provider.

```ts
import { github } from 'forges/github'

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

Splitting the work in two steps lets you describe your providers in one place and build them where you need them. `createForges()` relies on this too. It accepts factories and calls `create()` on each one.

## The provider interface

Every provider has the same shape, whichever forge it talks to. It has `forge`, `instance`, `baseUrl` and `capabilities`, along with namespaces for the operations: `repos`, `threads`, `notifications`, `checks`, `ci`, `contents`, `releases`, `webhooks`, `search`, `securityAlerts`, `installations`, `users` and `sources`. Reviews live on `threads`. The [provider reference](https://forges.link/reference/provider) lists everything in them.

All of the namespaces exist on all of the providers. If a forge lacks an operation, the method is still there and rejects when you call it, which means TypeScript doesn't force you to cast at every call site. To find out whether an operation will work, use [`can()`](https://forges.link/guides/capabilities) at run time.

## Escape hatch

The model doesn't cover every endpoint of every forge. When you need one that it doesn't, `provider.request()` lets you call it directly. It sends a request to an endpoint relative to `baseUrl`, or to an absolute HTTP(S) URL, and applies the provider's authentication, user agent, timeout and error mapping, just as it does for its own calls.

If you send a request to a different origin, the provider leaves out its credentials and default headers, so a token for one host is never sent to another.

## Lite factories

Every provider except Pushin.eu and Cloudflare Artifacts has a second factory next to the regular one, such as `githubLite()`. It builds the same provider without webhook ingestion. A browser doesn't receive webhook deliveries, so a bundle that uses a Lite factory can leave out the code that verifies signatures and translates payloads. The [Bundling](https://forges.link/guides/bundling) guide has the details.

## Subpath exports

Each provider has a subpath of its own, such as `forges/gitlab`, and the root entry re-exports all of them. The package declares `sideEffects: false`, so bundlers can tree-shake the root entry. Importing from a subpath still has the advantage of stating exactly which forge you depend on.

## Writing your own

If you need a forge that `forges` doesn't support, a provider is a single call to `defineForgeProvider()`. See [Write a provider](https://forges.link/contributing/write-a-provider) to learn how.


## Sitemap

See the full [sitemap](https://forges.link/sitemap.md) for all pages.