Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.
Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
This page is now obsolete, and its content has been incorporated into the main page on content scripts.
The constructors for content-script-using objects such as panel and page-mod define a group of options for loading content scripts:
contentScript string, array contentScriptFile string, array contentScriptWhen string contentScriptOptions object
We have already seen the contentScript option, which enables you to pass in the text of the script itself as a string literal. This version of the API avoids the need to maintain a separate file for the content script.
The contentScriptFile option enables you to pass in the local file URL from which the content script will be loaded. To supply the file "my-content-script.js", located in the /data subdirectory under your add-on's root directory, use a line like:
// "data" is supplied by the "self" module
var data = require("sdk/self").data;
...
contentScriptFile: data.url("my-content-script.js")
Both contentScript and contentScriptFile accept an array of strings, so you can load multiple scripts, which can also interact directly with each other in the content process:
// "data" is supplied by the "self" module
var data = require("sdk/self").data;
...
contentScriptFile:
[data.url("jquery-1.4.2.min.js"), data.url("my-content-script.js")]
Scripts specified using contentScriptFile are loaded before those specified using contentScript. This enables you to load a JavaScript library like jQuery by URL, then pass in a simple script inline that can use jQuery.
Unless your content script is extremely simple and consists only of a static string, don't use contentScript: if you do, you may have problems getting your add-on approved on AMO.
Instead, keep the script in a separate file and load it using contentScriptFile. This makes your code easier to maintain, secure, debug and review.
The contentScriptWhen option specifies when the content script(s) should be loaded. It takes one of three possible values:
-
"start" loads the scripts immediately after the document element for the page is inserted into the DOM. At this point the DOM content hasn't been loaded yet, so the script won't be able to interact with it.
-
"ready" loads the scripts after the DOM for the page has been loaded: that is, at the point the DOMContentLoaded event fires. At this point, content scripts are able to interact with the DOM content, but externally-referenced stylesheets and images may not have finished loading.
-
"end" loads the scripts after all content (DOM, JS, CSS, images) for the page has been loaded, at the time the window.onload event fires.
The default value is "end".
The contentScriptOptions is a json that is exposed to content scripts as a read only value under self.options property.
Any kind of jsonable value (object, array, string, etc.) can be used here.