Preact for browser extensions

Ship smaller extension UI bundles while keeping a React-like developer experience and fast local iteration. Extension.js detects Preact from your dependencies. It configures JSX/TSX transforms and React compatibility aliases automatically. Your React imports map to Preact through these aliases. In development, edits apply through live reload: the changed surface reloads rather than hot-swapping components in place.

When Preact is a good fit

You want smaller UI bundle size for popup/sidebar/new tab surfaces.
You like React-style components but want a lighter runtime.
You are optimizing extension startup and UI responsiveness on lower-end devices.

Template examples

`new-preact`

Ship a lighter new-tab UI with Preact and React-compatible ergonomics.

npx extension@latest create my-extension --template=new-preact

pnpx extension@latest create my-extension --template=new-preact

yarn dlx extension@latest create my-extension --template=new-preact

bunx extension@latest create my-extension --template=new-preact

deno run -A npm:extension@latest create my-extension --template=new-preact

Repository: extension-js/examples/new-preact

`content-preact`

Inject a compact Preact UI into page content using content scripts.

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

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

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

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

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

Repository: extension-js/examples/content-preact

Usage with an existing extension

Add Preact to an existing extension with the steps below.

Installation

Install the required dependencies:

npm install preact

pnpm add preact

yarn add preact

bun add preact

deno add npm:preact

Preact ships its own TypeScript types, so you do not need a separate @types/preact package.

Configuration

Extension.js expects Preact files to use the following file extensions:

If you do not enable TypeScript: *.jsx
If you enable TypeScript: *.tsx

Development behavior

When Extension.js detects Preact, it configures:

Compatibility aliases (for example, react → preact/compat).
JSX handling tuned for Preact.
Live reload in development: when a file changes, the affected surface reloads and remounts.

Unlike React, Preact does not currently get fast refresh (state-preserving hot updates). The upstream @rspack/plugin-preact-refresh runtime is incompatible with the Rspack version Extension.js ships, so Extension.js disables it rather than break dev mode. Your app still updates on every edit, and component state is just not preserved across edits. Fast refresh returns once the upstream plugin is fixed.

Troubleshooting

Component state resets on edit: Expected for now, because Preact uses live reload, not fast refresh (see above).
No Preact integration detected: Confirm preact appears in dependencies or devDependencies.

Usage examples

In a new tab extension

To use Preact in a new tab extension, include it as a <script> in your HTML file:

<!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 { h, render } from "preact";
import App from "./App";

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

render(<App />, root);

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

In a `content_script` file

For content scripts, inject Preact into the page by creating an HTML element and rendering into it:

import { h, render } from "preact";
import App from "./App";
import "./content.css";

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

render(<App />, rootDiv);

Next steps

Learn more about TypeScript support.
Explore how Extension.js handles Sass modules.

Video walkthrough

React for browser extensions Vue.js for browser extensions

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Publish to the stores

Debugging

Implementation guide

Community

Preact for browser extensions

When Preact is a good fit

Template examples

`new-preact`

`content-preact`

Usage with an existing extension

Installation

Configuration

Development behavior

Troubleshooting

Usage examples

In a new tab extension

In a `content_script` file

Next steps

Video walkthrough

​When Preact is a good fit

​Template examples

​new-preact

​content-preact

​Usage with an existing extension

​Installation

​Configuration

​Development behavior

​Troubleshooting

​Usage examples

​In a new tab extension

​In a content_script file

​Next steps

​Video walkthrough

When Preact is a good fit

Template examples

`new-preact`

`content-preact`

Usage with an existing extension

Installation

Configuration

Development behavior

Troubleshooting

Usage examples

In a new tab extension

In a `content_script` file

Next steps

Video walkthrough