Repository files navigation

Front-end infrastructure and code to complementmozilla/addons-server.

This code and its associated production website are included in Mozilla’s web and servicesbug bounty program. If you find a security vulnerability, please submit it via the process outlined in the program andFAQ pages. Further technical details about this application are available from theBug Bounty Onramp page.

Please submit all security-related bugs through Bugzilla using theweb security bug form.

Never submit security-related bugs through a Github Issue or by email.

• You needNodeLTS (long term support) release.
• Installyarn to manage dependencies and run scripts.

The easiest way to manage multiple node versions in development is to usenvm.

If you are on Windows, please make sure to followwindows guidelines too.

• typeyarn to install all dependencies
• typeyarn amo:stage to start a local server that connects to a hosted staging server

Here are some commands you can run:

You can enter the interactivejest mode by typingyarn test oryarn test-debug. This is the easiest way to develop new features.

Here are a few tips:

• yarn test will hide most console output and detailed test failure messages, so it is best when you are running a full suite of tests. When working on an individual test, you likely want to runyarn test-debug.
• When you startyarn test, you can switch to your code editor and begin adding test files or changing existing code. As you save each file,jest will only run tests related to the code you change.
• If you had typeda when you first started thenjest will continue to run the full suite even when you change specific files. Typeo to switch back to the mode of only running tests related to the files you are changing.
• Sometimes running tests related to your file changes is slow. In these cases, you can typep ort to filter tests by name while you working fixing a specific test suite.More info.
• If you see something likeError watching file for changes: EMFILE on Mac OS thenbrew install watchman might fix it. Seejestjs/jest#1767

By default,yarn test will only run a subset of tests that relate to the code you are working on.

To explicitly run a subset of tests, you can typet orp which are explained in thejest watch usage.

Alternatively, you can start the test runner with aspecific file or regular expression, like:

yarn test tests/unit/amo/components/TestAddon.js

If you want to run all tests and exit, type:

yarn test-once

As you run tests you will see a report of Eslint errors at the end of the test output:

yarn test

If you would like to run tests without Eslint checks, set an environment variable:

NO_ESLINT=1 yarn test

There is limited support for usingFlow to validate the intention of our program.

As you run tests you will see a report of Flow errors at the end of the test output:

yarn test

If you would like to run tests without Flow checks, set an environment variable:

NO_FLOW=1 yarn test

To only check for Flow issues during development while you edit files, run:

yarn flow:dev

If you are new to working with Flow, here are some tips:

• Check out thegetting started guide.
• Read through theweb-ext guide for hints on how to solve common Flow errors.

To add flow coverage to a source file, put a/* @flow */ comment at the top. The more source files you can opt into Flow, the better.

Here is our Flow manifesto:

• We use Flow todeclare the intention of our code and help others refactor it with confidence. Flow also makes it easier to catch mistakes before spending hours in a debugger trying to find out what happened.
• Avoid magicFlow declarations for anyinternal code. Just declare atype alias next to the code where it's used andexport/import it like any other object.
• Never import a real JS object just to reference its type. Make a type alias and import that instead.
• Never add more type annotations than you need. Flow is really good at inferring types from standard JS code; it will tell you when you need to add explicit annotations.
• When a function likegetAllAddons takes object arguments, call its type objectGetAllAddonsParams. Example:

typeGetAllAddonsParams={|categoryId:number,|};functiongetAllAddons({ categoryId}:GetAllAddonsParams={}){  ...}

• UseExact object types via the pipe syntax ({| key: ... |}) when possible. Sometimes the spread operator triggers an error like 'Inexact type is incompatible with exact type' but that's abug. You can use theExact<T> workaround fromsrc/amo/types/util if you have to. This is meant as a working replacement for$Exact.
• Add a type hint for components wrapped in HOCs (higher order components) so that Flow can validate calls to the component. We need to add a hint because we don't yet have decent type coverage for all the HOCs we rely on. Here is an example:

// Imagine this is something like components/ConfirmButton/index.jsimport{compose}from'redux';import*asReactfrom'react';// This expresses externally used props, i.e. to validate how the app would use <ConfirmButton />typeProps={|prompt?:string|null,|};// This expresses internally used props, such as i18n which is injected by translate()typeInternalProps={|  ...Props,i18n:I18nType,|};exportclassConfirmButtonBaseextendsReact.Component<InternalProps>{render(){constprompt=this.props.prompt||this.props.i18n.gettext('Confirm');return<button>{prompt}</button>;}}// This provides a type hint for the final component with its external props.// The i18n prop is not in external props because it is injected by translate() for internal use only.constConfirmButton:React.ComponentType<Props>=compose(translate())(ConfirmButtonBase,);exportdefaultConfirmButton;

• Try to avoid loose types likeObject orany but feel free to use them if you are spending too much time declaring types that depend on other types that depend on other types, and so on.
• You can add a$FlowFixMe comment to skip a Flow check if you run into a bug or if you hit something that's making you bang your head on the keyboard. If it's something you think is unfixable then use$FlowIgnore instead. Please explain your rationale in the comment and link to a GitHub issue if possible.
• If you're stumped on why some Flow annotations aren't working, try using theyarn flow type-at-pos ... command to trace which types are being applied to the code. Seeyarn flow -- --help type-at-pos for details.

