Skip to main content
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

Template screenshot Ship a lighter new-tab UI with Preact and React-compatible ergonomics.
Repository: extension-js/templates/newtab-preact

content-preact

Template screenshot Inject a compact Preact UI into page content using content scripts.
Repository: extension-js/templates/content-preact

Usage with an existing extension

Add Preact to an existing extension with the steps below.

Installation

Install the required dependencies:
Preact ships its own TypeScript types, so you do not need a separate @types/preact package. From the release after 4.1.41, the Preact templates set "jsxImportSource": "preact" in tsconfig.json, so the editor and tsc check JSX against Preact’s own JSX types. A project created from an earlier template can add the same line to its compilerOptions. preact is the only package you add. Extension.js resolves preact/compat, preact/test-utils, and the JSX runtimes from your project and builds the alias map from whatever it finds, so there is no extra package to install. Preact 10 and Preact 11 both work. Builds, rendering, and hooks behave the same on either version. If you use @preact/signals with Preact 11, install @preact/signals 2.0.4 or later, because 1.x and 2.0.0 to 2.0.3 accept only Preact 10 as a peer.

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:

In a content_script file

For content scripts, render Preact inside a shadow root, and load the stylesheet into that root:
A plain import "./content.css" styles nothing in a content script. See CSS, Sass, and Less for every route.

Next steps

Video walkthrough

See the template run