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 all commits
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
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
<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
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
Copy link
Contributor

@dotproto dotproto Apr 28, 2025

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.


Registered objects in `content_scripts` are injected into matching web pages at the time specified by `run_at` (first `document_start`, then`document_end`, and finally `document_idle`):

- In the order specified in the `content_scripts` array, for each object with a matching `run_at` value, then:
- CSS is applied in the order specified in its `css` array.
- JavaScript code is executed in the order specified in its `js` array.

For example, in this key specification:

```json
"content_scripts": [
{
"matches": ["*://*.mozilla.org/*"],
"js": ["jquery.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": ["run-first.js"],
"run_at": "document_start"
}
]
```

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

- `"run-first.js"` - because it's requested to run at `"document_start"`.
- `"jquery.js"` - because it's in the first array requesting run at `"document_idle"`.
- `"my-content-script.js"` - because it's the second item in the first array requesting run at `"document_idle"`.
- `"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"`

## 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