cfx

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.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

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 WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

cfx is no longer supported as of Firefox 44 and no longer accepted for add-on submission. jpm should now be used instead.

For information on how to migrate from cfx to jpm see this guide.

Enables you to test, run, and package add-ons. cfx is is no longer supported as of Firefox 44 and no longer accepted for add-on submission, jpm should now be used instead. cfx usage is:

  cfx [options] command [command-specific options]

"Options" are global options applicable to the tool itself or to all commands (for example --help). cfx supports the following global options:

  -h, --help        - show a help message and exit
  -v, --verbose     - enable lots of output

"Command-specific options" are documented alongside the commands.

There are four supported cfx commands:

cfx init Create a skeleton add-on as a starting point for your own add-on.
cfx run Launch an instance of Firefox with your add-on installed.
cfx test Runs your add-on's unit tests.
cfx xpi Package your add-on as an XPI file, which is the install file format for Firefox add-ons.

There are also a number of internal commands, which are more likely to be useful to SDK developers than to add-on developers.

cfx init

Create a new directory called "my-addon", change into it, and run cfx init.

This command will create an skeleton add-on, as a starting point for your own add-on development, with the following file structure:

  • my-addon
    • data
    • docs
      • main.md
    • lib
      • main.js
    • package.json
    • README.md
    • tests
      • test-main.js
 

cfx run

This command is used to run the add-on. Called with no options it looks for a file called package.json in the current directory, loads the corresponding add-on, and runs it under the version of Firefox it finds in the platform's default install path.

Supported Options

You can point cfx run at a different package.json file using the --pkgdir option, and pass arguments to your add-on using the --static-args option.

You can specify a different version of the host application using the --binary option, passing in the path to the application binary to run. The path may be specified as a full path or may be relative to the current directory. But note that the version must be 4.0b7 or later.

cfx run runs the host application with a new profile. You can specify an existing profile using the --profiledir option, and this gives you access to that profile's history, bookmarks, and other add-ons. This enables you to run your add-on alongside debuggers like Firebug. See "Using --profiledir" for more information.

-b BINARY, --binary=BINARY Use the host application binary specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.
--binary-args=CMDARGS

Pass extra arguments to the binary being executed (for example, Firefox).

For example, to pass the -jsconsole argument to Firefox, which will launch the JavaScript Error Console, try the following:

cfx run --binary-args -jsconsole

To pass multiple arguments, or arguments containing spaces, quote them:

cfx run --binary-args '-url "www.mozilla.org" -jsconsole'
--extra-packages=EXTRA_PACKAGES Extra packages to include, specified as a comma-separated list of package names.
-g CONFIG, --use-config=CONFIG Pass a set of options by referencing a named configuration.
-p PROFILEDIR, --profiledir=PROFILEDIR

Use an existing profile located in PROFILEDIR. PROFILEDIR may be specified as a full path or as a path relative to the current directory.

See "Using --profiledir" for more information.

--package-path=PACKAGEPATH Extra directories for package search.
--pkgdir=PKGDIR Use an add-on located in PKGDIR. PKGDIR may be specified as a full path or as a path relative to the current directory.
--static-args=STATIC_ARGS Pass arguments to your add-on, in JSON format.

Experimental Options

-a APP, --app=APP By default, cfx run uses Firefox as the host application. This option enables you to select a different host. You can specify "firefox", "xulrunner", "fennec", or "thunderbird". But note that at present only Firefox is supported.
--no-run

With this option cfx will not execute the command, but will print out the command that it would have used to execute the command.

For example, if you type:

cfx run ---no-run

you will see something like:

To launch the application, enter the following command:
 /path/to/firefox/firefox-bin -profile
 /path/to/profile/tmpJDNlP6.mozrunner -foreground -no-remote

This enables you to run the add-on without going through cfx, which might be useful if you want to run it inside a debugger like GDB.

-o, --overload-modules

