Repository navigation
Description
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 therun_atin the manifest make a difference in loading speed when using a dynamic importJan 20, 2024: Slightly, we should respect it, and allow configuring it, with the knowledge that
document_startdoesn'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 pagesJan 20, 2024: I don't think this is an issue, it's only an issue for the background service worker where there's no
windowglobal - 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.
-
Shouldtype: "module"be the default value? It works well with the defaultrun_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?
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
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsTodo
Activity
yunsii commentedon Jan 19, 2024
This feature is really nice, I am exploring how to implement HMR in content script like CRXJS, it is really a magic.
aklinker1 commentedon Jan 19, 2024
I've switch my proposal to use
type: "module"instead ofrunAt: "async".@yunsii I'd like to structure the outputs like this:
At a minimum, the loader would look something like this:
I'm also not sure where we need to call the
mainfunction of the content script. Inside the<name>.jslike the above loader would do, or inside the<name>-loader.js, like this:If I remember correctly, dynamically imported modules don't have access to the
chromeorbrowserglobal, so we may need to use the second example, and actually run themainfunction of the content script inside the loader, which it has access to those globals.[-]"async" content script support[/-][+]Content Script ESM Support[/+]yunsii commentedon Jan 20, 2024
@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 commentedon Jan 20, 2024
Cool, thanks for researching this! If both work, we'll go with whatever option makes the most sense during the implementation.
yunsii commentedon Jan 20, 2024
What's the meaning? I do not understand exactly.
aklinker1 commentedon Jan 20, 2024
Did some testing with the
run_atfield. Behaved exactly as I expected. It could be useful to set therun_atfield. For ecxample, withdocument_startyou load your script a little bit earlier, but the code will never run before theDOMContentLoadedevent, unlike without a dynamic import.esm-run-at-testing.zip
aklinker1 commentedon Jan 20, 2024
@yunsii Between the two options (running
maininside the imported file, or runningmaininside 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 commentedon Jan 20, 2024
Also, for future reference, here are the minimum requirements to get ESM content scripts working:
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 commentedon Jan 20, 2024
So it means that
document_startanddocument_idlecan usetype: "module"?aklinker1 commentedon Jan 20, 2024
You can use all three
run_atvalues (document_start,document_end, anddocument_idle) withtype: "module". But onlydocument_idlewill behave the same way with or withouttype: "module"yunsii commentedon Jan 20, 2024
I see, with
type: "module", this means allrun_atvalues can work, but dynamic imports withdocument_startanddocument_endhave to wait until the proper timing to run?aklinker1 commentedon Jan 20, 2024
Yup, exactly!
23 remaining items
yunsii commentedon Aug 17, 2024
It means we can use dynamic import manually anywhere now? the dynamic import modules will not be bundle into the entry file?
aklinker1 commentedon Aug 17, 2024
@yunsii no, WXT will never produce code-split ESM by itself.
This line tells vite to not analyze or bundle the dynamic import, and leave it as-is in the final output.
https://github.com/wxt-dev/examples/blob/main/examples%2Fesm-content-script-ui%2Fentrypoints%2Fcontent%2Findex.ts#L4-L7
Then you are then responsible for making sure the imported file exists, which is done with a custom vite build here:
https://github.com/wxt-dev/examples/blob/main/examples%2Fesm-content-script-ui%2Fmodules%2Fesm-builder.ts#L32
yunsii commentedon Aug 18, 2024
I see, with WXT Reusable Modules to custom build esm modules and then import them manually.
But it still not easy to use, why not integrated directly by WXT?
aklinker1 commentedon Aug 18, 2024
Hmm, I got it stuck in my head that this issue was about HMR, but if we ignore that and continue to do separate, code-split enabled builds with reloads like content scripts work today... It might be possible to implement a generic solution. Let me think on this more.
gabrielgrant commentedon Feb 12, 2025
Any update on this?
aklinker1 commentedon Feb 13, 2025
Not a priority for me until v1.0 is out. The tradeoff of not respecting
run_atmeans this specific feature has no real value to me personally, and there is a way to manually create a code-split content script. I will add this eventually, but not right now.rxliuli commentedon Mar 3, 2025
I still want a code splitting script, especially in dev mode, which is very useful for large plugins. For example, my content-script is over 16+M uncompressed right now, which makes hmr very, very slow. I guess chunk split would help.
kirankunigiri commentedon Jan 14, 2026
Hi! Wondering if this this going to be revisited anytime soon? Saving any content script file in my project takes 5+ seconds to reload and it's basically unusable for larger projects.
rxliuli commentedon Jan 15, 2026
For anyone tired of excessively long build times, try upgrading wxt + vite and using the beta version of rolldown. In my testing, it reduced build time by nearly 10x (35s => 3s). Unfortunately, my entire extension codebase has become rotten, containing many outdated dependencies, and I have to consider a complete rewrite to use it.
aklinker1 commentedon Feb 11, 2026
I meant to have this in the v1.1 milestone, added. I am putting this off until v1.0 is released. No ETA on that right now.
oyzamil commentedon Apr 18, 2026
Maybe this custom hook can help you: