Content Script ESM Support

[aklinker1]

Feature Request

As discussed in #335, it is possible to load ESM content scripts using a dynamic import. The downside is that since it's async, the standard run_at option has basically no effect.

I propose adding a new option to defineContentScript: type: "module". Similar to the background's type: "module" option.

When WXT sees an async content script, it will load the script asynchronously using a dynamic import.

await import(
  /* @vite-ignore */
  browser.runtime.getURL("path/to/chunk/entrypoint.js")
);

Questions:

• Does the run_at in the manifest make a difference in loading speed when using a dynamic import

  Jan 20, 2024: Slightly, we should respect it, and allow configuring it, with the knowledge that document_start doesn't work. See Content Script ESM Support #357 (comment)

• Can async content scripts be bundled in one step alongside HTML entrypoints, or do they have to be separated into their own step? My concern here is mixing chunks with side-effects that only work in HTML pages

  Jan 20, 2024: I don't think this is an issue, it's only an issue for the background service worker where there's no window global

• How will dev mode function and reload content scripts. What about main world content scripts, should those be grouped with the regular HTML file builds, or be in their own build step?

  Feb 2, 2024: Have not tested dev mode yet, but I am building the ESM background script with the other extension pages, so I'll do the same with isolated world content scripts. Main world content scripts will be combined with the sandbox pages since those don't have access to the browser APIs, like sandbox pages.

• Should type: "module" be the default value? It works well with the default run_at: "document_idle", and will likely provide a much better dev experience.

  Jan 21, 2024: If dev mode works well, yes, it will be the default.

  Feb 2, 2024: Initially, I'm going to make this an opt-in just like the background's type: "module". If it's working well for people, I'll try and make the the default before v1.0.

Is your feature request related to a bug?

#335

What are the alternatives?

No real alternatives to the feature as a whole. Instead of adding a new field, we could use runAt: "async", but that wouldn't provide a way to set the actual run_at in the manifest. That said, the run_at doesn't really matter, it can cause the browser to import the script earlier, but the code will never run before the DOMContentLoaded event.

Additional context

CC @yunsii

This will fix: #270

[yunsii]

This feature is really nice, I am exploring how to implement HMR in content script like CRXJS, it is really a magic.

[aklinker1]

I've switch my proposal to use type: "module" instead of runAt: "async".

---

@yunsii I'd like to structure the outputs like this:

.output/
  <target>/
    chunks/
      ...
    content-scripts/
      <name>.js
      <name>-loader.js

We may need to include the hash in dev mode to the non-loader file for HMR to work, I'm not sure.

At a minimum, the loader would look something like this:

import(
  /* @vite-ignore */
  browser.runtime.getURL("/content-scripts/<name>.js")
);

I'm also not sure where we need to call the main function of the content script. Inside the <name>.js like the above loader would do, or inside the <name>-loader.js, like this:

const { default } = await import(
  /* @vite-ignore */
  browser.runtime.getURL("/content-scripts/<name>.js")
);
default.main(...);

If I remember correctly, dynamically imported modules don't have access to the chrome or browser global, so we may need to use the second example, and actually run the main function of the content script inside the loader, which it has access to those globals.

[yunsii]

@aklinker1 Both examples seems ok, here is my demo https://github.com/yunsii/chrome-extension-raw-demo/blob/master/src/js/isolated_content_script.js

[aklinker1]

Cool, thanks for researching this! If both work, we'll go with whatever option makes the most sense during the implementation.

[yunsii]

we'll go with whatever option makes the most sense during the implementation.

What's the meaning? I do not understand exactly.

[aklinker1]

Did some testing with the run_at field. Behaved exactly as I expected. It could be useful to set the run_at field. For ecxample, with document_start you load your script a little bit earlier, but the code will never run before the DOMContentLoaded event, unlike without a dynamic import.

esm-run-at-testing.zip

[aklinker1]

we'll go with whatever option makes the most sense during the implementation.

What's the meaning? I do not understand exactly.

@yunsii Between the two options (running main inside the imported file, or running main inside the loader), since both work, we can use either one in WXT. So whichever option is easier to do while implementing this feature, we'll go with.

[aklinker1]

Also, for future reference, here are the minimum requirements to get ESM content scripts working:

1. Import statements must include the file extension

   This does not work:
   - import { logId } from './utils/log';
   This works:
   + import { logId } from './utils/log.js';

2. All imported files (chunks and non-loader entrypoints) must be listed in web_accessible_resources

    {
      "matches": [...],
      "resources": ["content-scripts/<name>.js", "chunks/*"]
    }

Here's a minimal example with an ESM service worker and content script sharing the ES module utility.

minimal-esm-chrome-extension.zip

[yunsii]

So it means that document_start and document_idle can use type: "module"?

[aklinker1]

So it means that document_start and document_idle can use type: "module"?

You can use all three run_at values (document_start, document_end, and document_idle) with type: "module". But only document_idle will behave the same way with or without type: "module"

[yunsii]

Did some testing with the run_at field. Behaved exactly as I expected. It could be useful to set the run_at field. For ecxample, with document_start you load your script a little bit earlier, but the code will never run before the DOMContentLoaded event, unlike without a dynamic import.

esm-run-at-testing.zip

I see, with type: "module", this means all run_at values can work, but dynamic imports with document_start and document_end have to wait until the proper timing to run?

[aklinker1]

Yup, exactly!