How to Use Transformers.js in a Chrome Extension

We recently released a Transformers.js demo browser extension powered by Gemma 4 E2B to help users navigate the web.

While building it, we ran into several practical observations about Manifest V3 runtimes, model loading, and messaging that are worth sharing.

Who this is for

This guide is for developers who want to run local AI features in a Chrome extension with Transformers.js under Manifest V3 constraints.

By the end, you will have the same architecture used in this project: a background service worker that hosts models, a side panel chat UI, and a content script for page-level actions.

What we will build

In this guide, we will recreate the core architecture of Transformers.js Gemma 4 Browser Assistant, using the published extension as a reference and the open-source codebase as the implementation map.

Live extension: Chrome Web Store
Source code: github.com/nico-martin/gemma4-browser-extension
End result: a background-hosted Transformers.js engine, a side panel chat UI, and a content script for page extraction and highlighting.

1) Chrome extension architecture (MV3)

Before diving in, a quick scope note: I will not go deep on the React UI layer or Vite build configuration. The focus here is the high-level architecture decisions: what runs in each Chrome runtime and how those pieces are orchestrated.

If Manifest V3 is new to you, read this short overview first: What is Manifest V3?.

1.1 Runtime contexts and entry points

In MV3, your architecture starts in public/manifest.json. This project defines three entry points:

background.service_worker = background.js, built from src/background/background.ts.
side_panel.default_path = sidebar.html, built from src/sidebar/index.html.
content_scripts[].js = content.js with matches: http(s)://*/* and run_at: document_idle, built from src/content/content.ts.