How to Use Transformers.js in a Chrome Extension

How to Use Transformers.js in a Chrome Extension 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 fromsrc/background/background.ts .side_panel.default_path = sidebar.html , built fromsrc/sidebar/index.html .content_scripts[].js = content.js withmatches: http(s)://*/* andrun_at: document_idle , built fromsrc/content/content.ts . The background service worker also handles chrome.action.onClicked to open the side panel for the active tab. Related entry point to know: a popup can be defined with action.default_popup and works well for quick actions. This project uses a side panel for persistent chat, but the orchestration pattern is the same. 1.2 What runs where The key design decision is to keep heavy orchestration in the background and keep UI/page logic thin. - Background ( src/background/background.ts ) is the control plane: agent lifecycle, model initialization, tool execution, and shared services like feature extraction. - Side panel ( src/sidebar/* ) is the interaction layer: chat input/output, streaming updates, and setup controls. - Content script ( src/content/content.ts ) is the page bridge: DOM extraction and highlight actions. One practical consequence of this division is that the conversation history also lives in background (Agent.chatMessages ): the UI sends events like AGENT_GENERATE_TEXT , background appends the message, runs inference, then emits MESSAGES_UPDATE back to the side panel. This split avoids duplicate model loads, keeps the UI responsive, and respects Chrome's security boundaries around DOM access. 1.3 Messaging contract Once runtimes are separated, messaging becomes the backbone. In this project, all messages are typed through enums in src/shared/types.ts . - Side panel -> background ( BackgroundTasks ):CHECK_MODELS ,INITIALIZE_MODELS AGENT_INITIALIZE ,AGENT_GENERATE_TEXT ,AGENT_GET_MESSAGES ,AGENT_CLEAR EXTRACT_FEATURES - Background -> side panel ( BackgroundMessages ):DOWNLOAD_PROGRESS ,MESSAGES_UPDATE - Background -> content ( ContentTasks ):EXTRACT_PAGE_DATA ,HIGHLIGHT_ELEMENTS ,CLEAR_HIGHLIGHTS The orchestration rule is simple: the background is…