In early versions of the SDK, the SDK modules used by an add-on were themselves included in the add-on. The SDK modules now ship as part of Firefox. From Firefox 21 onwards, SDK add-ons built with SDK 1.14 or higher will use the SDK modules that are built into Firefox, even if the add-on includes its own copies of the SDK modules.

Use this flag to reverse that behavior: if this flag is set and the add-on includes its own copies of the SDK modules, then the add-on will use the SDK modules in the add-on, not the ones built into Firefox.

This flag is particularly useful for SDK developers or people working with the development version of the SDK, who may want to run an add-on using newer versions of the modules than than those shipping in Firefox.

--templatedir=TEMPLATEDIR The cfx run command constructs the add-on using a extension template which you can find under the SDK root, in app-extension. Use the --templatedir option to specify a different template. TEMPLATEDIR may be specified as a full path or as a path relative to the current directory.

Internal Options

--addons=ADDONS Paths of add-ons to install, comma-separated. ADDONS may be specified as a full path or as a path relative to the current directory.
--e10s If this option is set then the add-on runs in a separate process. This option is currently not implemented.
--keydir=KEYDIR Supply a different location for signing keys. KEYDIR may be specified as a full path or as a path relative to the current directory.
--logfile=LOGFILE Log console output to the file specified by LOGFILE. LOGFILE may be specified as a full path or as a path relative to the current directory.

cfx test

Run available tests for the specified package.

Called with no options this command will look for a file called package.json in the current directory. If package.json exists, cfx will load the corresponding add-on, load from the tests directory any modules that start with the word test- and run the unit tests they contain.

Note the hyphen after "test" in the module name. cfx test will include a module called "test-myCode.js", but will exclude modules called "test_myCode.js" or "testMyCode.js".

See the tutorial on unit testing and the reference documentation for the assert module for details.

Supported Options

As with cfx run you can use options to control which host application binary version to use, and to select a profile.

You can also control which tests are run: you can test dependent packages, filter the tests by name and run tests multiple times.

-b BINARY, --binary=BINARY Use the host application binary specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.
--binary-args=CMDARGS

Pass extra arguments to the binary being executed (for example, Firefox).

For example, to pass the -jsconsole argument to Firefox, which will launch the JavaScript Error Console, try the following:

cfx run --binary-args -jsconsole

To pass multiple arguments, or arguments containing spaces, quote them:

cfx run --binary-args '-url "www.mozilla.org" -jsconsole'
--dependencies Load and run any tests that are included with modules that your package depends on.
For example: if your add-on depends on modules from the SDK, then cfx will run the unit tests for the SDK's modules as well as yours.
-f FILENAME[:TESTNAME], --filter=FILENAME[:TESTNAME] Only run tests whose filenames match FILENAME and optionally match TESTNAME, both regexps (test, testall, testex, testpkgs)
For example: if you specify --filter data, then cfx will only run tests in those modules whose name contain the string "data".
-g CONFIG, --use-config=CONFIG Pass a set of options by referencing a named configuration.
-p PROFILEDIR, --profiledir=PROFILEDIR

Use an existing profile located in PROFILEDIR. PROFILEDIR may be specified as a full path or as a path relative to the current directory.

See "Using --profiledir" for more information.

--package-path=PACKAGEPATH Extra directories for package search.
--pkgdir=PKGDIR Use an add-on located in PKGDIR. PKGDIR may be specified as a full path or as a path relative to the current directory.
--times=ITERATIONS Execute tests ITERATIONS number of times.

Experimental Options

-a APP, --app=APP By default, cfx test uses Firefox as the host application. This option enables you to select a different host. You can specify "firefox", "xulrunner", "fennec", or "thunderbird". But note that at present only Firefox is supported.
--check-memory Attempts to detect leaked compartments after a test run.
--no-run

With this option cfx will not execute the command, but will print out the command that it would have used to execute the command.

For example, if you type:

cfx run ---no-run

you will see something like:

