Environment:Mlc ai Web llm Chrome Extension Manifest V3
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Chrome_Extension, Browser |
| Last Updated | 2026-02-14 22:00 GMT |
Overview
Chrome Extension environment with Manifest V3, `wasm-unsafe-eval` Content Security Policy, and Service Worker background script for running WebLLM inference inside a Chrome extension.
Description
This environment defines the specific requirements for deploying WebLLM as a Chrome extension. It builds on the base WebGPU browser runtime but adds Chrome-specific constraints including Manifest V3 configuration, a Content Security Policy that permits WebAssembly execution (`wasm-unsafe-eval`), required Chrome API permissions (`storage`, `tabs`, `webNavigation`), and whitelisted remote hosts for fetching model weights from HuggingFace. The extension runs inference in a Service Worker background script with a keep-alive heartbeat to prevent idle shutdown.
Usage
Use this environment when deploying WebLLM as a Chrome Extension. This is the mandatory prerequisite for running the Service_Worker_MLC_Engine_Handler, Create_Service_Worker_MLC_Engine, Manifest_V3_Configuration, and Chrome_Tabs_Connect implementations.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Browser | Chrome or Chromium-based browser | Must support Manifest V3 extensions |
| Extension API | Chrome Extensions API with Service Worker support | `chrome.runtime`, `chrome.tabs`, `chrome.storage` |
| WebGPU | WebGPU available in Service Worker context | Required for in-extension inference |
| CSP | `wasm-unsafe-eval` directive allowed | Required for loading WASM model libraries |
| Network | Access to HuggingFace CDN endpoints | Model weights fetched at runtime |
Dependencies
Chrome Permissions
- `storage` — For caching extension state
- `tabs` — For accessing page content via content scripts
- `webNavigation` — For monitoring page navigation events
Content Security Policy
- `script-src 'self' 'wasm-unsafe-eval'` — Required for WASM execution
- `connect-src` must whitelist:
JavaScript Packages
- `@mlc-ai/web-llm` >= 0.2.80
- Bundled with webpack or rollup for extension packaging
Credentials
No API keys required. All model fetches use public HuggingFace endpoints.
Quick Install
{
"manifest_version": 3,
"content_security_policy": {
"extension_pages": "style-src-elem 'self' https://cdnjs.cloudflare.com; font-src 'self' https://cdnjs.cloudflare.com; script-src 'self' 'wasm-unsafe-eval'; default-src 'self' data:; connect-src 'self' data: https://huggingface.co https://cdn-lfs.huggingface.co https://cdn-lfs-us-1.huggingface.co https://raw.githubusercontent.com https://cdn-lfs-us-1.hf.co https://cas-bridge.xethub.hf.co"
},
"background": {
"service_worker": "background.ts",
"type": "module"
},
"permissions": ["storage", "tabs", "webNavigation"]
}
Code Evidence
Manifest V3 CSP configuration from `examples/chrome-extension-webgpu-service-worker/src/manifest.json:1-30`:
{
"manifest_version": 3,
"content_security_policy": {
"extension_pages": "style-src-elem 'self' https://cdnjs.cloudflare.com; font-src 'self' https://cdnjs.cloudflare.com; script-src 'self' 'wasm-unsafe-eval'; default-src 'self' data:; connect-src 'self' data: http://localhost:8000 https://huggingface.co https://cdn-lfs.huggingface.co https://cdn-lfs-us-1.huggingface.co https://raw.githubusercontent.com https://cdn-lfs-us-1.hf.co https://cas-bridge.xethub.hf.co"
},
"background": {
"service_worker": "background.ts",
"type": "module"
},
"permissions": ["storage", "tabs", "webNavigation"]
}
Service Worker API requirement from `src/service_worker.ts:222-224`:
if (!("serviceWorker" in navigator)) {
throw new NoServiceWorkerAPIError();
}
NonWorkerEnvironmentError from `src/error.ts:368-371`:
export class NonWorkerEnvironmentError extends Error {
constructor(className: string) {
super(`${className} must be created in the service worker script.`);
this.name = "NonWorkerEnvironmentError";
}
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Service worker API is not available in your browser` | Browser lacks Service Worker support or not HTTPS | Use Chrome with HTTPS; check `navigator.serviceWorker` availability |
| `{ClassName} must be created in the service worker script` | Engine handler instantiated outside service worker context | Move `ServiceWorkerMLCEngineHandler` creation to `background.ts` (the service worker script) |
| `Service worker failed to initialize` | Service worker registration failed | Refresh the page; check Chrome DevTools > Application > Service Workers for errors |
| CSP violation / WASM load failure | Missing `wasm-unsafe-eval` in manifest CSP | Add `'wasm-unsafe-eval'` to `script-src` in `content_security_policy` |
| Network error fetching model | HuggingFace domain not in `connect-src` | Add all required HuggingFace CDN domains to `connect-src` directive |
Compatibility Notes
- Manifest V3 only: Manifest V2 is deprecated; the WebGPU Service Worker pattern requires V3.
- Service Worker lifecycle: Chrome terminates idle service workers after ~30 seconds. WebLLM uses a keep-alive heartbeat (default 10s) to prevent this.
- WebGPU in Service Worker: Not all Chromium versions support WebGPU in service worker context. The non-service-worker extension example (`examples/chrome-extension/`) uses an offscreen document or Web Worker as fallback.
- Content script limitations: Content scripts cannot directly access WebGPU; they must communicate with the service worker via `chrome.runtime.connect()`.