Firefox Desktop

The Firefox Desktop browser is the primary product built from this tree. The chrome (browser UI) lives in browser/ with shared infrastructure in toolkit/. It runs on Linux, macOS, and Windows.

Purpose

Firefox Desktop is a multi-process browser whose chrome is implemented in JavaScript + HTML/XUL hybrid documents, running in the parent process. The web content runs in dozens of sandboxed content processes (Fission). The chrome is itself a xul:browser element hosting privileged HTML, with custom elements for tabs, sidebar, address bar, and panels.

Directory layout

browser/
├── app/              # Application entry points, packaging
├── actors/           # JSWindowActor implementations for browser features
├── base/             # Core browser chrome: tabbrowser, browser.js, browser.xhtml
├── components/       # Sub-features grouped as components (urlbar, places, sessionstore, ...)
├── extensions/       # Built-in WebExtensions (e.g., webcompat, formautofill)
├── fxr/              # Firefox Reality (legacy)
├── installer/        # Per-platform installers (Windows/macOS/Linux)
├── locales/          # English source strings (other locales come from l10n repos)
├── modules/          # Shared JS modules (.sys.mjs)
├── themes/           # Default theme assets
└── tools/            # Browser-specific dev tools

toolkit/                       # Shared between desktop and other Gecko apps
├── components/                # Shared components (telemetry, Glean, Places, Search, etc.)
├── content/                   # Shared chrome content (widgets, common dialogs)
├── modules/                   # Shared JS modules
├── mozapps/                   # App-level features: extensions UI, update, profile manager
├── crashreporter/             # Crash reporter client
├── library/                   # libxul.so / xul.dll links here
├── moz.build
└── ...

Key entry points

Path	Role
browser/app/firefox.exe.manifest	Windows app manifest
browser/app/macbuild/	macOS app bundle structure
browser/base/content/browser.xhtml	The main browser window markup
browser/base/content/browser.js	The startup script for each browser window
browser/components/sessionstore/	Save/restore tab state
browser/components/urlbar/	Address bar (Quantum Bar)
browser/components/places/	Bookmarks, history UI
browser/components/newtab/	New-tab page (Pocket integration etc.)
toolkit/components/extensions/	WebExtensions runtime
toolkit/mozapps/extensions/	about:addons UI, AddonManager

Browser chrome architecture

graph TD
    BrowserXHTML[browser.xhtml] --> Tabbrowser[tabbrowser-tabs / tabbrowser]
    Tabbrowser --> XulBrowser["<xul:browser>"]
    XulBrowser -->|hosts| ContentDoc[Content document<br/>in content process]
    BrowserXHTML --> Urlbar[urlbar Custom Element]
    BrowserXHTML --> Sidebar[Sidebar]
    BrowserXHTML --> Toolbar[Customizable toolbar]
    Urlbar --> UrlbarController[UrlbarController.sys.mjs]
    UrlbarController --> Providers[UrlbarProvider* sources]
    BrowserXHTML --> Actors[JSWindowActor<br/>per-document IPC]

The browser uses JSWindowActors (dom/ipc/JSActor.cpp) to communicate between the chrome (parent process) and the content (child process). Actor pairs are registered in BrowserGlue.sys.mjs and similar files; they replace the older messageManager API.

Components worth knowing

• Urlbar / Quantum Bar — multi-source address bar with autocomplete, search engines, suggestions. Uses an extensible UrlbarProvider* model. See browser/components/urlbar/.
• Places — SQLite-backed bookmarks/history, in toolkit/components/places/. The schema is in Database.cpp. The query language is places:// URIs.
• Session Store — saves and restores tabs across restarts. Persists JSON to the profile.
• New Tab (newtab) — React-based page; fetches stories from Pocket-style endpoints.
• Search — search engine plumbing via toolkit/components/search/.
• Form Autofill — built-in WebExtension under browser/extensions/formautofill/.
• WebCompat — built-in WebExtension that fixes site-specific compatibility issues. browser/extensions/webcompat/.

Building and running

./mach build
./mach run

For chrome-only iteration:

./mach build faster
./mach run

For artifact builds (download prebuilt platform binaries, build only chrome):

echo "ac_add_options --enable-artifact-builds" >> .mozconfig
./mach build
./mach run

Related

• Process model
• Toolkit components
• WebExtensions
• DevTools (via the same engine; see also systems/devtools.md)