Skip to main content
Version: Next

abstractRemoteBrowserProvider <TContext>

Abstract base class for remote browser service providers.

Implement this class to encapsulate the lifecycle of a remote browser session (creation, connection URL resolution, and cleanup). RemoteBrowserPool calls connect once per browser launch and release when the browser closes, crashes, the pool is destroyed, or the connection fails during launch.

Pass the provider instance as the endpoint of a RemoteBrowserPool, then hand the pool to a crawler via its browserPool option:

const browserPool = new RemoteBrowserPool({
    browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
    endpoint: new MyProvider(),
});

const crawler = new PlaywrightCrawler({ browserPool });

Example — simple static endpoint (e.g. Browserless):

class BrowserlessProvider extends RemoteBrowserProvider {
    maxOpenBrowsers = 2; // respect the service's concurrent session limit

    async connect() {
        return { url: `wss://production-sfo.browserless.io?token=${token}` };
    }
}

Example — session lifecycle with concurrency limit (e.g. Browserbase):

class BrowserbaseProvider extends RemoteBrowserProvider<{ id: string }> {
    maxOpenBrowsers = 2; // respect the service's concurrent session limit

    async connect({ proxyUrl } = {}) {
        const session = await createSession(apiKey, projectId, {
            proxies: proxyUrl ? [{ type: 'external', server: proxyUrl }] : undefined,
        });
        return { url: session.connectUrl, context: { id: session.id } };
    }

    async release(context: { id: string }) {
        await releaseSession(apiKey, context.id);
    }
}

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

optionalmaxOpenBrowsers

maxOpenBrowsers?: number

Maximum number of browsers that can be open at the same time. Set this to your remote service's concurrent session limit to avoid 429 errors.

Methods

abstractconnect

  • connect(options): Promise<{ context?: TContext; url: string }> | { context?: TContext; url: string }

  • Called once per browser launch. Return the WebSocket/CDP endpoint URL and an optional context object that will be passed back to release.

    Parameters

    • optionaloptions: { proxyUrl?: string }
      • optionalproxyUrl: string

        The proxy URL resolved by Crawlee's proxy configuration for this browser session. Pass it to your remote service's proxy API if supported.

    Returns Promise<{ context?: TContext; url: string }> | { context?: TContext; url: string }

release

  • release(_context): Promise<void>

  • Called when the browser closes, crashes, the pool is destroyed, or the connection fails right after connect succeeds. Override this to clean up remote sessions, release API resources, etc.

    Errors thrown here are caught and logged as warnings — they never crash the crawler. Safe to assume this is called at most once per connect call.

    Parameters

    • _context: TContext

      The same context object returned by connect.

    Returns Promise<void>

Page Options