> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/clyrisai/gitresolve/llms.txt
> Use this file to discover all available pages before exploring further.

# GitResolve Browser Providers: Fetch, Puppeteer & Browserless

> Compare GitResolve's three browser providers — fetch, Puppeteer, and Browserless — and learn how auto-detection and the BROWSER_PROVIDER variable work.

GitResolve fetches profile pages from GitHub, GitLab, and Bitbucket before extracting structured data from them. Because many modern portfolio sites are single-page applications built with React, Vue, or similar frameworks, a plain HTTP download would return an empty shell — the real content only appears after JavaScript runs. Browser providers are the pluggable layer that decides *how* a page is retrieved, ranging from a lightweight native-fetch call all the way to a full headless Chromium instance.

## Provider comparison

| Provider      | Requires                       | JS rendering | Best for                                                 |
| ------------- | ------------------------------ | ------------ | -------------------------------------------------------- |
| `fetch`       | Nothing (Node 18+ built-in)    | ❌ No         | Static sites, GitHub/GitLab profiles, CI with no browser |
| `puppeteer`   | Puppeteer (bundled dependency) | ✅ Yes        | Local development, SPAs, maximum compatibility           |
| `browserless` | Running Browserless container  | ✅ Yes        | Production servers, Docker/CI, no local binary           |

<Note>
  Puppeteer is listed as a direct dependency of `@clyrisai/gitresolve` and is installed automatically when you run `npm install @clyrisai/gitresolve`. You do not need a separate install step for local use.
</Note>

## Auto-detection

When no provider is specified, `createProvider()` walks a fixed resolution chain and returns the first available option.

<Steps>
  <Step title="Check the explicit argument">
    If you called `createProvider('puppeteer')`, GitResolve attempts to use exactly that provider. If it is not available, an error is thrown immediately — there is no silent fallback to a different provider.
  </Step>

  <Step title="Check the BROWSER_PROVIDER environment variable">
    If no argument was passed, GitResolve reads `process.env.BROWSER_PROVIDER`. If the variable is set, it behaves as though you had passed that value explicitly, including the hard failure if the provider is unavailable.
  </Step>

  <Step title="Try Puppeteer">
    With no explicit preference, GitResolve tries to import `puppeteer`. If the module resolves successfully, `PuppeteerProvider` is returned.
  </Step>

  <Step title="Try Browserless">
    If Puppeteer is not importable, GitResolve probes `BROWSERLESS_URL` (defaulting to `http://localhost:3000`) with a 3-second `GET /json/version` health check. If the server responds, `BrowserlessProvider` is returned.
  </Step>

  <Step title="Fall back to Fetch">
    `FetchProvider` is always available on Node 18+ and is used as the final fallback. No installation or configuration is required.
  </Step>
</Steps>

## Forcing a specific provider

There are two ways to override auto-detection.

**Environment variable** — set once, applies to every run in that shell session:

```bash theme={null}
export BROWSER_PROVIDER=puppeteer
```

**Programmatic API** — pass the provider name to `createProvider`:

```typescript theme={null}
import { createProvider } from '@clyrisai/gitresolve';

const provider = await createProvider('puppeteer');
```

<Warning>
  If the requested provider is not available, `createProvider` throws `Error: Requested provider 'puppeteer' is not available`. It will **not** silently fall back to another provider when a preference is expressed.
</Warning>

## Choose your provider

<CardGroup cols={3}>
  <Card title="Fetch" icon="bolt" href="/providers/fetch">
    Zero-dependency, always available. Uses Node's native fetch. No JavaScript execution — ideal for static sites and constrained environments.
  </Card>

  <Card title="Puppeteer" icon="browser" href="/providers/puppeteer">
    Full headless Chromium bundled as a dependency. Executes JavaScript and handles SPAs. Best for local development and maximum compatibility.
  </Card>

  <Card title="Browserless" icon="server" href="/providers/browserless">
    Delegates rendering to a remote Browserless container over REST. No local binary needed — the right choice for production servers and CI/CD pipelines.
  </Card>
</CardGroup>