# Newtab Development ## Documentation - Newtab source docs: https://firefox-source-docs.mozilla.org/browser/extensions/newtab/docs/index.html - Design system tokens: https://firefoxux.github.io/firefox-desktop-components/ (visual reference), or locally: `toolkit/themes/shared/design-system/dist/tokens-shared.css` ## File Locations Most of the code should be located in `browser/extensions/newtab` - React components: `browser/extensions/newtab/content-src/components/` - Styles (SCSS): `browser/extensions/newtab/content-src/styles/` (global) and alongside components - Backend feeds: `browser/extensions/newtab/lib/*Feed.sys.mjs` - Redux actions: `browser/extensions/newtab/common/Actions.mjs` - Redux reducers: `browser/extensions/newtab/common/Reducers.sys.mjs` - Tests: `browser/extensions/newtab/test/jest/` (matches source structure) ## Redux Patterns - Action types defined in `common/Actions.mjs` with enum pattern - Action creators use utility functions (ac.AlsoToMain, ac.OnlyToContent, etc.) - Components connect via react-redux `connect()` and functional components connect with the `useSelector()` hook from `react-redux` - Message routing between main/content processes via action metadata (to/from properties) - Always dispatch actions, never mutate state directly ## Development Workflow - Source files: Edit `.jsx`, `.js`, and `.scss` files in `browser/extensions/newtab/content-src/` - Build (front-end only): `./mach build faster` skips C++/Rust compilation — use this for front-end-only changes - The build generates the bundles and CSS into the objdir; no separate bundle step is needed - Bundle only: `./mach newtab bundle` writes the bundles and CSS into the source tree, where they shadow the objdir copies and go stale; see "Bundles left in the source tree" in `docs/index.md` for the cleanup - Watch mode: `./mach newtab watch` for auto-building (invokes npm run watchmc and mach watch); it also writes into the source tree - After making code changes: format with `./mach format path/to/file`, lint with `./mach lint --fix path/to/file`, then build ## Build Output - Pre-rendered HTML: `prerendered/activity-stream.html` - Bundles and CSS: generated by `build-newtab-bundles.py` into the objdir and packaged through `addon-jar.mn` ## Testing - Test framework: Jest + React Testing Library - Run unit tests: `./mach test browser/components/newtab/test/xpcshell && ./mach npm test --prefix=browser/extensions/newtab` - Run browser (mochi) tests: `./mach test browser/components/newtab/test/browser` — you probably want to run with `--headless` - Unit Test files mirror source structure: `test/jest/content-src/components/Card.test.jsx` - Use test utilities from `test/jest/test-utils.jsx` for mocks (`stubGlobals`, `mockServices`, `WrapWithProvider`) ## Train-Hopping Compatibility The newtab extension can ship updates independently of the Firefox release train ("train-hopping") via XPI. This has compatibility implications: - **Trainhoppable**: Only code under `browser/extensions/newtab/` is packaged into the XPI and can train-hop - **Not trainhoppable**: Code in `browser/components/newtab/` always rides the release train (e.g. `AboutNewTabResourceMapping.sys.mjs`) — changes here cannot be ship-fixed via XPI - **External dependencies**: If newtab code depends on platform changes outside `browser/extensions/newtab/` (imported modules, DOM APIs, Nimbus feature definitions), those changes are only available once they reach the Release channel When a change requires a shim for backward compatibility, mark it with: ```js /** * @backward-compat { version 143 } * Explanation of what breaks on older versions and what this shim does. */ ``` The version is when the workaround can be removed (once that Firefox version hits Release). Remove shims once the version reaches Release. **Practical rules:** - Avoid depending on new platform APIs or module paths until they are in Release - New Nimbus feature definitions in `FeatureManifest.yaml` require defensive coding on older channels - If you must depend on an external change, add a `@backward-compat` comment and plan the removal - The `newtabTrainhop` escape hatch in `AboutNewTabChild.sys.mjs` allows overriding the XPI-bundled content with a locally-built version for testing train-hop changes before they ship ### Design tokens Design tokens (`--space-*`, `--color-*`, `--dialog-*` and so on) are defined in `toolkit/themes/shared/design-system/` and ride the release train. A train-hopped New Tab only gets the tokens of the Firefox it runs on, and an undefined token silently drops the declaration (Bug 2080654: dialogs turned transparent on 158 and 159). Custom properties defined under `browser/extensions/newtab/` ship in the XPI and are exempt, but only when every token their value references is also defined there or is on Release: `--x: var(--new-platform-token)` breaks just the same. When you write or review a change under `browser/extensions/newtab/` that adds or changes a `var(--…)` reference (CSS, SCSS, inline styles, a token rename, a regenerated `content-src/styles/nova/_tokens.scss`), check the tokens it references against Release: 1. List the distinct token names on the added or changed lines, including lines that only moved in a regenerated file, and check each name once. Drop names defined under `browser/extensions/newtab/`, but keep the names their values reference. 2. Query them all in one call, with `--space-large` as a control. Keep the quotes, and raise `-l` above the number of names: ``` searchfox-cli -R mozilla-release -r -l 500 "--query=--(space-large|dialog-border-color|dialog-padding):|moz-pref" -p ^toolkit/themes/shared/design-system/dist/tokens- ``` 3. Read the result: - No `--space-large` line, or an error: the query failed. Report the names as unverified on Release rather than guessing. - A match counts only in `tokens-shared.css` or `tokens-brand.css`, above that file's `moz-pref("browser.nova.enabled")` line. Anything below that line is Nova-only, which New Tab doesn't get from the platform. - A name with no counted match that is also missing from the local `toolkit/themes/shared/design-system/dist/tokens-shared.css` doesn't exist at all: flag it as a phantom token, not a train-hop issue. - Any other name with no counted match is newer than Release. Run the same query against `-R mozilla-beta` for those names. 4. For each newer token, either use a token that is on Release, or fall back to the one its definition on main aliases and mark it: ```scss // @backward-compat { version 160 } border-radius: var(--dialog-border-radius, var(--popup-border-radius)); ``` The version is the first Firefox that ships the token: the Release version plus 1 if Beta has it, plus 2 if only main does. Read the Release version from `searchfox-cli -R mozilla-release --get-file browser/config/version.txt`, since a local checkout may be behind. ## Nova CSS - Nova-specific CSS must be scoped under `.nova-enabled` — the CSS file switcher has been removed. Flag any nova styles not behind this class. ## Glean Metrics - Metric definitions live in `browser/components/newtab/metrics.yaml` and `browser/components/newtab/pings.yaml`. - **Pings**: Newtab uses two pings: - `newtab` — session-level data, sent on `newtab_session_end` or `component_init` - `newtab-content` — private instrumentation sent over OHTTP without a client ID - **Schema changes are not trainhoppable** — renaming, removing, or changing the type of an existing metric rides the release train and cannot be ship-fixed via XPI - Glean supports runtime registration (new metrics). Whenever you touch either file, generate and commit the channel diff files: - `./mach newtab channel-metrics-diff --channel beta` - `./mach newtab channel-metrics-diff --channel release` - This writes `runtime-metrics-N.json` files to `browser/extensions/newtab/webext-glue/metrics/`. Delete any files for versions no longer supported on the Release channel. --- ## Configuration Files - `webpack.system-addon.config.js` - Webpack bundling config - `jest.config.mjs` - Unit test runner configuration - `yamscripts.yml` - npm script definitions (compile with `npm run yamscripts`) - `.eslintrc.mjs` - ESLint configuration