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 4 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
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
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.


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

@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.

Suggested edit to address my feedback at https://github.com/mdn/content/pull/39298/files#r2075072868

Suggested change
Files declared in `content_scripts` are injected into web pages in a defined order. When a webpage loads, matching key objects are processed in this order:
Files declared in `content_scripts` are injected into web pages in a defined order: At the time specified by `run_at`, in the order as given in the `css` / `js` arrays.
When a webpage loads, matching key objects are processed in this order:

@rebloor rebloor May 12, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@Rob--W I'm unclear how this could help the reader: they are now presented with two slightly different statements of the processing order. And, as I commented previously, this statement doesn't include what I understood to be the whole reason for the change, i.e., the statement about the object ordering the key array.

@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.

@Rob--W I'm unclear how this could help the reader: they are now presented with two slightly different statements of the processing order.

I think that a concise one-sentence frame helps the reader with putting your following explanation in the right context. The list of steps below could result in the appearance that there is some complex rule (that the reader must brace for), while the rule is relatively simple: run_at, and then the order as given. If someone already understands this one sentence rule, they don't need to read the rest.

And, as I commented previously, this statement doesn't include what I understood to be the whole reason for the change, i.e., the statement about the object ordering the key array.

Your fuller explanation covers that. The sentence here is mainly to get the rule of thumb. And as phrased, it could also include the order of js/css arrays across all objects (but it could also mean just within the object). It is not needed to make the sentence longer to address that ambiguity.

@rebloor rebloor May 12, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@Rob--W For clarity, we should state the rule only once.

@Rob--W Rob--W May 16, 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.

I'd be fine with stating the rule only once. Can we choose a phrasing that fits more naturally with how it actually works? The current text below describes some ordering, without the time aspect of run_at (they are evaluated separately at different times!). The mentions of "each object", "object", "key value" and "each object" again is getting me confused, requiring me to think what exactly it is referring to.

Here is an example of text that conveys the concepts more naturally, at least to me.

At each point in time specified by `run_at`
(first `document_start`, then`document_end`, and finally `document_idle`),
the registered objects in `content_scripts` are run as follows:

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

@rebloor rebloor May 16, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@Rob--W a slight irony here in that my original draft included detailing the sequence of run_at directives, but @dotproto suggested removing them to avoid duplication and redundancy. Please check out my update.

@dotproto dotproto May 21, 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.

For reference, here's my comment. At the time I just read it as a list of possible run_at values, not as commentary about their execution order. That was an oversight on my part.


- in accordance with the `run_at` directive, then for each object with the same directive:
- 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": ["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:

- `"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