Using React to Build a Chrome Extension

React can make Chrome extensions easier to build and maintain, especially when an extension has an interactive popup, options page, or side panel. Its component-based approach helps organize the interface into reusable pieces, while tools such as Vite can streamline development and packaging.

A Chrome extension is not simply a website inside the browser. It can include several parts that run in different contexts, each with its own capabilities and security rules. Understanding those parts is the first step to using React effectively.

Where React Fits in a Chrome Extension

React is most commonly used for extension interfaces:

• Popup: The small window that opens when someone clicks the extension’s toolbar icon.
• Options page: A page for configuring the extension’s settings.
• Side panel: A larger, persistent interface displayed alongside a webpage.
• New tab page: A custom page that replaces Chrome’s default new tab experience.

Extensions can also use content scripts to interact with web pages and service workers to handle events in the background. These parts do not automatically share the same environment as a React interface. They communicate through Chrome’s extension APIs and messaging system.

How a Chrome Extension Is Structured

Most modern Chrome extensions use Manifest V3. The manifest is a JSON file that describes the extension, its entry points, permissions, and other settings. A basic project might contain files like these:

my-extension/


├── manifest.json


├── popup.html


├── src/


│   ├── popup.jsx


│   ├── options.jsx


│   └── content.js


└── dist/

The source files are typically bundled into a production-ready folder, such as dist. That folder—not necessarily the original source folder—is what you load into Chrome.

Creating a React Popup

A React popup starts with an HTML file that provides a mount point. A bundler such as Vite can build the React code and include the necessary JavaScript and CSS.

For example, the popup HTML could contain:

<div id="root"></div>


<script type="module" src="/src/popup.jsx"></script>

The React entry point renders the interface into that element:

import React from "react";


import { createRoot } from "react-dom/client";





function Popup() {


  return (


    <main>


      <h1>Page Helper</h1>


      <p>Your extension is ready.</p>


    </main>


  );


}





createRoot(document.getElementById("root")).render(<Popup />);

The popup is a regular extension page, so React can manage its interface just as it would on a standard web page. However, it closes when the user clicks outside it, so long-running tasks should not depend on the popup remaining open.

Defining the Manifest

A minimal Manifest V3 configuration for a popup might look like this:

{


  "manifest_version": 3,


  "name": "Page Helper",


  "version": "1.0.0",


  "action": {


    "default_popup": "popup.html"


  }


}

Additional features may require permissions or other manifest entries. For example, an extension that reads the current tab’s URL may need the activeTab permission. A content script that runs on selected websites must be declared with appropriate match patterns. Request only the permissions the extension actually needs, and explain their purpose to users.

Using Content Scripts and Background Logic

A React popup and a content script run in separate contexts. The popup cannot directly access a web page’s DOM, and a content script does not automatically share React’s state. To pass information between them, use Chrome’s messaging APIs.

A content script can be declared in the manifest:

{


  "manifest_version": 3,


  "name": "Page Helper",


  "version": "1.0.0",


  "permissions": ["activeTab"],


  "content_scripts": [


    {


      "matches": ["https://example.com/*"],


      "js": ["content.js"]


    }


  ]


}

For broader event handling, Manifest V3 extensions use a service worker specified with background.service_worker. A service worker is not a persistent webpage: Chrome may stop it when it is idle and start it again when an event occurs. Store important state using extension storage or another suitable persistence mechanism instead of relying on ordinary in-memory variables.

Choosing a Build Tool

React source code usually needs to be bundled before Chrome can load it as an extension. Vite is a popular choice because it offers a fast development server and a production build process. Extension-focused tools and plugins can also help generate multiple entry points, manage the manifest, and package popup, options, content script, and service worker files.

Whichever tool you choose, check that the final output follows Chrome extension requirements. In particular, production extension code should not depend on loading executable JavaScript from an external server. Bundle the code with the extension and test the generated files, not just the development version.

Testing the Extension in Chrome

1. Build the project so it produces the extension’s output folder.
2. Open chrome://extensions in Chrome.
3. Turn on Developer mode.
4. Select Load unpacked and choose the output folder.
5. Test the popup, settings, content scripts, and background behavior.

When you change extension files, use the reload button on the extension’s card in Chrome. You may also need to refresh the web page to run updated content scripts. Check the extension’s errors panel and the relevant developer console when something does not work.

Common Challenges

• Mixing contexts: Popup pages, content scripts, and service workers have different access and lifecycle rules. Keep their responsibilities separate.
• Over-requesting permissions: Broad permissions can reduce user trust and may create review or security concerns. Use the narrowest permissions that support the feature.
• Assuming background code stays active: Manifest V3 service workers can stop when idle. Design background tasks around events and persistent storage.
• Including development-only code: Check the production build for development servers, external scripts, and other assets that should not ship.
• Ignoring small screens: Popups have limited space. Keep the interface focused and make important actions easy to find.

Best Practices

Build the extension with clear boundaries between the React interface, content scripts, and background service worker. Use React for the parts that benefit from a rich, stateful interface, and use Chrome APIs for browser-specific features. Keep permissions minimal, validate messages passed between contexts, and provide useful feedback when an action succeeds or fails.

It is also helpful to test the extension on the pages and browser configurations it is intended to support. Pay attention to accessibility, keyboard navigation, loading states, and error handling—not just whether the interface looks correct.

Conclusion

React is a strong choice for building polished interfaces in Chrome extensions, from compact popups to full options pages and side panels. The key is to pair React with a suitable build process and understand how extension components operate in separate browser contexts. With a well-structured project, careful permission choices, and thorough testing in Chrome, React can support extensions that are maintainable, responsive, and easy to use.