Skip to content

Content script load order clarification #39298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rebloor merged 6 commits into from
May 21, 2025
Merged

Content script load order clarification #39298

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5105bf1
Content script load order clarification
rebloor Apr 28, 2025
38b1261
Apply linter suggestions
rebloor Apr 28, 2025
0baee9b
Update for feedback
rebloor Apr 29, 2025
d046f99
Update to manifest example
rebloor May 12, 2025
f50fc37
Apply suggestions from review
rebloor May 16, 2025
6b67d13
Revised load order description
rebloor May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 49 additions & 27 deletions files/en-us/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ browser-compat: webextensions.manifest.content_scripts
</tbody>
</table>

Instructs the browser to load [content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) into web pages whose URL matches a given pattern.
Instructs the browser to load [content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) into web pages whose URL matches a pattern.

This key is an array. Each item is an object which:

- **must** contain a key named **`matches`**, which specifies the URL patterns to be matched in order for the scripts to be loaded;
- **may** contain keys named **`js`** and **`css`**, which list scripts and/or stylesheets to be loaded into matching pages; and
- **may** contain a number of other properties that control finer aspects of how and when content scripts are loaded.
- **must** contain a key named **`matches`**, which specifies the URL patterns to be matched for the scripts to be loaded;
- **may** contain keys named **`js`** and **`css`**, which list scripts and stylesheets to be loaded into matching pages; and
- **may** contain a number of other properties that control aspects of how and when content scripts are loaded.

Details of all the keys you can include are given in the table below.
This table details all the keys you can include.

<table class="fullwidth-table standard-table">
<thead>
Expand Down Expand Up @@ -100,12 +100,9 @@ Details of all the keys you can include are given in the table below.
<td>
<p>
An array of paths, relative to <code>manifest.json</code>, referencing
CSS files that will be injected into matching pages.
CSS files to inject into matching pages. For information on the order
Comment thread
rebloor marked this conversation as resolved.
Outdated
in which files are injected, see a <a href="#load_order">Load order</a>.
</p>
<p>
Files are injected in the order given, and at the time specified by
Comment thread
dotproto marked this conversation as resolved.
<code><a href="#run_at">run_at</a></code
>.
</p>
<div class="notecard note">
<p>
Expand Down Expand Up @@ -156,23 +153,8 @@ Details of all the keys you can include are given in the table below.
<td>
<p>
An array of paths, relative to <code>manifest.json</code>, referencing
JavaScript files that will be injected into matching pages.
</p>
<p>
Files are injected in the order given. This means that, for example,
if you include jQuery here followed by another content script, like
this:
</p>
<pre class="brush: json">
"js": ["jquery.js", "my-content-script.js"]</pre
>
<p>Then, <code>"my-content-script.js"</code> can use jQuery.</p>
<p>
The files are injected after any files in
<code><a href="#css">css</a></code
>, and at the time specified by
<code><a href="#run_at">run_at</a></code
>.
JavaScript files to inject into matching pages. For information on the
Comment thread
rebloor marked this conversation as resolved.
Outdated
order in which files are injected, see a <a href="#load_order">Load order</a>.
</p>
</td>
</tr>
Expand Down Expand Up @@ -324,6 +306,46 @@ Details of all the keys you can include are given in the table below.
</tbody>
</table>

## Load order

@dotproto dotproto Apr 28, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a reader, I find the current framing a little confusing. The first sentence in this section starts by talking about the order in which "matching key objects are processed," but it's not immediately clear to me why that matters.

It feels like the current copy is too focused on the implementation details of parsing an array of objects rather than the thing I want to understand as a developer: what (if any) guarantees are there about the order in which my content scripts will be added to (and executed on) a web page.

For the moment, I think just adding an intro statement would help clarify this content. For example:

Files declared in content scripts are injected into web pages in a well defined order. When a webpage loads, matching key objects are processed in this order:

Longer term, I think we should consider moving this to the content scripts page and building it out to cover both the static content scripts definitions from this page and the dynamic content scripts declrations from the runtime API.


When a webpage load loads, matching key objects are processed in this order:

@dotproto dotproto Apr 28, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When a webpage load loads, matching key objects are processed in this order:
When a webpage loads, matching key objects are processed in this order:


- in accordance with the `run_at` directive (`"document_start"` then `"document_end"` then `"document_idle"`). For each object with the same directive:

@dotproto dotproto Apr 28, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we link to run_at rather than include possible values here? Having it inline is both more info for the reader to parse and more content to maintain should the potential values change.

- in the order of each object in the key array, then for each object:
- CSS in the order items are specified in the object's `css` property, then,
- JavaScript in the order items are specified in the object's `js` property.

For example, in this key specification:

```json
"content_scripts": [
{
"matches": ["*://*.mozilla.org/*"],
"js": ["my-content-script.js"],
"run_at": "document_idle"
},
{
"matches": ["*://*.mozilla.org/*"],
"css": ["my-css.css"],
"js": ["another-content-script.js", "yet-another-content-script.js"],
"run_at": "document_idle"
},
{
"matches": ["*://*.mozilla.org/*"],
"js": ["jquery.js"],

@Rob--W Rob--W May 12, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May I suggest putting jquery.js back in the original list of two scripts, and use run-first.js here? jquery can be viewed as a dependency of the other scripts, and if they are indeed dependent, then it makes much more sense to put them in the same declaration.

Something called "run-first.js" already conveys from its name what it is supposed to do.

Comment thread
rebloor marked this conversation as resolved.
Outdated
"run_at": "document_start"
}
]
```

The files are loaded like this when a mozilla.org domain opens:

- `"jquery.js"` - because it's requested to run at `"document_start"`.
Comment thread
rebloor marked this conversation as resolved.
Outdated
- `"my-content-script.js"` - because it's in the first array requesting run at `"document_idle"`.
Comment thread
rebloor marked this conversation as resolved.
Outdated
- `"my-css.css"` - because an object's CSS is loaded before its JavaScript.
- `"another-content-script.js"` - because it's the first item in the `js` property.
- `"yet-another-content-script.js"`
Comment on lines +341 to +347

@dotproto dotproto Apr 28, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like helping concertize this information with a grounded example. I think we can improve on this explanation, though, by adding notes about things like when the website's own scripts run, when DOM events occur (e.g. DOMContentLoaded), and referencing which content script object is being processed at a given moment.


## Matching URL patterns

The `"content_scripts"` key attaches content scripts to documents based on URL matching: if the document's URL matches the specification in the key, then the script will be attached. There are four properties inside `"content_scripts"` that you can use for this specification:
Expand Down