Content Scripts

Static Assets

Feel free to import static assets! CRXJS automatically declares imported content script dependencies as web_accessible_resources in the manifest.

Use the extension URL

Content scripts share the origin of the host page, so convert imported static assets to the extension origin using the Chrome API.

import logo from './logo.png'
const url = chrome.runtime.getURL(logo)

IIFE content scripts

CRXJS normally runs content scripts through an async loader. That loader enables Vite HMR and regular ESM imports, but it can be too late for document_start scripts that must patch host page APIs before page code runs.

Use an IIFE content script for timing-sensitive work like intercepting fetch, XMLHttpRequest, DOM events, or globals in the main world. CRXJS emits the script as a standalone bundle with its imports inlined, and Chrome runs that file directly.

Recommended architecture

Keep most of your extension logic in the default isolated world content script. It stays separated from page JavaScript, can use the extension APIs available to content scripts, and receives full Vite HMR in development.

Use a MAIN world IIFE only for the part that must run inside the host page environment. Treat it as a small bridge: install the early hook at document_start, then pass commands or data to the isolated content script with window.postMessage, CustomEvent, or DOM events. This keeps the non-HMR script small and stable.

Enable IIFE output

import { defineManifest } from '@crxjs/vite-plugin'

export default defineManifest({
  manifest_version: 3,
  name: 'My Extension',
  version: '1.0.0',
  content_scripts: [{
    js: ['src/content/interceptor.iife.ts'],
    matches: ['https://example.com/*'],
    run_at: 'document_start',
    world: 'MAIN',
  }],
})

import { crx } from '@crxjs/vite-plugin'
import { defineConfig } from 'vite'
import manifest from './manifest.config'

export default defineConfig({
  plugins: [
    crx({
      manifest,
      contentScripts: {
        standaloneFiles: ['src/content/interceptor.ts'],
      },
    }),
  ],
})

import interceptor from './content/interceptor.ts?iife'
// import interceptor from './content/interceptor.iife.ts?script'

chrome.scripting.registerContentScripts([{
  id: 'network-interceptor',
  js: [interceptor],
  matches: ['https://example.com/*'],
  runAt: 'document_start',
  world: 'MAIN',
}])

HTML in content scripts

It is possible to inject an extension page into a host page using an iframe. The host page CSP does not affect the injected iframe even if the host page specifies the frame-src policy.

An injected extension page loads inside a cross-origin iframe, so it does not have access to the host page DOM like a content script.

const src = chrome.runtime.getURL('pages/iframe.html')

const iframe = new DOMParser().parseFromString(
  `<iframe class="crx" src="${src}"></iframe>`,
).body.firstElementChild

document.body.append(iframe)

Injected extension pages do have access to the full Chrome API, however.

import { defineManifest } from '@crxjs/vite-plugin'
import pkg from './package.json'

export default defineManifest({
  manifest_version: 3,
  name: pkg.name,
  version: pkg.version,
  action: {
    default_popup: 'src/popup/index.html',
  },
  content_scripts: [{
    js: ['src/content/main.ts'],
    matches: ['https://*/*'],
  }],
  web_accessible_resources: [{
      resources: ["pages/iframe.html"],
      matches: ["https://*.google.com/*"]
  }]
})

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        welcome: 'pages/iframe.html',
      },
    },
  },
})

Imported HTML

If you need to render complex HTML in a content script without a framework, an HTML file can serve as a static fragment by importing it as text using the ?raw query. This technique does not require the file to be web-accessible, and you don't need to declare it in the Vite config.

import html from './root.html?raw'

const iframe = new DOMParser().parseFromString(html).body.firstElementChild
iframe.src = chrome.runtime.getURL('pages/iframe.html')

document.body.append(iframe)

Importing an HTML file as text lets you take advantage of IDE language services for HTML files. Depending on your HTML, this technique may be more concise than using document.createElement().