No native modules, pod installs, or prebuild steps are required. The library uses only Node.js built-ins (fs, path, child_process) available in Node 18+.

Project setup

1. Copy the source/ directory into your project, e.g. src/puppeteer-core/.

2. In tsconfig.json, ensure moduleResolution is "NodeNext" or "Bundler", and add path aliases if you rename the directory:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "strict": true,
    "paths": {
      "puppeteer-core": ["./src/puppeteer-core/puppeteer-core.ts"]
    }
  }
}

3. Set the PUPPETEER_EXECUTABLE_PATH environment variable (or pass executablePath at launch time) to point at a Chrome or Firefox binary, since puppeteer-core does not download one:

export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

4. In your entry file, import from puppeteer-core.ts for Node.js usage or from puppeteer-core-browser.ts for browser/ESM environments.

5. If using ESM, add "type": "module" to package.json and use .js extensions in internal imports (the source already does this).

Public API

connect

import { connect } from 'puppeteer-core';

const browser = await connect(options: BrowserConnectOptions): Promise<Browser>;

Connects to a pre-existing browser instance over CDP or BiDi using a browserWSEndpoint, browserURL, or a custom transport. Use this when the browser is already running (e.g., launched externally or by another process) and you only need to attach a control session.

launch

import { launch } from 'puppeteer-core';

const browser = await launch(options?: PuppeteerLaunchOptions): Promise<Browser>;

Spawns a new browser process and returns a connected Browser instance. Requires executablePath in options or the PUPPETEER_EXECUTABLE_PATH env var. Use this as the primary entry point for server-side automation scripts.

executablePath

import { executablePath } from 'puppeteer-core';

const path: string = executablePath(channel?: string): string;

Returns the resolved file-system path to the browser executable puppeteer-core would use for the given channel. Useful for validating environment setup or passing the path to other tools. Always call this before launch during CI setup to surface missing-binary errors early.

defaultArgs

import { defaultArgs } from 'puppeteer-core';

const args: string[] = defaultArgs(options?: BrowserLaunchArgumentOptions): string[];

Returns the default CLI flags passed to Chrome/Firefox on launch. Call this to build a customized argument list by spreading the defaults and appending your own flags (e.g., --proxy-server, --disable-gpu).

Working examples

Scenario - Launch a browser and take a screenshot

Launches a local Chrome instance, navigates to a URL, captures a full-page screenshot, and closes the browser.

import { launch } from 'puppeteer-core';

async function screenshot() {
  const browser = await launch({
    executablePath: '/usr/bin/google-chrome',
    headless: true,
    args: ['--no-sandbox', '--disable-setuid-sandbox'],
  });
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 800 });
  await page.goto('https://example.com', { waitUntil: 'networkidle2' });
  await page.screenshot({ path: 'example.png', fullPage: true });
  await browser.close();
}

screenshot().catch(console.error);

Scenario - Connect to a running browser and scrape text

Attaches to an already-running Chrome instance via its remote debugging WebSocket URL and extracts text content from the page.

import { connect } from 'puppeteer-core';

async function scrape(wsEndpoint: string) {
  const browser = await connect({ browserWSEndpoint: wsEndpoint });
  const page = await browser.newPage();
  await page.goto('https://news.ycombinator.com');

  const titles = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.titleline > a')).map(
      el => (el as HTMLAnchorElement).innerText
    );
  });

  console.log(titles);
  await browser.disconnect();
  return titles;
}

scrape('ws://127.0.0.1:9222/devtools/browser/<id>').catch(console.error);

Scenario - Use locators and keyboard input

Navigates to a site, fills a search box using the accessible locator API, and clicks a result.

import { launch } from 'puppeteer-core';

async function search() {
  const browser = await launch({
    executablePath: process.env.PUPPETEER_EXECUTABLE_PATH ?? '',
    headless: true,
  });
  const page = await browser.newPage();
  await page.goto('https://developer.chrome.com/');
  await page.setViewport({ width: 1080, height: 1024 });

  await page.keyboard.press('/');
  await page.locator('::-p-aria(Search)').fill('puppeteer');
  await page.locator('.devsite-result-item-link').click();

  const title = await page.title();
  console.log('Navigated to:', title);
  await browser.close();
}

search().catch(console.error);

File walkthrough

