React for browser extensions

Extension.js detects React from your project dependencies and configures JSX/TSX transforms, React module aliases, and fast-refresh support for development automatically.

When React is a good fit

You are building rich UI surfaces like popup, options, sidebar, or new tab.
You want component reuse across extension pages and content-script UI mounts.
You already use React in web projects and want the same development model in extensions.

Template examples

`new-react`

Build a React new-tab experience with a ready-to-run project structure.

npx extension@latest create my-extension --template=newtab-react

pnpx extension@latest create my-extension --template=newtab-react

yarn dlx extension@latest create my-extension --template=newtab-react

bunx extension@latest create my-extension --template=newtab-react

deno run -A npm:extension@latest create my-extension --template=newtab-react

Repository: extension-js/examples/newtab-react

`content-react`

Inject React UI into existing pages with a content-script-first setup.

npx extension@latest create my-extension --template=content-react

pnpx extension@latest create my-extension --template=content-react

yarn dlx extension@latest create my-extension --template=content-react

bunx extension@latest create my-extension --template=content-react

deno run -A npm:extension@latest create my-extension --template=content-react

Repository: extension-js/examples/content-react

`new-react-router`

React extension with client-side routing using React Router.

npx extension@latest create my-extension --template=newtab-react-router

pnpx extension@latest create my-extension --template=newtab-react-router

yarn dlx extension@latest create my-extension --template=newtab-react-router

bunx extension@latest create my-extension --template=newtab-react-router

deno run -A npm:extension@latest create my-extension --template=newtab-react-router

Repository: extension-js/examples/newtab-react-router

Usage with an existing extension

Add React to an existing extension with the steps below.

Installation

Install React runtime dependencies:

npm install react react-dom

pnpm add react react-dom

yarn add react react-dom

bun add react react-dom

deno add npm:react npm:react-dom

If you use TypeScript, also install React type packages:

npm install -D @types/react @types/react-dom

pnpm add -D @types/react @types/react-dom

yarn add -D @types/react @types/react-dom

bun add -d @types/react @types/react-dom

deno add -D npm:@types/react npm:@types/react-dom

The React integration also uses optional packages such as react-refresh and @rspack/plugin-react-refresh. Both ship as dependencies of extension-develop, so a healthy install already resolves them. When one cannot be resolved, the build fails to start and the error names the packages to install. The install command in the error is phrased for the package manager that your project uses.

Configuration

Common React file patterns:

JavaScript: *.jsx
TypeScript: *.tsx

Development behavior

In development mode, Extension.js enables React refresh integration when it detects React.

Extension.js uses react-refresh and @rspack/plugin-react-refresh for refresh behavior.
If the refresh packages cannot be resolved from your project or from extension-develop, the build fails to start and prints that install command. Extension.js does not install them for you and does not ask for a restart.
Extension.js applies React aliases to keep a single React/runtime instance in your bundle.

Usage examples

In a new tab extension

Example page entry:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>New Extension</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this extension.</noscript>
    <div id="root"></div>
  </body>
  <script src="./index.tsx"></script>
</html>

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

export default function App() {
  return <h1>Hello, Extension!</h1>;
}

In a `content_script` file

For content scripts, render React into an injected root element:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./content.css";

const rootDiv = document.createElement("div");
rootDiv.id = "extension-root";
document.body.appendChild(rootDiv);

const root = ReactDOM.createRoot(rootDiv);
root.render(<App />);

Next steps

Start from the React template (--template=react) when you want a sidebar panel plus a content script.
Learn more about TypeScript support.
Explore how Extension.js handles Sass modules.

Video walkthrough

⌘I

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

React for browser extensions

When React is a good fit

Template examples

`new-react`

`content-react`

`new-react-router`

Usage with an existing extension

Installation

Configuration

Development behavior

Usage examples

In a new tab extension

In a `content_script` file

Next steps

Video walkthrough

​When React is a good fit

​Template examples

​new-react

​content-react

​new-react-router

​Usage with an existing extension

​Installation

​Configuration

​Development behavior

​Usage examples

​In a new tab extension

​In a content_script file

​Next steps

​Video walkthrough

When React is a good fit

Template examples

`new-react`

`content-react`

`new-react-router`

Usage with an existing extension

Installation

Configuration

Development behavior

Usage examples

In a new tab extension

In a `content_script` file

Next steps

Video walkthrough