Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Content Scripts

To create a content script, seeEntrypoint Types.

Context

The first argument to a content script'smain function is its "context".

ts
// entrypoints/example.content.tsexport default defineContentScript({  main(ctx) {},});

This object is responsible for tracking whether or not the content script's context is "invalidated". Most browsers, by default, do not stop content scripts if the extension is uninstalled, updated, or disabled. When this happens, content scripts start reporting this error:

plaintext
Error: Extension context invalidated.

Thectx object provides several helpers to stop asynchronous code from running once the context is invalidated:

ts
ctx.addEventListener(...);ctx.setTimeout(...);ctx.setInterval(...);ctx.requestAnimationFrame(...);// and more

You can also check if the context is invalidated manually:

ts
if (ctx.isValid) {  // do something}// ORif (ctx.isInvalid) {  // do something}

CSS

In regular web extensions, CSS for content scripts is usually a separate CSS file, that is added to a CSS array in the manifest:

json
{  "content_scripts": [    {      "css": ["content/style.css"],      "js": ["content/index.js"],      "matches": ["*://*/*"]    }  ]}

In WXT, to add CSS to a content script, simply import the CSS file into your JS entrypoint, and WXT will automatically add the bundled CSS output to thecss array.

ts
// entrypoints/example.content/index.tsimport './style.css';export default defineContentScript({  // ...});

To create a standalone content script that only includes a CSS file:

  1. Create the CSS file:entrypoints/example.content.css

  2. Use thebuild:manifestGenerated hook to add the content script to the manifest:

    wxt.config.ts
    ts
    export default defineConfig({  hooks: {    'build:manifestGenerated': (wxt,manifest)=> {      manifest.content_scripts??= [];      manifest.content_scripts.push({        // Build extension once to see where your CSS get's written to        css: ['content-scripts/example.css'],        matches: ['*://*/*'],      });    },  },});

UI

WXT provides 3 built-in utilities for adding UIs to a page from a content script:

Each has their own set of advantages and disadvantages.

MethodIsolated StylesIsolated EventsHMRUse page's context
Integrated
Shadow Root✅ (off by default)
IFrame

Integrated

Integrated content script UIs are injected alongside the content of a page. This means that they are affected by CSS on that page.

ts
// entrypoints/example-ui.content.tsexport default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      anchor:'body',      onMount: (container)=> {        // Append children to the container        const app = document.createElement('p');        app.textContent= '...';        container.append(app);      },    });    // Call mount to add the UI to the DOM    ui.mount();  },});
ts
// entrypoints/example-ui.content/index.tsimport { createApp }from 'vue';import Appfrom './App.vue';export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      anchor:'body',      onMount: (container)=> {        // Create the app and mount it to the UI container        const app = createApp(App);        app.mount(container);        return app;      },      onRemove: (app)=> {        // Unmount the app when the UI is removed        app.unmount();      },    });    // Call mount to add the UI to the DOM    ui.mount();  },});
tsx
// entrypoints/example-ui.content/index.tsximport ReactDOMfrom 'react-dom/client';import Appfrom './App.tsx';export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      anchor:'body',      onMount: (container)=> {        // Create a root on the UI container and render a component        const root = ReactDOM.createRoot(container);        root.render(<App />);        return root;      },      onRemove: (root)=> {        // Unmount the root when the UI is removed        root.unmount();      },    });    // Call mount to add the UI to the DOM    ui.mount();  },});
ts
// entrypoints/example-ui.content/index.tsimport Appfrom './App.svelte';import { mount, unmount }from 'svelte';export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      anchor:'body',      onMount: (container)=> {        // Create the Svelte app inside the UI container        return mount(App, { target: container });      },      onRemove: (app)=> {        // Destroy the app when the UI is removed        unmount(app);      },    });    // Call mount to add the UI to the DOM    ui.mount();  },});
tsx
// entrypoints/example-ui.content/index.tsimport { render }from 'solid-js/web';export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      anchor:'body',      onMount: (container)=> {        // Render your app to the UI container        const unmount = render(()=> <div>...</div>, container);        return unmount;      },      onRemove: (unmount)=> {        // Unmount the app when the UI is removed        unmount();      },    });    // Call mount to add the UI to the DOM    ui.mount();  },});

See theAPI Reference for the complete list of options.

Shadow Root

Often in web extensions, you don't want your content script's CSS affecting the page, or vise-versa. TheShadowRoot API is ideal for this.

WXT'screateShadowRootUi abstracts all theShadowRoot setup away, making it easy to create UIs whose styles are isolated from the page. It also supports an optionalisolateEvents parameter to further isolate user interactions.

To usecreateShadowRootUi, follow these steps:

  1. Import your CSS file at the top of your content script
  2. SetcssInjectionMode: "ui" insidedefineContentScript
  3. Define your UI withcreateShadowRootUi()
  4. Mount the UI so it is visible to users
ts
// 1. Import the styleimport './style.css';export default defineContentScript({  matches: ['<all_urls>'],  // 2. Set cssInjectionMode  cssInjectionMode:'ui',  async main(ctx) {    // 3. Define your UI    const ui = await createShadowRootUi(ctx, {      name:'example-ui',      position:'inline',      anchor:'body',      onMount(container) {        // Define how your UI will be mounted inside the container        const app = document.createElement('p');        app.textContent= 'Hello world!';        container.append(app);      },    });    // 4. Mount the UI    ui.mount();  },});
ts
// 1. Import the styleimport './style.css';import { createApp }from 'vue';import Appfrom './App.vue';export default defineContentScript({  matches: ['<all_urls>'],  // 2. Set cssInjectionMode  cssInjectionMode:'ui',  async main(ctx) {    // 3. Define your UI    const ui = await createShadowRootUi(ctx, {      name:'example-ui',      position:'inline',      anchor:'body',      onMount: (container)=> {        // Define how your UI will be mounted inside the container        const app = createApp(App);        app.mount(container);        return app;      },      onRemove: (app)=> {        // Unmount the app when the UI is removed        app?.unmount();      },    });    // 4. Mount the UI    ui.mount();  },});
tsx
// 1. Import the styleimport './style.css';import ReactDOMfrom 'react-dom/client';import Appfrom './App.tsx';export default defineContentScript({  matches: ['<all_urls>'],  // 2. Set cssInjectionMode  cssInjectionMode:'ui',  async main(ctx) {    // 3. Define your UI    const ui = await createShadowRootUi(ctx, {      name:'example-ui',      position:'inline',      anchor:'body',      onMount: (container)=> {        // Container is a body, and React warns when creating a root on the body, so create a wrapper div        const app = document.createElement('div');        container.append(app);        // Create a root on the UI container and render a component        const root = ReactDOM.createRoot(app);        root.render(<App />);        return root;      },      onRemove: (root)=> {        // Unmount the root when the UI is removed        root?.unmount();      },    });    // 4. Mount the UI    ui.mount();  },});
ts
// 1. Import the styleimport './style.css';import Appfrom './App.svelte';import { mount, unmount }from 'svelte';export default defineContentScript({  matches: ['<all_urls>'],  // 2. Set cssInjectionMode  cssInjectionMode:'ui',  async main(ctx) {    // 3. Define your UI    const ui = await createShadowRootUi(ctx, {      name:'example-ui',      position:'inline',      anchor:'body',      onMount: (container)=> {        // Create the Svelte app inside the UI container        return mount(App, { target: container });      },      onRemove: (app)=> {        // Destroy the app when the UI is removed        unmount(app);      },    });    // 4. Mount the UI    ui.mount();  },});
tsx
// 1. Import the styleimport './style.css';import { render }from 'solid-js/web';export default defineContentScript({  matches: ['<all_urls>'],  // 2. Set cssInjectionMode  cssInjectionMode:'ui',  async main(ctx) {    // 3. Define your UI    const ui = await createShadowRootUi(ctx, {      name:'example-ui',      position:'inline',      anchor:'body',      onMount: (container)=> {        // Render your app to the UI container        const unmount = render(()=> <div>...</div>, container);      },      onRemove: (unmount)=> {        // Unmount the app when the UI is removed        unmount?.();      },    });    // 4. Mount the UI    ui.mount();  },});

See theAPI Reference for the complete list of options.

Full examples:

IFrame

If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page,HMR is supported.

WXT provides a helper function,createIframeUi, which simplifies setting up the IFrame.

  1. Create an HTML page that will be loaded into your IFrame:

    html
    <!-- entrypoints/example-iframe.html --><!doctype html><html lang="en">  <head>    <meta charset="UTF-8" />    <meta name="viewport" content="width=device-width, initial-scale=1.0" />    <title>Your Content Script IFrame</title>  </head>  <body>    <!-- ... -->  </body></html>
  2. Add the page to the manifest'sweb_accessible_resources:

    wxt.config.ts
    ts
    export default defineConfig({  manifest: {    web_accessible_resources: [      {        resources: ['example-iframe.html'],        matches: [...],      },    ],  },});
  3. Create and mount the IFrame:

    ts
    export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    // Define the UI    const ui = createIframeUi(ctx, {      page:'/example-iframe.html',      position:'inline',      anchor:'body',      onMount: (wrapper,iframe)=> {        // Add styles to the iframe like width        iframe.width= '123';      },    });    // Show UI to user    ui.mount();  },});

See theAPI Reference for the complete list of options.

Isolated World vs Main World

By default, all content scripts run in an isolated context where only the DOM is shared with the webpage it is running on - an "isolated world". In MV3, Chromium introduced the ability to run content scripts in the "main" world - where everything, not just the DOM, is available to the content script, just like if the script were loaded by the webpage.

You can enable this for a content script by setting theworld option:

ts
export default defineContentScript({  world:'MAIN',});

However, this approach has several notable drawbacks:

  • Doesn't support MV2
  • world: "MAIN" is only supported by Chromium browsers
  • Main world content scripts don't have access to the extension API

Instead, WXT recommends injecting a script into the main world manually using it'sinjectScript function. This will address the drawbacks mentioned before.

  • injectScript supports both MV2 and MV3
  • injectScript supports all browsers
  • Having a "parent" content script means you can send messages back and forth, making it possible to access the extension API

To useinjectScript, we need two entrypoints, one content script and one unlisted script:

html
📂 entrypoints/   📄 example.content.ts   📄 example-main-world.ts
ts
// entrypoints/example-main-world.tsexport default defineUnlistedScript(()=> {  console.log('Hello from the main world');});
ts
// entrypoints/example.content.tsexport default defineContentScript({  matches: ['*://*/*'],  async main() {    console.log('Injecting script...');    await injectScript('/example-main-world.js', {      keepInDom:true,    });    console.log('Done!');  },});
json
export default defineConfig({  manifest: {    // ...    web_accessible_resources: [      {        resources: ["example-main-world.js"],        matches: ["*://*/*"],      }    ]  }});

injectScript works by creating ascript element on the page pointing to your script. This loads the script into the page's context so it runs in the main world.

injectScript returns a promise, that when resolved, means the script has been evaluated by the browser and you can start communicating with it.

Warning:run_at Caveat

For MV3,injectScript is synchronous and the injected script will be evaluated at the same time as your the content script'srun_at.

However for MV2,injectScript has tofetch the script's text content and create an inline<script> block. This means for MV2, your script is injected asynchronously and it will not be evaluated at the same time as your content script'srun_at.

Mounting UI to dynamic element

In many cases, you may need to mount a UI to a DOM element that does not exist at the time the web page is initially loaded. To handle this, use theautoMount API to automatically mount the UI when the target element appears dynamically and unmount it when the element disappears. In WXT, theanchor option is used to target the element, enabling automatic mounting and unmounting based on its appearance and removal.

ts
export default defineContentScript({  matches: ['<all_urls>'],  main(ctx) {    const ui = createIntegratedUi(ctx, {      position:'inline',      // It observes the anchor      anchor:'#your-target-dynamic-element',      onMount: (container)=> {        // Append children to the container        const app = document.createElement('p');        app.textContent= '...';        container.append(app);      },    });    // Call autoMount to observe anchor element for add/remove.    ui.autoMount();  },});

TIP

When theui.remove is called,autoMount also stops.

See theAPI Reference for the complete list of options.

Dealing with SPAs

It is difficult to write content scripts for SPAs (single page applications) and websites using HTML5 history mode for navigation because content scripts are only ran on full page reloads. SPAs and websites that take advantage of HTML5 history modedo not perform a full reload when changing paths, and thus your content script isn't going to be ran when you expect it to be.

Let's look at an example. Say you want to add a UI to YouTube when watching a video:

ts
export default defineContentScript({  matches: ['*://*.youtube.com/watch*'],  main(ctx) {    console.log('YouTube content script loaded');    mountUi(ctx);  },});function mountUi(ctx: ContentScriptContext): void {  // ...}

You're only going to see "YouTube content script loaded" when reloading the watch page or when navigating directly to it from another website.

To get around this, you'll need to manually listen for the path to change and run your content script when the URL matches what you expect it to match.

ts
const watchPattern = new MatchPattern('*://*.youtube.com/watch*');export default defineContentScript({  matches: ['*://*.youtube.com/*'],  main(ctx) {    ctx.addEventListener(window,'wxt:locationchange', ({newUrl })=> {      if (watchPattern.includes(newUrl))mainWatch(ctx);    });  },});function mainWatch(ctx: ContentScriptContext) {  mountUi(ctx);}

[8]ページ先頭

©2009-2025 Movatter.jp