Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
develop
✓ import { develop } from 'extension-develop';
✗ const develop = require('extension-develop');
The primary programmatic entry point to start the development server. ESM-only for programmatic use cases.
BuildEmitter
✓ import { BuildEmitter } from 'extension-develop';
Access the event emitter for build lifecycle events when using `develop` programmatically.
DevelopOptions
✓ import type { DevelopOptions } from 'extension-develop';
✗ import { DevelopOptions } from 'extension-develop';
TypeScript type for configuring the `develop` function. Use `import type` for type-only imports.
This quickstart demonstrates how to programmatically start the extension development server, subscribe to build events using the BuildEmitter, and configure development options for a project. It uses a fictional API key environment variable for demonstration.
import { develop, BuildEmitter } from 'extension-develop';
import path from 'node:path';
const projectRoot = path.resolve('./my-extension-project');
async function startDevServer() {
const emitter = new BuildEmitter();
emitter.on('build_start', () => console.log('Build started...'));
emitter.on('build_end', (result) => {
if (result.success) {
console.log(`Build successful in ${result.durationMs}ms`);
} else {
console.error('Build failed:', result.errors);
}
});
emitter.on('extension_reload', () => console.log('Extension reloaded in browser.'));
try {
const devProcess = await develop({
root: projectRoot,
port: 8000,
browser: 'chromium',
open: true,
install: true,
logger: console,
emitter,
// Example env vars for a content script or background script
env: { API_KEY: process.env.MY_API_KEY ?? 'default_api_key' }
});
console.log(`Development server running on port ${devProcess.port}`);
console.log(`Open your browser to ${devProcess.url}`);
// To stop the server programmatically after some time (e.g., for testing)
// setTimeout(() => {
// devProcess.close();
// console.log('Development server closed.');
// }, 60000);
} catch (error) {
console.error('Failed to start development server:', error);
process.exit(1);
}
}
startDevServer();
extension-develop --version
Debug
Known issues
breakingThe `extensionStart` function was removed from the programmatic API. The CLI now orchestrates the build and preview steps. When using `develop` programmatically, ensure you're passing all necessary options, as `extensionStart` is no longer a separate, low-level entry point.fixMigrate programmatic usage from `extensionStart` to the `develop` function, consolidating build and preview configurations directly into `develop`'s options object.
affects: >=3.13.0
securityA vulnerability in the `follow-redirects` dependency (GHSA-r4q5-vmmm-2653) could lead to authentication header leakage during redirects. This affects network requests made internally by the CLI.fixUpgrade to `extension-develop@3.14.0` or higher once released, or the corresponding next version if running pre-releases (e.g., `3.14.0-next.0`).
affects: >=3.14.0-next.0 (fix shipped in next, stable update pending)
securityA critical Preact VNode injection vulnerability (CVE-2026-22028) was identified and fixed. This could potentially allow arbitrary code execution in certain contexts if user-controlled input was rendered via Preact components within the extension.fixUpgrade to `extension-develop@3.12.0` or higher to receive the patch for CVE-2026-22028. Regularly check for security advisories.
affects: >=3.12.0
gotchaPrior to version 3.13.5, setting the `--port` flag to `0` (which typically requests an OS-assigned ephemeral port) would cause the development server to crash. This has been resolved.fixIf using an older version, avoid setting `--port 0` and instead specify a fixed, available port number. Upgrade to `extension-develop@3.13.5` or later to safely use `--port 0`.
affects: <3.13.5
gotchaIssues were reported with user project dependency resolution when using package managers like `pnpm dlx` or `npx` for building. This could lead to build failures due to missing dependencies in the user's project context.fixUpgrade to `extension-develop@3.13.4` or later, which includes fixes for improved user project dependency resolution across various package managers.
affects: <3.13.4
Errors
Common errors & fixes
Error: A valid port was not provided or could not be assigned. The dev server crashed.
Using `--port 0` to request an OS-assigned port on versions prior to 3.13.5.
fixUpgrade to `extension-develop@3.13.5` or later, or specify a specific, available port number (e.g., `extension-develop --port 8000`).
Error: Authentication header potentially leaked during redirect to an external domain.
The `follow-redirects` dependency, used internally by the CLI, had a vulnerability (GHSA-r4q5-vmmm-2653).
fixUpgrade to `extension-develop@3.14.0` (or `3.14.0-next.0` for pre-release) or higher to get the patched version of `follow-redirects`.
Error: Failed to resolve project dependencies. Are they installed correctly?
Issues with user project dependency resolution, particularly when using `pnpm dlx` or `npx` for CLI execution, prior to version 3.13.4.
fixUpgrade to `extension-develop@3.13.4` or later. Ensure your project's `node_modules` are correctly installed by running `npm install`, `yarn install`, or `pnpm install` in your project root.
Audit
Dependencies
No dependency data recorded yet.