# Firefox Home (New Tab)

All files related to Firefox Home, which includes content that appears on `about:home` and
`about:newtab`, can be found in the `browser/extensions/newtab` directory.
Some of these source files (such as `.js`, `.jsx`, and `.scss`) require an additional build step.
We are working on migrating this to work with `mach`, but in the meantime, please
follow the following steps if you need to make changes in this directory:

## For `.sys.mjs` files (system modules)

No build step is necessary. Use `mach` and run mochitests according to your regular Firefox workflow.

## For `.js`, `.jsx`, `.scss`, or `.css` files

### Prerequisites

You will need the following:

- Node.js 10+ (On Mac, the best way to install Node.js is to use the install link on the [Node.js homepage])
- npm (packaged with Node.js)

To install node dependencies, run the following from the root of the mozilla-central repository.
(This command uses `mach` to call `npm` and `node` commands to ensure the correct versions of Node and npm are being referenced.)

```shell
./mach newtab install
```

**IMPORTANT NOTE**: If you're using Windows, you may need to run the install command differently:

```shell
(cd browser/extensions/newtab && ../../../mach npm install)
```

### Which files should you edit?

You should not make changes to `.js` or `.css` files in `browser/extensions/newtab/css` or
`browser/extensions/newtab/data` directory. Instead, you should edit the `.jsx`, `.js`, and `.scss` source files
in `browser/extensions/newtab/content-src` directory. These files will be compiled into the `.js` and `.css` files.

## Building assets and running Firefox

To build assets and run Firefox, run the following from the root of the mozilla-central repository:

```shell
./mach newtab bundle && ./mach build && ./mach run
```

## Continuous development / debugging

For near real-time reloading, run the following commands in **two separate terminals** to automatically rebuild bundled files whenever JSX or SCSS files change. After making a change, [restart your local instance](/devtools-user/browser_console/index.html#controlling-the-browser) to apply the updates. Run the following terminal commands:

```shell
./mach newtab watch
```

```shell
./mach run
```

**IMPORTANT NOTE**: This task will add inline source maps to help with debugging, which changes the memory footprint. Do not use the `watch` task for profiling or performance testing! After finishing your work, **be sure to stop the watch process**. When stopped, it will automatically run a final bundle step to remove the temporary inline source maps.

## Pre-commit git hook

A pre-commit hook is available in `tools/lint/hooks_newtab.py`. When installed,
it runs the following checks in order, stopping at the first failure:

1. **Bundle** — if newtab source or bundle output files are staged, runs
   `./mach newtab bundle` and blocks the commit if the output files differ
   from what is staged.
2. **Lint** — runs [mozlint](https://firefox-source-docs.mozilla.org/code-quality/lint/usage.html)
   on staged files and blocks the commit if there are errors.
3. **Tests** — optionally runs unit tests (configurable, disabled by default).

To install the hook, run the following from the root of the mozilla-central repository:

```shell
ln -sf "$(git rev-parse --show-toplevel)/tools/lint/hooks_newtab.py" \
       "$(git rev-parse --show-toplevel)/.git/hooks/pre-commit"
```

By default, no tests are run on commit. To configure which tests run, use
`git config newtab.pre-commit.tests` with one of the following values:

```shell
git config newtab.pre-commit.tests jest       # Jest only (~30 seconds)
git config newtab.pre-commit.tests jest-karma # Jest + Karma/Enzyme (~3-5 minutes)
git config newtab.pre-commit.tests all        # all tests including xpcshell and browser (10+ minutes)
git config newtab.pre-commit.tests none       # skip tests (default)
```

To commit despite failing tests, use `git commit --no-verify` to bypass the hook entirely.

## Running tests

The majority of New Tab / Messaging unit tests are written using
[mocha](https://mochajs.org), and other errors that may show up there are
[SCSS](https://sass-lang.com/documentation/syntax) issues flagged by
[stylelint](https://stylelint.io). These things are all run using
`npm test` under the `newtab` slug in Treeherder/Try, so if that slug turns
red, these tests are what is failing. To execute them, do this:

```shell
./mach npm test --prefix=browser/extensions/newtab
```

These tests are not currently run by `mach test`, but there's a
[task filed to fix that](https://bugzilla.mozilla.org/show_bug.cgi?id=1581165).

Windows isn't currently supported by `npm test`
([path/invocation difference](https://bugzilla.mozilla.org/show_bug.cgi?id=1737419)).
To run newtab specific tests that aren't covered by `mach lint` and
`mach test`:

```shell
./mach npm run lint:stylelint --prefix=browser/extensions/newtab
./mach npm run testmc:build --prefix=browser/extensions/newtab
./mach npm run testmc:unit --prefix=browser/extensions/newtab
```

Mochitests and xpcshell tests run normally, using `mach test`.

## Code Coverage

Our testing setup will run code coverage tools in addition to just the unit
tests. It will error out if the code coverage metrics don't meet certain thresholds.

If you see any missing test coverage, you can inspect the coverage report by
running

```shell
./mach npm test --prefix=browser/extensions/newtab &&
./mach npm run debugcoverage --prefix=browser/extensions/newtab
```

## Discovery Stream Developer tools

You can access the developer tools for the Discovery Stream components of <about:newtab> by
visiting `about:config` and setting `browser.newtabpage.activity-stream.asrouter.devtoolsEnabled`
to `true`.

Then, go to any `about:newtab` page and click on the wrench icon in the top-right corner.

## Detailed Docs

```{toctree}
:glob: true
:titlesonly: true

v2-system-addon/*
```

[node.js homepage]: https://nodejs.org/