To launch the application, enter the following command:
 /path/to/firefox/firefox-bin -profile
 /path/to/profile/tmpJDNlP6.mozrunner -foreground -no-remote

This enables you to run the add-on without going through cfx, which might be useful if you want to run it inside a debugger like GDB.

-o, --overload-modules

In early versions of the SDK, the SDK modules used by an add-on were themselves included in the add-on. The SDK modules now ship as part of Firefox. From Firefox 21 onwards, SDK add-ons built with SDK 1.14 or higher will use the SDK modules that are built into Firefox, even if the add-on includes its own copies of the SDK modules.

Use this flag to reverse that behavior: if this flag is set and the add-on includes its own copies of the SDK modules, then the add-on will use the SDK modules in the add-on, not the ones built into Firefox.

This flag is particularly useful for SDK developers or people working with the development version of the SDK, who may want to run an add-on using newer versions of the modules than than those shipping in Firefox.

--stop-on-error Stop running tests after the first failure.

Internal Options

--addons=ADDONS Paths of add-ons to install, comma-separated. ADDONS may be specified as full paths or relative to the current directory.
--e10s If this option is set then the add-on runs in a separate process. This option is currently not implemented.
--keydir=KEYDIR Supply a different location for signing keys. KEYDIR may be specified as a full path or as a path relative to the current directory.
--logfile=LOGFILE Log console output to the file specified by LOGFILE. LOGFILE may be specified as a full path or as a path relative to the current directory.
--profile-memory=PROFILEMEMORY If this option is given and PROFILEMEMORY is any non-zero integer, then cfx dumps detailed memory usage information to the console when the tests finish.
--test-runner-pkg=TEST_RUNNER_PKG Name of package containing test runner program. Defaults to test-harness.

cfx xpi

This tool is used to package your add-on as an XPI file, which is the install file format for Mozilla add-ons.

Called with no options, this command looks for a file called package.json in the current directory and creates the corresponding XPI file.

Once you have built an XPI file you can distribute your add-on by submitting it to addons.mozilla.org.

If you choose to host the XPI yourself you should enable the host application to find new versions of your add-on.

To do this, include a URL in the XPI called the updateURL: the host application will go here to get information about updates. At the updateURL you host a file in the update RDF format: among other things, this includes another URL called updateLink which points to the updated XPI itself.

The --update-link and --update-url options simplify this process. Both options take a URL as an argument.

The --update-link option builds an update RDF alongside the XPI, and embeds the supplied URL in the update RDF as the value of updateLink.

The --update-url option embeds the supplied URL in the XPI file, as the value of updateURL.

Note that as the add-on documentation explains, you should make sure the update procedure for your add-on is secure, and this usually involves using HTTPS for the links.

So if we run the following command:

  cfx xpi --update-link https://example.com/addon/latest/pluginName.xpi --update-url https://example.com/addon/update_rdf/pluginName.update.rdf

cfx will create two files:

  • an XPI file which embeds https://example.com/addon/update_rdf/pluginName.update.rdf as the value of updateURL
  • an RDF file which embeds https://example.com/addon/latest/pluginName.xpi as the value of updateLink.

Supported Options

As with cfx run you can point cfx at a different package.json file using the --pkgdir option. You can also embed arguments in the XPI using the --static-args option: if you do this the arguments will be passed to your add-on whenever it is run.

--extra-packages=EXTRA_PACKAGES Extra packages to include, specified as a comma-separated list of package names.
-g CONFIG, --use-config=CONFIG Pass a set of options by referencing a named configuration.
--package-path=PACKAGEPATH Extra directories for package search.
--pkgdir=PKGDIR Use an add-on located in PKGDIR. PKGDIR may be specified as a full path or as a path relative to the current directory.
--static-args=STATIC_ARGS Pass arguments to your add-on, in JSON format.
--update-link=UPDATE_LINK Build an update RDF alongside the XPI file, and embed the URL supplied in UPDATE_LINK in it as the value of updateLink.
--update-link=UPDATE_URL Embed the URL supplied in UPDATE_URL in the XPI file, as the value of updateURL.
--no-strip-xpi Will force the packager to include all files into the output xpi. If your extension works unpacked, but breaks after you cfx xpi it, you should try using this option.

