Skip to main content
You have two common entry points. Point extension dev at a local folder you already cloned, or point it at a GitHub URL to let Extension.js fetch the sample for you. 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. See Project detection and inputs in the develop package README.
  • 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 downloads the sample, then runs the dev workflow against it.

​
Option B: clone first, then dev 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 out of the box.

​
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 by passing the GitHub tree URL and enabling the polyfill. The polyfill maps Firefox-style browser.* API calls to Chrome-style chrome.* calls. This lets your Firefox-oriented extension work 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 — just 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