Skip to content
ExtForge

Install

Prerequisites

  • Node.js 20 or later. ExtForge uses native ESM and requires the fetch global available in Node 18+, but Node 20 LTS is the tested baseline.
  • A package manager. pnpm is recommended; npm, yarn, and bun all work.
  • A Chromium-based browser for local testing (Chrome, Edge, or Brave). Firefox requires a separate profile. Safari requires Xcode.

Run extforge doctor after installing to confirm your environment is ready. See Verifying the install below.

Per-project install

Install extforge as a dev dependency in your project:

Terminal window
pnpm add -D extforge

Global install

A global install gives you extforge on your PATH for running extforge init outside a project directory.

Terminal window
pnpm add -g extforge

Scaffolding a new project

Run extforge init with a project name to start the interactive wizard:

Terminal window
pnpm dlx extforge init my-extension

The wizard asks:

PromptOptions
Extension nameFree text (letters, numbers, hyphens; max 45 chars)
DescriptionFree text
VersionSemver (e.g. 0.1.0)
UI frameworkReact, Vanilla
CSS frameworkTailwind CSS, Vanilla CSS, None
Target browsersChrome, Firefox, Edge, Safari (multi-select)
Extension featuresPopup, Background, Content Script, Options Page, Side Panel
PermissionsStorage, activeTab, and others (multi-select)

To skip the prompts and accept defaults (React, Tailwind, Chrome + Firefox, popup + background, storage + activeTab):

Terminal window
pnpm dlx extforge init my-extension --defaults

After the wizard completes, the project directory is ready. Install dependencies:

Terminal window
cd my-extension && pnpm install

See extforge init in the CLI reference for all flags.

Verifying the install

Check the version:

Terminal window
pnpm exec extforge --version

Run the environment check:

Terminal window
pnpm exec extforge doctor

extforge doctor reports:

  • Node.js version (✓ if 20+, ✗ if below)
  • Package manager detected
  • extforge.config.ts present and valid
  • icons/ directory present with required sizes
  • HMR port 9100 availability

See extforge doctor for the full list of checks.

Loading the extension

Chrome

  1. Open chrome://extensions.
  2. Enable Developer mode (toggle in the top-right).
  3. Click Load unpacked and select dist/chrome/ in your project directory.

The extension loads immediately. The dev server prints the full path to dist/chrome/ on startup.

Firefox

  1. Open about:debugging#/runtime/this-firefox.
  2. Click Load Temporary Add-on.
  3. Select dist/firefox/manifest.json (Firefox requires a file, not a directory).

Temporary add-ons are removed when Firefox restarts. For persistent loading, use a dedicated Firefox profile via extforge dev --browser firefox.

Edge

  1. Open edge://extensions.
  2. Enable Developer mode (left sidebar toggle).
  3. Click Load unpacked and select dist/edge/.

Edge uses the same Chromium extension loader as Chrome.

Safari

Safari requires converting your extension using Apple’s tool before it can be loaded.

  1. Build the extension: pnpm build.
  2. Run the converter: xcrun safari-web-extension-converter dist/chrome/ --project-location ./safari-ext --app-name MyExtension.
  3. Open the generated Xcode project and run the app target on your Mac.
  4. In Safari, go to Settings → Extensions and enable the extension.