This code and its associated production website are included in Mozilla’s web and services [bug bounty program]. If you find a security vulnerability, please submit it via the process outlined in the program and [FAQ pages]. Further technical details about this application are available from the [Bug Bounty Onramp page].
| yarn amo:dev | Start the dev server/proxy (for amo) using data from the dev server (https://addons-dev.allizom.org/) |
| yarn amo:dev-https | Same as `amo:dev` but with HTTPS, available at: https://example.com:3000/. [Read about setting up this environment](docs/moz-addon-manager.md#developing-with-a-local-https-server-recommended) |
| yarn amo:no-proxy | Start the dev server without a proxy (for amo) using data from Docker |
| yarn amo:stage | Start the dev server/proxy (for amo) using data from the staging server (https://addons.allizom.org/) |
| yarn build | Build an app specified with the `NODE_APP_INSTANCE` environment variable. |
| yarn build-all | Build all the applications. |
| yarn build-ci | Run the `build-all` and `bundlesize` npm scripts. |
| yarn bundlesize | Run [bundlesize][] to check the generated AMO bundle sizes. [Building AMO is required first](#building-and-running-services). |
| yarn disco | Start the dev server (for Discovery Pane) using data from the dev server (https://addons-dev.allizom.org/) |
| yarn disco:https | Same as `disco` but with HTTPS, available at: https://example.com:3000/. [Read about setting up this environment](docs/moz-addon-manager.md#developing-with-a-local-https-server-recommended) |
- When you start `yarn 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 typed `a` when you first started then [jest][] will continue to run the full suite even when you change specific files. Type `o` 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 type `p` or `t` to filter tests by name while you working fixing a specific test suite. [More info](https://github.com/jest-community/jest-watch-typeahead).
- If you see something like `Error watching file for changes: EMFILE` on Mac OS then `brew install watchman` might fix it. See https://github.com/facebook/jest/issues/1767
To explicitly run a subset of tests, you can type `t` or `p` which are explained in the [jest][] watch usage.
Alternatively, you can start the test runner with a [specific file or regular expression](https://facebook.github.io/jest/docs/en/cli.html#jest-regexfortestfiles), like:
- Check out the [getting started](https://flow.org/en/docs/getting-started/) guide.
- Read through the [web-ext guide](https://github.com/mozilla/web-ext/blob/master/CONTRIBUTING.md#check-for-flow-errors) 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.
- We use Flow to **declare 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 magic [Flow declarations](https://flowtype.org/en/docs/config/libs/) for any _internal_ code. Just declare a [type alias](https://flowtype.org/en/docs/types/aliases/) next to the code where it's used and [export/import](https://flow.org/en/docs/types/modules/) 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 like `getAllAddons` takes object arguments, call its type object `GetAllAddonsParams`. Example:
- Use [Exact object types](https://flowtype.org/en/docs/types/objects/#toc-exact-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 a [bug](https://github.com/facebook/flow/issues/2405). You can use the `Exact<T>` workaround from [`src/core/types/util`](https://github.com/mozilla/addons-frontend/blob/master/src/core/types/util.js) if you have to. This is meant as a working replacement for [\$Exact<T>](https://flow.org/en/docs/types/utilities/#toc-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:
- Try to avoid loose types like `Object` or `any` 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 `$FLOW_FIXME` 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 `$FLOW_IGNORE` 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 the `yarn flow type-at-pos ...` command to trace which types are being applied to the code. See `yarn flow -- --help type-at-pos` for details.
We use [Prettier][] to automatically format our JavaScript code and stop all the on-going debates over styles. As a developer, you have to run it (with `yarn prettier-dev`) before submitting a Pull Request.
The wizard allows you to decide whether you want to upgrade dependencies or ignore the issue for 30 days. See the existing reasons to ignore an issue in the [`.snyk`](.snyk) file. Snyk is a bit intrusive and changes many things (like re-adding `snyk test` to the npm `test` script): double check your changes before submitting a Pull Request. You have successfully fixed an issue when `yarn snyk-ci` does not complain. Make sure you open a Pull Request with a branch pushed to this repository and not from your fork, because the `snyk-ci` job (Travis CI) does not run on forks.
Note: You should authenticate yourself once by running `yarn snyk auth` (no dash). It will open a link in your favorite browser and authenticate you locally.
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:
This configures the proxy to use `https://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 a [local API server running in Docker](https://addons-server.readthedocs.io/en/latest/topics/install/index.html), you can use the `yarn amo` command. However, this is currently not working. See [issue-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. See [mozilla/addons-server#4684](https://github.com/mozilla/addons-server/issues/4684) for more information on fixing this.
If you need to override any settings while running `yarn amo`, `yarn amo:dev`, or `yarn amo:stage`, first create a local config file named exactly like this:
Consult the [config file loading order docs](https://github.com/lorenwest/node-config/wiki/Configuration-Files#file-load-order) to learn more about how configuration is applied.
When running `yarn disco`, your local server will be configured for a hosted development API. If you want to run your own [addons-server](https://github.com/mozilla/addons-server) API or make any other local changes, you'll need to create a custom config file named exactly like this:
touch config/local-development-disco.js
Here's what `local-development-disco.js` would look like when overriding the `apiHost` parameter so that it points to your docker container:
### Configuring an Android device for local development
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 address `10.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 at `http://10.0.0.1:3000`.
**NOTE**: At this time, it is not possible to sign in with this configuration because the Firefox Accounts client redirects to `localhost:3000`. You may be able to try a different approach by editing `/etc/hosts` on your device so that `localhost` 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 to `false` in any local config file, such as `local-development-amo.js`. Example:
The documentation you are reading right now lives inside the source repository as [Github flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown). When you make changes to these files you can create a pull request to preview them or, better yet, you can use [grip](https://github.com/joeyespo/grip) to preview the changes locally. After installing `grip`, run it from the source directory like this:
**Note: To run the app locally in production mode you'll need to create a config file for local production builds.** It must be saved as `config/local-prod-amo.js` and should look like:
After this, re-build and restart using `yarn build` and `yarn start` as documented above. If you have used `127.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/.
When implementing user interfaces you will need to refer to the [Sketch](https://www.sketchapp.com/)-based mocks that are hosted on InVision: https://mozilla.invisionapp.com/share/YCCYEOFRH#/screens.
If you need to explore the Sketch source file, you will need a license to run Sketch and you also need to install some fonts (which are free). Install [Fira Sans](https://www.fontsquirrel.com/fonts/fira-sans), [Open Sans](https://www.fontsquirrel.com/fonts/open-sans), [Fira Mono](https://www.fontsquirrel.com/fonts/fira-mono) and [Chivo](https://www.fontsquirrel.com/fonts/chivo).
You can check to see what commit of `addons-frontend` is deployed as well as which A/B experiments are running and which feature flags are enabled by making a request like this:
We've made a conscious decision to avoid "premature modularization" and keep this all in one repository. This will help us build out the necessary tooling to support a universal front-end infrastructure without having to worry about cutting packages and bumping versions the entire time.
