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.

完全なインストールガイドと統合プロンプトは購入後に解放されます。