addons-frontend/README.md

[![Build Status](https://travis-ci.org/mozilla/addons-frontend.svg?branch=master)](https://travis-ci.org/mozilla/addons-frontend)
[![Coverage Status](https://coveralls.io/repos/github/mozilla/addons-frontend/badge.svg?branch=master)](https://coveralls.io/github/mozilla/addons-frontend?branch=master)

[Documentation](http://addons-frontend.readthedocs.io/en/latest/)

# Addons-frontend 🔥

Front-end infrastructure and code to complement
[mozilla/addons-server](https://github.com/mozilla/addons-server).

## Security Bug Reports

This code and it’s 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].

Please submit all security-related bugs through Bugzilla using the [web security bug form].

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

  [bug bounty program]: https://www.mozilla.org/en-US/security/web-bug-bounty/
  [FAQ pages]: https://www.mozilla.org/en-US/security/bug-bounty/faq-webapp/
  [Bug Bounty Onramp page]: https://wiki.mozilla.org/Security/BugBountyOnramp/
  [web security bug form]: https://bugzilla.mozilla.org/form.web.bounty

## Requirements

* Node 4.x LTS
* npm 3.x

The easiest way to manage multiple node versions in development is to use
[nvm](https://github.com/creationix/nvm).

## Get started

* npm install
* npm run dev


## NPM scripts for development

Generic scripts that don't need env vars. Use these for development:

| Script                  | Description                                           |
|-------------------------|-------------------------------------------------------|
| npm run dev:admin       |  Starts the dev server (admin app)                    |
| npm run dev:amo         |  Starts the dev server (amo)                          |
| npm run dev:disco       |  Starts the dev server (discovery pane)               |
| npm run eslint          |  Lints the JS                                         |
| npm run stylelint       |  Lints the SCSS                                       |
| npm run lint            |  Runs all the JS + SCSS linters                       |
| npm run version-check   |  Checks you have the minimum node + npm versions      |
| npm test                |  Runs the unittest, servertests + lint                |
| npm run unittest        |  Runs just the unittests                              |
| npm run unittest:dev    |  Runs the unittests and watches for changes           |
| npm run unittest:server |  Starts a unittest server for use with `unittest:run` |
| npm run unittest:run    |  Executes unittests (requires `unittest:server`)      |
| npm run servertest      |  Runs the servertests                                 |

### Running tests

You can run the entire test suite with `npm test` but there are a few other ways
to run tests.

#### Run all unit tests in a loop

You can use `npm run unittest:dev` to run all unit tests in a loop while you
edit the source code.

#### Run a subset of the unit tests

If you don't want to run the entire unit test suite, first you have to start a
unittest server:

    npm run unittest:server

When you see "Connected on socket," the server has fully started.

Now you can execute a more specific [mocha](https://mochajs.org/) command,
such as using `--grep` to run only a few tests. Here is an example:

    npm run unittest:run -- --grep=InfoDialog

This would run all tests that either fall under the `InfoDialog` description grouping
or have `InfoDialog` in their behavior text.

Any option after the double dash (`--`) gets sent to `mocha`. Check out
[mocha's usage](https://mochajs.org/#usage) for ideas.

### Code coverage

The `npm run unittest` command generates a report of how well the unit tests
covered each line of source code.
The continuous integration process will give you a link to view the report.
To see this report while running tests locally, type:

    open ./coverage/index.html

### Configuring for local development

The `dev` scripts above will connect to a hosted development API by default.
If you want to run your own
[addons-server](https://github.com/mozilla/addons-server)
API or make any other local changes, just add a local configuration
file for each app. For example, to run your own discovery pane API, first create
a local config file:

    touch config/local-development-disco.js

Be sure to prefix the file with **local-development-** so that it doesn't pollute the
test suite.
Here's what `local-development-disco.js` would look like when
overriding the `apiHost` parameter so that it points to your docker container:

````javascript
module.exports = {
  apiHost: 'http://olympia.dev',
};
````

When you start up your front-end discover pane server, it will now apply
overrides from your local configuration file:

    npm run dev:disco

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.

### Building and running services

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_APP_INSTANCE` this is the name of the app e.g. 'disco'
`NODE_ENV` this is the node environment. e.g. production, dev, stage, development.

| Script                 | Description                                         |
|------------------------|-----------------------------------------------------|
| npm run start          |  Starts the express server (requires env vars)      |
| npm run build          |  Builds the libs (all apps) (requires env vars)     |

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

```
NODE_APP_INSTANCE=admin NODE_ENV=production npm run build && npm run start
```

## Overview and rationale

This project will hold distinct front-ends e.g:

* Editors' admin/search tool
* Discovery Pane
* and beyond...

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.

At a later date if we need to move things out into their own project we
still can.

## Core technologies

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