Skip to main content

​
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:
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:
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

​
Clone first, then 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.

​
Clone first, then polyfill + Edge

This follows the Beastify example from MDN WebExtensions Examples. It is a Manifest V3 example that calls the Firefox-style browser.* APIs, which is what the polyfill translates. Manifest V2 examples (such as Apply CSS) cannot run in Edge at all, because modern Chromium refuses to load MV2: run those with --browser=firefox instead.

​
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
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