Zen Browser Documentation

Zen Browser configuration files are organized by their source or component. When looking for specific preference overrides, navigate the directory structure based on the following categories:

• firefox/: Contains preferences used to override default Firefox behaviors.
• zen/: Contains preferences specifically for configuring Zen-unique features.
• privatefox/ & fastfox/: Contains a subset of preferences extracted from the Betterfox project for specialized browsing profiles.

Zen Browser provides two main build tracks based on Firefox versions:

• Release: The stable build. Currently built using Firefox version 153.0.3.
• Twilight: An experimental/preview build. Currently built using Firefox version RC 153.0.3.

You can download these specific versions at zen-browser.app/download (use the ?twilight query parameter for the Twilight build).

The repository uses a specific branching model to manage features and releases:

• dev (main branch): The primary development branch and the default branch for the repository.
• stable: The release branch, branched off from dev. It receives hotfixes (such as security patches) directly to avoid including unfinished features from other branches.
• twilight: A feature branch branched off from dev.
• features branches: Can be branched off from twilight or dev depending on the scope.

This structure allows for applying critical patches to stable without being blocked by ongoing work in twilight or dev.

dev (main branch)
 | |
 | \--->-- stable (release branch)
 |   ^
 ^   |
 |   \-<- Hotfix (hotfixes directly from stable)
 |
 \-<- (features branches)

The src/external-patches/firefox/ directory contains temporal patches applied to Firefox. These patches are imported from future Firefox versions to serve as temporary solutions.

Critical Maintenance Rule: If these patches begin failing during new Firefox releases, they must be removed immediately. They are not intended to be permanent parts of the codebase and should only exist while waiting for official Firefox updates to include the relevant fixes.

The LiveFolderProvider is the abstract base class for all live folder implementations. It defines the contract for fetching items, managing update intervals, handling state serialization (cache and last update time), and providing metadata like icons and labels.

Developers implementing a new provider must satisfy the following interface:

interface FolderItem {
  id: string;
  title: string;
  url: string;
}

interface FolderMetadata {
  icon: string;
  label: string;
}

interface LiveFolderProvider {
  fetchItems(): Promise<FolderItem[]>;
  getMetadata(): FolderMetadata;
}

REST-based Live Folders fetch JSON data from an HTTP(S) endpoint and map it into folder items.

Remote APIs

For remote endpoints (https:// or http://), you can use a mapping configuration to tell Zen how to extract data from the JSON response.

Localhost APIs

For local endpoints (http://127.0.0.1 or http://localhost), the response must strictly follow Zen's Local REST Schema for security and consistency.

Common Rules

• All requests are GET.
• Responses must be JSON.
• CORS headers are ignored (Zen performs the fetch internally).
• Max response size is 1 MB.
• Items exceeding liveFolder.maxItems (default 100) will be automatically trimmed.

{
  "type": "rest",
  "url": "https://api.example.com/posts",
  "mapping": {
    "items": "data.posts",
    "id": "id",
    "title": "headline",
    "url": "link"
  }
}

Zen is a Firefox-based browser designed for productivity. You can download the browser, visit the official website, access documentation, or view the latest release notes via the following links:

• Download: zen-browser.app/download
• Website: zen-browser.app
• Documentation: docs.zen-browser.app
• Release Notes: zen-browser.app/release-notes/latest

To bundle the new tab assets, you must use meow@9.0.0 as other versions may be incompatible. Execute the following command from the repository root to trigger the bundling process for the new tab component.

./mach npm run bundle --prefix=browser/components/newtab

To interact with the Zen Browser development process:

• Report a bug: Use the GitHub Issues page.
• Request a feature: Use GitHub Discussions.
• Contribute code: Zen is open-source. Before contributing, review the contribution guidelines.

Before attempting to set up your local development environment, you must follow the official Building Guidelines to prevent avoidable build errors.

Refer to the Building Guidelines for the complete setup and compilation process.