We usePrettier to automatically format our JavaScript code and stop all the on-going debates over styles.

To see a report of code coverage, type:

yarn test-coverage-once

This will print a table of files showing the percentage of code coverage. The uncovered lines will be shown in the right column but you can open the full report in a browser:

open coverage/lcov-report/index.html

A proxy server is provided for running the AMO app with the API on the same host as the frontend. This mimics our production setup.

Start developing against a hosted API like this:

yarn amo:dev

This configures the proxy to usehttps://addons-dev.allizom.org for API data. This command is the most common way to develop new frontend features. See the table of commands up above for similar ways to run the server.

To use alocal API server running in Docker, you can use theyarn amo command. However, this is currently not working. Seeissue-7196.

Authentication will work when initiated from addons-frontend and will persist to addons-server but it will not work when logging in from an addons-server page. Seemozilla/addons-server#4684 for more information on fixing this.

If you need to override any settings while runningyarn amo,yarn amo:dev, oryarn amo:stage, first create a local config file named exactly like this:

touch config/local-development.js

Make any config changes. For example:

module.exports={trackingEnabled:true,};

Restart the server to see it take affect.

Consult theconfig file loading order docs to learn more about how configuration is applied.

If you want to access your local server on an Android device you will need to change a few settings. Let's say your local machine is accessible on your network at the IP address10.0.0.1. You could start your server like this:

API_HOST=http://10.0.0.1:3000 \    SERVER_HOST=10.0.0.1 \    WEBPACK_SERVER_HOST=10.0.0.1 \    yarn amo:dev

On your Android device, you could then access the development site athttp://10.0.0.1:3000.

NOTE: At this time, it is not possible to sign in with this configuration because the Mozilla accounts client redirects tolocalhost:3000. You may be able to try a different approach by editing/etc/hosts on your device so thatlocalhost points to your development machine but this has not been fully tested.

When developing locally with a webpack server, the randomly generated asset URL will fail our Content Security Policy (CSP) and clutter your console with errors. You can turn off all CSP errors by settings CSP tofalse in any local config file, such aslocal-development-amo.js. Example:

module.exports={CSP:false,};

The documentation you are reading right now lives inside the source repository asGithub flavored Markdown. When you make changes to these files you can create a pull request to preview them or, better yet, you can usegrip to preview the changes locally. After installinggrip, run it from the source directory like this:

grip .

Open itslocalhost URL and you will see the renderedREADME.md file. As you make edits, it will update automatically.

The following are scripts that are used in deployment - you generally won't need unless you're testing something related to deployment or builds.

The env vars are:

• NODE_ENV: the node environment, e.g.production ordevelopment
• NODE_CONFIG_ENV: the name of the configuration to load, e.g.,dev,stage,prod

Example: Building and running a production instance of the app:

NODE_ENV=production NODE_CONFIG_ENV=prod yarn buildNODE_ENV=production NODE_CONFIG_ENV=prod yarn start

To run the app locally in production mode you'll need to create a config file for local production builds. Production builds can be built for different environments:dev,stage andprod (controlled by theNODE_CONFIG_ENV env var), but only one extra config file is needed for these environments to run locally.

Rename the file namedconfig/local.js.dist toconfig/local.js. After this, re-build and restart usingyarn build andyarn start as documented above. If you have used127.0.0.1 before with a different configuration, be sure to clear your cookies. The application should be available at:http://127.0.0.1:4000/.

NOTE: At this time, it's not possible to sign in using this approach.

You can check to see what commit ofaddons-frontend is deployed, which A/B experiments are running, or which feature flags are enabled by making a request like this:

curl https://addons-dev.allizom.org/__frontend_version__{    "build": "https://circleci.com/gh/mozilla/addons-frontend/10333",    "commit": "47edfa6f24e333897b25516c587f504e294e8fa9",    "experiments": {        "homeHero": true    },    "feature_flags": {        "enableFeatureAMInstallButton": true,        "enableFeatureStaticThemes": true    },    "source": "https://github.com/mozilla/addons-frontend",    "version": ""}

This will return a 415 response if aversion.json file doesn't exist in the root directory. This file is typically generated by the deploy process.

For consistency with monitoring scripts, the same data can be retrieved at this URL:

curl https://addons-dev.allizom.org/__version__

💡 You can install theamo-info extension to easily view this information.

This project also contains code to build a library namedaddons-frontend-blog-utils and offers the following commands:

• yarn build:blog-utils-dev: build the library, start a watcher to rebuild the library on change and serve a development page athttp://127.0.0.1:11000
• yarn build:blog-utils-prod: build the library in production mode

This library is exclusively designed to work withaddons-blog.

In order to publish a new version ofaddons-frontend-blog-utils, a special tag has to be pushed to the main repository. The tag name must start withblog-utils- and usually contains the version number. This can be automated using the following command:

npm version [major|minor|patch]

Issuing this command from themaster branch will update the version in thepackage.json, create a commit and create a tag. Push both this commit and the tag to the main repository.

Note: When a newaddons-frontend-blog-utils release is merged inaddons-blog, you should publish a new version of the WordPress theme. Please followthese instructions in the addons-blog repository.

• Based on Redux + React
• Code written in ES2015+
• Universal rendering via node
• Unit tests with high coverage (aiming for 100%)