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

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.

Auto-detection

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

1. 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.

2. 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.

3. Try Puppeteer

   With no explicit preference, GitResolve tries to import puppeteer. If the module resolves successfully, PuppeteerProvider is returned.

4. 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.

5. Fall back to Fetch

   FetchProvider is always available on Node 18+ and is used as the final fallback. No installation or configuration is required.

Forcing a specific provider

There are two ways to override auto-detection.

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

export BROWSER_PROVIDER=puppeteer

Programmatic API — pass the provider name to createProvider:

import { createProvider } from '@clyrisai/gitresolve';

const provider = await createProvider('puppeteer');

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.

Choose your provider

Fetch

Zero-dependency, always available. Uses Node’s native fetch. No JavaScript execution — ideal for static sites and constrained environments.

Puppeteer

Full headless Chromium bundled as a dependency. Executes JavaScript and handles SPAs. Best for local development and maximum compatibility.

Browserless

Delegates rendering to a remote Browserless container over REST. No local binary needed — the right choice for production servers and CI/CD pipelines.