Experimental Options

--harness-option=KEY=VALUE Extra properties added to harness-options.json.
--manifest-overload Add fields to, or override selected fields in, package.json. This option takes an argument which is a path to a file containing JSON, and overloads any property of package.json with the properties found in the specified file.
--output-file=OUTPUT_FILE Where to put the finished XPI file.
--templatedir=TEMPLATEDIR

The cfx xpi command constructs the add-on using a extension template which you can find under the SDK root, in app-extension. Use the --templatedir option to specify a different template. TEMPLATEDIR may be specified as a full path or as a path relative to the current directory.

Internal Options

--keydir=KEYDIR Supply a different location for signing keys. KEYDIR may be specified as a full path or as a path relative to the current directory.

Internal Commands

cfx testcfx

This will run a number of tests on the cfx tool, including tests against the documentation. Use cfx testcfx -v for the specific list of tests.

This accepts the same options as cfx test.

cfx testaddons

This will run a number of test add-ons that are packaged with the SDK.

This accepts the same options as cfx test.

cfx testpkgs

This will test all of the available CommonJS packages. Note that the number of tests run and their success depends on what application they are run with, and which binary is used.

This accepts the same options as cfx test.

cfx testex

This will test all available example code. Note that the number of tests run and their success depends on what application they are run with, and which binary is used.

This accepts the same options as cfx test.

cfx testall

This will test everything: the cfx tool, all available CommonJS packages, and all examples.

This accepts the same options as cfx test.

Using --profiledir

By default, cfx run and cfx test use a new profile each time they are executed. This means that any profile-specific data entered from one run of cfx will not, by default, be available in the next run.

This includes, for example, any extra add-ons you installed, or your history, or any data stored using the simple-storage API.

To make cfx use a specific profile, pass the --profiledir option, specifying the path to the profile you wish to use.

If you give --profiledir a path to a nonexistent profile, cfx will create a profile there for you. So you just have to make up a path and name the first time, and keep using it:

cfx run --profiledir=~/addon-dev/profiles/boogaloo

The path must contain at least one "/" (although you may specify just "./dir").

Using Configurations

The --use-config option enables you to specify a set of options as a named configuration in a file, then pass them to cfx by referencing the named set.

You define configurations in a file called local.json which should live in the root directory of your SDK. Configurations are listed under a key called "configs".

Suppose your the following local.json is as follows:

  {
      "configs": {
          "ff40": ["-b", "/usr/bin/firefox-4.0"]
      }
  }

You can run:

  cfx test --use-config=ff40

And it would be equivalent to:

  cfx test -a firefox -b /usr/bin/firefox-4.0

This method of defining configuration options can be used for all of the run, build, and test tools. If "default" is defined in the local.json cfx will use that configuration unless otherwise specified.

Passing Static Arguments

You can use the cfx --static-args option to pass arbitrary data to your program. This may be especially useful if you run cfx from a script.

The value of --static-args must be a JSON string. The object encoded by the JSON becomes the staticArgs property of the system module.

The default value of --static-args is "{}" (an empty object), so you don't have to worry about checking whether staticArgs exists in system.

For example, if your add-on looks like this:

var system = require("sdk/system");
console.log(system.staticArgs.foo);

And you run cfx like this:

  cfx run --static-args="{ \"foo\": \"Hello from the command line\" }"

Then your console should contain this:

info: my-addon: Hello from the command line

The --static-args option is recognized by two of the package-specific commands: run and xpi. When used with the xpi command, the JSON is packaged with the XPI's harness options and will therefore be used whenever the program in the XPI is run.

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, One, evold, willlma, MeLight, backy0175
 Last updated by: wbamberg,