• api/ - Abstract base classes (Browser, Page, Frame, ElementHandle, HTTPRequest, JSHandle, etc.) that both CDP and BiDi implementations extend. This is the stable public API surface.
• bidi/ - Concrete implementations of every api/ class using the WebDriver BiDi protocol. Contains browser connector, session management, serialization/deserialization, and network interception.
• bidi/core/ - Thin, protocol-level wrappers over raw BiDi messages: Session, BrowsingContext, Connection, Realm, Request, UserContext. No Puppeteer abstractions here.
• cdp/ - Concrete CDP-based implementations: CdpBrowser, CdpPage, CdpFrame, accessibility tree, input emulation, JavaScript coverage, tracing, etc.
• common/ - Cross-cutting concerns: the Puppeteer base class, custom error types, EventEmitter, timeout utilities, NetworkConditions, device descriptors.
• injected/ - Serialized scripts evaluated inside page contexts: CSS/XPath/ARIA query handlers, MutationObserver-based polling, PierceHandler.
• node/ - Node.js runtime layer: PuppeteerNode (extends Puppeteer), BrowserLauncher, ChromeLauncher, FirefoxLauncher, ScreenRecorder, pipe transport.
• util/ - Low-level helpers: AsyncIterableUtil, Deferred, DisposableStack, Base64 encoding, error guards.
• templates/ - Mustache/string templates used by the build pipeline to generate boilerplate.
• environment.ts - Detects Node.js vs browser runtime; holds a singleton environment.value object that provides fs and ScreenRecorder to the rest of the codebase without hard imports.
• index.ts - Barrel re-export of index-browser.ts plus node/node.js.
• index-browser.ts - Browser-safe barrel: re-exports api/, cdp/, common/, revisions, util/, and protocol types.
• puppeteer-core.ts - Node.js package entry: injects fs/path into environment, constructs PuppeteerNode, and named-exports connect, launch, executablePath, defaultArgs.
• puppeteer-core-browser.ts - ESM/browser entry: constructs a browser-only Puppeteer instance and exports only connect.
• revisions.ts - Exports pinned Chrome and Firefox revision strings used by the launcher to validate browser versions.

Common pitfalls and fixes

• Missing executablePath: puppeteer-core does not download Chrome; launch will throw unless executablePath is set in options or via PUPPETEER_EXECUTABLE_PATH. Fix: always set the env var in CI and local .env.
• ESM/CJS interop: The source uses .js extensions in all internal imports for ESM compatibility. If bundling with Webpack/esbuild targeting CJS, set resolve.extensionAlias or use the tsconfig.cjs.json build config. Fix: use tsconfig.cjs.json for CJS output.
• fs not available in browser: Importing from puppeteer-core.ts in a browser bundle will fail because it imports node:fs. Fix: import from puppeteer-core-browser.ts or index-browser.ts for browser targets.
• Sandbox errors in Docker/Linux: Chrome requires --no-sandbox when running as root or in unprivileged containers. Fix: pass args: ['--no-sandbox', '--disable-setuid-sandbox'] to launch.
• devtools-protocol version mismatch: The CDP type definitions in api/ and cdp/ are tightly coupled to a specific devtools-protocol version. Fix: pin devtools-protocol to the exact version in the upstream puppeteer-core package.json.
• ScreenRecorder not available in browser builds: environment.value.ScreenRecorder throws by design in non-Node environments. Fix: only call page.screencast() / ScreenRecorder APIs in Node.js contexts, never in browser-bundle code paths.

Vibe-coding prompt template

I have the puppeteer-core source code in `source/` and a usage guide in `USAGE.md`.
The upstream package is `puppeteer-core` (from the puppeteer monorepo).

Please help me integrate this into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Identify which entry point I should use: `source/puppeteer-core.ts` (Node.js)
   or `source/puppeteer-core-browser.ts` (browser/ESM).
3. Update my `tsconfig.json` to resolve `puppeteer-core` imports from `source/`.
4. Install all required dependencies listed in `USAGE.md`.
5. Wire the `PUPPETEER_EXECUTABLE_PATH` environment variable into my project config.
6. Write a minimal integration file that imports `launch` or `connect` from the
   source, navigates to a URL, and returns the page title.
7. If I need screenshot, scraping, or keyboard automation, write the relevant
   scenario from `USAGE.md` adapted to my project's structure.
8. Point out any pitfalls from `USAGE.md` that apply to my setup (Docker, ESM,
   browser bundle, etc.) and apply the recommended fixes.

My project structure: [DESCRIBE YOUR PROJECT HERE]
My target environment: [Node.js version, OS, Chrome path, etc.]

License and credit

The source is licensed under the Apache-2.0 license (per the SPDX headers in every file). Full license text is in source/LICENSE if present in your copy.

Upstream package: puppeteer-core - part of the puppeteer monorepo.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.