Strategies for injecting code with registerContentScripts and CRXJS

[jonlong]

Hello, and thank you so much for this amazing project! It's really been indispensable, and the further I get with extension development, the more appreciation I gain for your efforts here 🙏🙏

I have a use case that I initially thought would be kinda common in MV3, but I haven't found a solid way to make it work yet and was hoping to get some ideas or guidance from more experienced folks.

What I'm trying to do

Broadly, I want to have users grant permission for content scripts to register themselves against a matching domain, instead of me having to list/update a set of domains in my manifest.json.

So the goals are:

• Avoid a permissions prompt on installation
• After installation, prompt a user for permission (via my popup UI) to inject a content script on a given domain (via Chrome's registerContentScripts method)
• When permission is granted, register a main world content script that loads the same as it would if it was specified in a content_scripts config (automatically, on page load)

So far I've got everything working except successful execution of the script passed to registerContentScripts in CRXJS's dev mode.

Reproducing the issue

Here's a repo that illustrates the issue: https://github.com/jonlong/crx-registercontentscripts.

• After building/running the extension, navigate to a YouTube video page
• Open the popup and hit the "Grant Permission" button
• Inspect the YouTube page
  • You should see two log statements indicating that the content script was imported successfully and the content was injected
  • What I see instead is an error stating Cannot use import statement outside a module, which looks like it's coming from the import in my content/inject.ts file

Why do this?

Really I just want to have a chance to explain to users what the permissions prompt their about to see means, and what we're planning to do (and not do) with their data. I could do this in the extension's description in the Chrome Web Store, but I doubt it would have the same read rate as something that is right next to the action itself.

If I avoid listing any matching urls in my manifest.json, and instead specify "optional_host_permissions": ["*://*/*"], then ideally I'd be able to avoid permissions prompts altogether. Users could control the entire permissions flow themselves from my popup UI, and I could control how I present those options to them.

Where I'm looking for help

I guess the content script import error is the most obvious place to start.

• It seems like passing a module to registerContentScripts won't work, right?
• Is there a different pattern I can use with CRXJS that I'm not considering? Something that would retain content script HMR in dev mode?

If there's not a CRXJS solution to this, how would you approach it?

• would you build content/inject.ts separately somehow, and pass registerContentScripts a path to the built file?
• would you avoid registerContentScripts altogether and do something else?
• would you use something like webext-dynamic-content-scripts (which looks like it needs at least one match in manifest.json)?
• would you never do this and just manually track domains in manifest.json?

I'd appreciate any thoughts or direction anyone's willing to share! Thanks!

[jacksteamdev]

This looks like an ideal way to register optional content scripts. 👍

Is there a different pattern I can use with CRXJS that I'm not considering? Something that would retain content script HMR in dev mode?

I'd suggest removing the module param from the query string:

-- import contentScriptUrl from "../content/inject?script&module";
++ import contentScriptUrl from "../content/inject?script";

Content scripts use a wrapper script to import the actual script module and to support HMR in dev mode. The module param removes the wrapper, which is useful in some scenarios, but doesn't work for a registered content script.

[jonlong]

Hrm, this ends up throwing an error for me as well:

TypeError: Cannot read properties of undefined (reading 'getURL')

Which refers to the missing chrome.runtime API in the generated inject.ts-loader.js file that gets passed to registerContentScripts:

(function () {
  'use strict';

  (async () => {
    if ("vendor/crx-client-preamble.js")
      await import(
        /* @vite-ignore */
        chrome.runtime.getURL("vendor/crx-client-preamble.js")
      );
    await import(
      /* @vite-ignore */
      chrome.runtime.getURL("vendor/vite-client.js")
    );
    await import(
      /* @vite-ignore */
      chrome.runtime.getURL("src/content/inject.ts.js")
    );
  })().catch(console.error);

})();

Looking at your example in the e2e tests (thanks for that link btw, I should have checked those out!) I'm wondering if runtime is available when calling chrome.scripting.executeScript, but not in whatever context chrome.scripting.registerContentScripts uses? 🤷

[jonlong]

Apologies that it's taken me so long to wrap my head around this! 🤦

The errors I was seeing were a product of specifying world: "MAIN" in both executeScript and registerContentScripts — but I think I understand what you're doing now. It looks like the idea here is that you'd run the content script in the isolated world instead, where it appends a new <script> to the DOM that executes in the main world. Is that right?

When I do this, I'm able to bypass my runtime errors (makes sense, the runtime API is available in the isolated world), and see the script load (nice), but I get a new set of HMR errors this time around:

[vite] failed to connect to websocket (TypeError: Cannot read properties of undefined (reading 'connect')). 

Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.

I noticed a few examples in the e2e tests passed preambleCode from Vite's React plugin to the CRX's contentScripts option, but that didn't seem to change things for me.

Any advice on what to look into next? Apologies if I'm missing something obvious — trying to navigate this part of MV3 has been monumentally confusing 😅

[AntonOfTheWoods]

I'm also very interested to see whether there are any solutions to this. I only have executeScript and when I put world: "MAIN" I still don't get a chrome.runtime, whether I am compiling in dev mode or prod mode.

[AntonOfTheWoods]

I did a lot more testing and it seems there is simply no way to get into MAIN before the main page has properly loaded. After it has loaded then it works fine.

I tried all sorts of things here: https://github.com/AntonOfTheWoods/badcrx/tree/main , and everything seems to result in the same getURL errors. The repo is with the beta and vite4 but I have also tested with 1.0.14 and vite2 and see exactly the same issue.

It happens whether for dev or prod. Is there no way to make this work?

[jacksteamdev]

I only have executeScript and when I put world: "MAIN" I still don't get a chrome.runtime, whether I am compiling in dev mode or prod mode.

This is expected, world: "MAIN" runs in the same environment as a normal host page, with no special Chrome Extension APIs.

Something like below works, but only if main-world.ts doesn't use the import or export keywords:

import mainWorld from "./main-world?script&module";

chrome.scripting
  .registerContentScripts([
    {
      id: "session-script",
      js: [mainWorld],
      persistAcrossSessions: false,
      matches: ["*://www.google.com/*"],
      runAt: "document_start",
      world: "MAIN", // this fails
    },
  ])
  .then(() => console.log("registration complete"))
  .catch((err) => console.warn("unexpected error", err));

Vite outputs ES modules, and content scripts run as scripts. CRXJS uses dynamic imports to get content scripts working, but this won't work in a registered world: "MAIN" script, since you can't use chrome.runtime.getURL to get the module URL.

What we need is to build the script as an IIFE, and Vite doesn't do this, except in library mode.

This is a tricky feature to build into CRXJS, b/c it would need to run a recursive instance of Vite inside CRXJS to build the IIFE file, and signal CRXJS to reload when there's a new sub-build.

[jacksteamdev]

My suggestion for this use case is to use two build processes:

1. Build the main world script (main-world.ts -> main-world.iife.js) in a separate process using vite build --watch in library mode without CRXJS.
2. In the main build process, include the output IIFE script file (main-world.iife.js) in web_accessible_resources in the manifest.
3. In background.ts, register the content script as main-world.iife.js (don't import the script):

chrome.scripting
  .registerContentScripts([
    {
      id: "session-script",
      js: ["main-world.iife.js"],
      persistAcrossSessions: false,
      matches: ["*://www.google.com/*"],
      runAt: "document_start",
      world: "MAIN", // this fails
    },
  ])
  .then(() => console.log("registration complete"))
  .catch((err) => console.warn("unexpected error", err));

CRXJS will copy the IIFE script file as-is, and you can develop the Chrome Extension using CRXJS with HMR, etc.

[AntonOfTheWoods]

Actually found a non-HMR hack for this which satisfies my needs, for the moment anyway. Because the paths of the final scripts are well known (just add a .js to the .ts) and we can make sure they are generated by referring to the paths (with a log or whatever), then I just refer to path that will be generated and the script gets loaded directly without the need for a non-MAIN getURL at runtime.

It's brittle but it's definitely better than embarking on one of the other paths for something that can't work for me anyway. I need to run something before the host page loads so HMR is pointless here.

[remmel]

@jacksteamdev can you share you vite.iife.config.js ?

When using multiple entry point, iife is not handled by vite (Multiple entry points are not supported when output formats include "umd" or "iife".), so I though about wrapping myself in iife in a custom plugin its es outputs, but if an external function is used multiple time, it won't create a single file per entry, and thus use import (rollup/rollup#2756 (comment))

[edit: replace with gist to avoid pollute that thread]
https://gist.github.com/remmel/4b8217c5a845f78a578dc91141f74350

[remmel]

A working alternative (build: ok, dev: in world main file no HMR and file not updated in dist folder) is to use webpack to generate iife. However at dev, vite/crxjs does not detect the file update and the iife file is not copied/updated into the dist directory. Do you know where I should dig, to be able to have vite copying changes?

My files conf:
https://gist.github.com/remmel/ff381e4bd6c4ac8ce8355dcd7cf81ba9

[remmel]

An improve working alternative using webpack (build: ok, dev: in work main files no HMR or need to edit background.js) is to have webpack directly write in the dist crxjs folder the iife files. So vite does not need to copy it

[salmin89]

It's been a year and I'm wondering if there is a solution for HMR support for injected mainworld js-files - that doesn't require me to run a seperate --watch task?

If someone can think of a better solution please share with the rest of us :)

[salmin89]

I did some research and figured a few things out. Let me summarize this to anyone finding this issue:

• You can NOT define contentScripts to run in the MAIN world of a page.
• You CAN use registerContentScripts to inject in the MAIN world with the permission "scripting".
• registerContentScript doesn't allow you to define a script as a module. This limits you to use import in your injected script.
• for HMR to work we need to reference the script somewhere. This is solved by appending ?script to the import, which also outputs the script path. Further reading: Manifest resources and dynamic scripts #272
• we can use a contentScript to inject in the main world by using createElement('script') and append it to the head of the page.

You can follow solution 1/2 to have a setup that enables HMR and main world injecting without any hacks or extra stuff needed.

---

Solution 1 - define loader in manifest:

// manifest.json
content_scripts: [
  {
    matches: ['<all_urls>'],
    js: ['src/main-world-loader.ts'],
  }
],

Solution 2 - we use a registerContentScripts in the background

//background.ts

//@ts-ignore
import mainWorldLoader from 'main-world-loader?script'; // append ?script which bundles the imported script as a content script and returns the output script path.

chrome.scripting.registerContentScripts([
{
  id: 'script-id',
  js: [mainWorldLoader],
  persistAcrossSessions: false,
  matches: ['...'], // I personally set this conditionally. If you use <all_urls> you might as well use solution 1.
  world: 'ISOLATED' as const, // inject into ISOLATED world because the loader will inject the module in the main world.
}
])

---

Followed by:

// main-world-loader.ts
// @ts-ignore
import mainWorldScript from './mainWorld?script&module'; // By appending ?module to the import, you're explicitly specifying that you want to import the script as a module script.

const script = document.createElement('script');
script.src = chrome.runtime.getURL(mainWorldScript);
script.type = 'module'; // important if you are using imports in your module.
document.head.prepend(script);

// mainWorldScript.ts

// this is now a module so you can import libraries, access import.meta vars etc.

Hope this helps

[remmel]

Thanks, for sharing your solution, however, that solution does not work for me, as the injected world main script is not injected early enough (I'm intercepting xhr request) - same as https://dev.to/jacksteamdev/advanced-config-for-rpce-3966#main-world-scripts

[salmin89]

I'm also intercepting xhr and this works for me. Do you runAt contentStart? Might need to see an example