Skip to main content

Documentation Index

Fetch the complete documentation index at: https://extension.js.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Run any GitHub extension in 30 seconds

The sections below cover both paths. You will learn what Extension.js treats as a project root and how it resolves ambiguous inputs like a bare sample name.

​
How dev resolves the project

extension dev accepts an optional first argument. Resolution works like this:
  • No argument: Uses the current working folder as the extension project.
  • Local path: Extension.js treats this as a path relative to the current working folder (for example, ./my-extension or ../samples/page-redder after you clone a repository).
  • https://github.com/... URL: Extension.js fetches the repository (or tree path) into your working folder, then builds from the extracted folder. For details, see Project detection and inputs.
  • Other http(s) URLs: Extension.js treats the URL as a ZIP archive, downloads it, and extracts it locally.
A bare name like sample.page-redder is not a remote fetch; it is only a folder name under your current folder. Use a full GitHub URL, or clone first and point dev at the path.

​
Run Chrome extension samples fast

Use samples from the Chrome Extension Samples repository to validate your setup and learn the workflow quickly.
  1. Open your terminal.
  2. cd to the folder where cloned/extracted projects should appear (often an empty folder).
  3. Run:
npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
Extension.js fetches the sample, builds it, and launches Chrome with the extension loaded. Browse Chrome Extension Samples for more URLs to try. To target a different browser, append --browser=firefox or --browser=edge.

​
How dev resolves the project

extension dev accepts an optional first argument. Resolution works like this:
  • No argument: Uses the current working folder as the extension project.
  • Local path: Extension.js treats this as a path relative to the current working folder (for example, ./my-extension or ../samples/page-redder after you clone a repository).
  • https://github.com/... URL: Extension.js fetches the repository (or tree path) into your working folder, then builds from the extracted folder. For details, see Project detection and inputs.
  • Other http(s) URLs: Extension.js treats the URL as a ZIP archive, downloads it, and extracts it locally.
A bare name like sample.page-redder is not a remote fetch. It is only a folder name under your current folder. Use a full GitHub URL, or clone first and point dev at the path.

​
Clone first, then dev a local path

When you want a stable folder layout (rather than a one-shot try), clone the repository and point dev at a local path: 
git clone https://github.com/GoogleChrome/chrome-extensions-samples.git
cd chrome-extensions-samples/functional-samples/sample.page-redder
npx extension@latest dev .
Browse more samples in Chrome Extension Samples.

​
Run samples in Microsoft Edge

Extension.js supports Microsoft Edge with no extra configuration.

​
Full URL with Edge

npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge

​
Clone first, then Edge

git clone https://github.com/GoogleChrome/chrome-extensions-samples.git
cd chrome-extensions-samples/api-samples/topSites/magic8ball
npx extension@latest dev . --browser=edge
This example follows the magic8ball sample.

​
Run Mozilla extensions in Edge with polyfill

You can run MDN WebExtensions examples in Edge. Pass the GitHub tree URL and enable the polyfill (a compatibility layer). The polyfill maps Firefox-style browser.* calls to Chrome-style chrome.* calls, so your Firefox-oriented extension works in Chromium-based browsers. 
npx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true

​
Clone first, then polyfill + Edge

git clone https://github.com/mdn/webextensions-examples.git
cd webextensions-examples/apply-css
npx extension@latest dev . --browser=edge --polyfill=true
This follows the Apply CSS example from MDN WebExtensions Examples.

​
Create a minimal extension from scratch

Use extension create with the init template for the lightest possible starting point: a manifest and icons, no framework or UI surface.

​
init

init template screenshot 
npx extension@latest create my-extension --template=init
Repository: extension-js/examples/init

​
Quick tips

  • Use TypeScript: Add a tsconfig.json file to your project root.
  • Use React: Add react and react-dom to your package.json.
  • A tsconfig.json configured for React enables TypeScript + React authoring.
  • If you need to handle assets not declared in the manifest, learn more about Special folders.

​
Best practices

  • Use the extension package to build, run, and bundle your extension from one toolchain.
  • Use --browser to target a specific browser while developing.
  • Use --polyfill when adapting Mozilla-oriented examples for Chromium-based browsers.
  • Prefer full GitHub URLs for one-shot tries; clone + local path when you want a stable folder layout.

​
Next steps