puppeteer-chrome-debugger-transport

Use puppeteer-core in your browser extension's background page or service worker. This package provides a transport layer that uses Chrome's chrome.debugger extension API to communicate with the Chrome DevTools Protocol.

Features

• ✨ Use Puppeteer in browser extensions
• 🔌 Built on Chrome's native debugger API
• 🚀 Works in both Manifest V2 and V3 extensions
• 📦 Lightweight with minimal dependencies
• 🎯 Full TypeScript support

Installation

npm install puppeteer-chrome-debugger-transport puppeteer-core

Prerequisites

Your extension must have the debugger permission in manifest.json:

Manifest V2

{
  "permissions": [
    "debugger",
    "tabs"
  ]
}

Manifest V3

{
  "permissions": [
    "debugger",
    "tabs"
  ]
}

Usage

Basic Example

import puppeteer from 'puppeteer-core/lib/cjs/puppeteer/web'
import { ExtensionDebuggerTransport } from 'puppeteer-chrome-debugger-transport'

async function run(tabId) {
    // Create transport connected to the tab
    const extensionTransport = await ExtensionDebuggerTransport.create(tabId)
    
    // Connect puppeteer using the transport
    const browser = await puppeteer.connect({
        transport: extensionTransport,
        defaultViewport: null,
    })

    // Use first page from pages instead of using browser.newPage()
    const [page] = await browser.pages()

    await page.goto('https://wikipedia.org')

    // Take a screenshot
    const screenshot = await page.screenshot({
        encoding: 'base64',
    });
    console.log(`data:image/png;base64,${screenshot}`)

    // Interact with the page
    const englishButton = await page.waitForSelector('#js-link-box-en > strong')
    await englishButton.click()

    const searchBox = await page.waitForSelector('#searchInput');
    await searchBox.type('telephone')
    await page.keyboard.press('Enter')

    // Clean up
    await page.close();
}

// Create a new tab and run automation
chrome.tabs.create(
    {
        active: true,
        url: 'https://www.google.co.in',
    },
    tab => (tab.id ? run(tab.id) : null)
)

Using with Existing Tab

You can also attach to an existing tab:

// Get the active tab
chrome.tabs.query({ active: true, currentWindow: true }, async (tabs) => {
    if (tabs[0]?.id) {
        await run(tabs[0].id);
    }
});

Error Handling

async function runWithErrorHandling(tabId) {
    try {
        const extensionTransport = await ExtensionDebuggerTransport.create(tabId)
        
        const browser = await puppeteer.connect({
            transport: extensionTransport,
            defaultViewport: null,
        })

        const [page] = await browser.pages()
        await page.goto('https://example.com')
        
        // Your automation code here
        
    } catch (error) {
        console.error('Automation failed:', error)
    }
}

API

ExtensionDebuggerTransport

static async create(tabId: number): Promise<ExtensionDebuggerTransport>

Creates and initializes a new transport instance connected to the specified tab.

Parameters:

• tabId (number): The Chrome tab ID to attach the debugger to

Returns: Promise that resolves to an initialized ExtensionDebuggerTransport instance

Throws: Error if the debugger fails to attach

send(message: string): void

Sends a Chrome DevTools Protocol command. This is called internally by Puppeteer.

close(): void

Closes the debugger connection and cleans up resources.

Important Notes

Don't Use browser.newPage()

When using this transport, you should not call browser.newPage(). Instead, use the existing page:

// ✅ Correct
const [page] = await browser.pages()

// ❌ Incorrect
const page = await browser.newPage()

Tab Management

The debugger attaches to a specific tab. If the tab is closed, the connection will be terminated.

Permissions

Make sure your extension has the debugger permission, otherwise the connection will fail.

Chrome Extensions Only

This package only works in Chrome/Chromium-based browser extensions that support the chrome.debugger API.

Limitations

• Only works in Chrome/Chromium-based browsers
• Requires the debugger permission
• Cannot create new tabs via browser.newPage() (must use existing tabs)
• When debugger is attached, a notification appears in the browser

Examples

Check out the examples directory for more use cases:

• Basic automation
• Screenshot capture
• Form filling
• Web scraping in extensions

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• puppeteer
• puppeteer-core

Support

If you encounter any issues or have questions, please open an issue on GitHub.