Browser Extensions

Using Extensions

note

Extension support is only available when using the Chromium browser.
If you don't specify a browser, Chromium is used by default.

Browserless allows you to upload and use your own browser extensions in your automation sessions. Extensions must be uploaded through your account dashboard and can then be referenced by name in your launch options.

Extension Upload

1. Navigate to the Extensions section in your account dashboard
2. Upload your extension as a ZIP file containing the extension directory (max 100 MB)
3. Once uploaded, extensions can be referenced by their assigned name

Demo Extension

You can find a demo extension in this link. This extension adds the "Hello from extension" text to the body element of every page, making it easy to verify that your extension is working correctly.

Extension Launch Parameter

Use the extensions parameter in your launch options to load extensions:

Puppeteer

import puppeteer from "puppeteer-core";

// Define launch options
const launchArgs = {
  extensions: ['extension_name_01', 'extension_name_02']
};

// Create query parameters
const queryParams = new URLSearchParams({
  token: 'YOUR_API_TOKEN_HERE',
  timeout: '180000',
  launch: JSON.stringify(launchArgs)
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?${queryParams.toString()}`,
});
const page = await browser.newPage();

Playwright CDP

import playwright from "playwright";

// Define launch options
const launchArgs = {
  extensions: ['extension_name_01', 'extension_name_02']
};

// Create query parameters
const queryParams = new URLSearchParams({
  token: 'YOUR_API_TOKEN_HERE',
  timeout: '180000',
  launch: JSON.stringify(launchArgs)
});

const browser = await playwright.chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?${queryParams.toString()}`
);

// Extensions are loaded in the default context
// Always use the default context to access extensions
const context = await browser.contexts()[0];
const page = await context.newPage();

Important Implementation Detail

Extensions are loaded in the default context only. When using Playwright, you must create your pages from the default context (browser.contexts()[0]) to access the loaded extensions. Creating new contexts will not have access to the extensions.

Extension Requirements

• File Format: Extensions must be uploaded as ZIP files containing the extension directory structure
• File Size: Maximum extension size is 100 MB
• Naming: Extension names in the extensions array correspond to the names assigned during upload
• Compatibility: Extensions must be compatible with Chromium-based browsers

Best Practices

• Test Locally First: Always test your extension in a local Chrome browser before uploading
• Keep Extensions Small: Larger extensions increase session startup time
• Use Descriptive Names: Give your extensions clear, descriptive names for easier management
• Version Control: Consider versioning your extensions if you make frequent updates

Troubleshooting

Extension Not Loading?

• Verify the extension name matches exactly what's shown in your dashboard
• Check that the extension ZIP file contains the proper directory structure
• Ensure the extension is compatible with Chromium

Session Taking Too Long to Start?

• Reduce the number of extensions loaded simultaneously
• Check extension file sizes
• Consider if all extensions are necessary for your use case

Extension Not Working as Expected?

• Test the extension locally first
• Check browser console for any extension errors
• Verify the extension's manifest.json is valid

note

Sessions with extensions can take more time to start since we need to load the extension in real time. The startup time increases with the number and size of extensions loaded.