desktop Documentation

Technical Documentation: zen-browser/desktop

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

`Zen Browser` Copy Section

Zen is a firefox-based browser with the aim of pushing your productivity to a new level!

Firefox Versions Copy Section

• Release - Is currently built using Firefox version 157.0.1!
• Twilight - Is currently built using Firefox version RC 158.0!

Contributing Copy Section

If you'd like to report a bug, please do so on our GitHub Issues page and for feature requests, you can use GitHub Discussions.

Zen is an open-source project, and we welcome contributions from the community! Please take a look at the contribution guidelines before getting started!

Partners

Thanks to all the partners of Zen for their support and contributions:

Overview (`prefs/README.md`) Copy Section

Browser Preferences

This directory contains configuration files for Zen. They are divided by folder according to the source / component they belong to and further divided by file according to their purpose.

• firefox/: Preferences to override Firefox defaults.
• zen/: Preferences to configure Zen-specific features.
• privatefox/ & fastfox/: Some of the preferences got extracted from Betterfox.

Overview (`src/external-patches/firefox/README.md`) Copy Section

Temporal patches done to Firefox

IMPORTANT: Once they start failing (on new Firefox releases), they should be removed as these patches are imported from future versions of Firefox as temporary solutions while we wait.

Overview (`src/external-patches/librewolf/README.md`) Copy Section

Patches imported from LibreWolf

Firefox sometimes makes changes without considering the impact on forks. This is the case of the patches that are imported from LibreWolf, which are already present in LibreWolf but not yet (or never) present in Firefox. Thanks to LibreWolf for making these patches available and for their work in maintaining them. We will keep these patches as long as they are needed, and we will remove them once they are no longer necessary (for example, when they are merged into Firefox or when the issue they solve is no longer present).

Overview (`src/browser/components/newtab/README.md`) Copy Section

Checkout this documentation to build new tab assets

• New Tab Documentation
• You also need [email protected] (that's the one I tested) because other versions might not work.
• To bundle the new tab, execute the following command:

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

Contribute (`docs/contribute.md`) Copy Section

Branch Structure

The repository is structured as follows:

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

The dev branch is the main branch of the repository, and it is the default branch for the repository. The twilight branch is the feature branch, and it is branched off from the dev branch. The stable branch is the release branch, and it is branched off from the dev branch.

The stable branch may have hotfixes directly from the stable branch, and the twilight branch may have feature branches branched off from the twilight branch. This is done so that we can apply hotfixes like security patches directly to the stable branch without having to merge the changes from the twilight branch.

Local Development Setup

Before you set up your local development environment, read our Building Guidelines. Skipping them can lead to avoidable build errors.

Code Of Conduct

Please read our Code of Conduct before contributing.

Live Folders Specs (`docs/live-folders-specs.md`) Copy Section

Zen Live Folders - Specification

Overview Copy Chapter

Live Folders are dynamic, auto-updating folders in Zen.
Unlike static folders, they fetch and refresh their contents automatically from external sources (e.g., RSS feeds, APIs).
By default, Live Folders refresh every 30 minutes, but this interval can be configured in preferences.

Architecture Copy Chapter

`LiveFolderProvider` Copy Section

• Abstract base class for all live folder implementations.
• Defines the contract for fetching and updating live folder contents.
• Responsibilities:
  • Define how to fetch items (abstract method fetchItems()).
  • Handle update intervals (default: 30 min).
  • Manage serialization/deserialization of folder state (cache, last update time).
  • Provide metadata (icon, label, description).

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

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

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

Implementations Copy Section

`RssLiveFolderProvider`

• Description: Updates live folder contents from an RSS/Atom feed.
• Configuration:
  • url: URL of the RSS feed.

`GithubLiveFolderProvider`

• Description: Updates live folder contents from GitHub user's Pull Requests.
• Configuration:
  • username: GitHub username.

`RestAPILiveFolderProvider`

• Description: Updates live folder contents from a REST API endpoint.
• Configuration:
  • schema: JSON schema to validate API responses.

Possible future implementations

• WebhookLiveFolderProvider

REST API Live Folder Schema

Overview Copy Chapter

REST-based Live Folders allow Zen to fetch JSON data from an HTTP(S) endpoint and map it into folder items.
Each REST Live Folder must provide a schema-compliant response that Zen can parse into items.

• Remote APIs (https://, http://): Flexible schema (mapping via config).
• Localhost APIs (http://127.0.0.1, http://localhost): Must strictly follow Zen’s Local REST Schema for security and consistency.

Common Rules Copy Chapter

• Requests are always GET.
• Responses must be JSON.
• CORS headers are ignored (Zen fetches internally).
• Max response size: 1 MB (to prevent abuse).
• Items exceeding liveFolder.maxItems (default 100) will be trimmed.

Remote REST Schema Copy Chapter

Remote APIs can return any JSON, but the Live Folder must provide a mapping configuration:

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

Installation of REST API Live Folder Copy Section

These schemas would be stored inside a marketplace on Zen's web platform, allowing users to easily discover and integrate new REST API Live Folders into their workspace.

If the user wants to create a new REST API Live Folder, they can do so by providing the necessary schema and configuration through the marketplace interface. This will enable them to customize the folder's behavior and data mapping according to their specific needs.

If it's a custom API and the schema is not publicly available, users can still create a Live Folder by defining their own mapping configuration. This allows them to integrate with proprietary APIs while adhering to Zen's Live Folder standards. This mapping configuration will be fetched via https://example.com/zen-live-folder.schema.json.

Issue Metrics 2024 2024 11 01..2024 11 30 (`docs/issue-metrics/2024_2024-11-01..2024-11-30.md`) Copy Section

Issue Metrics

This report was generated with the Issue Metrics Action
Search query used to find these items: repo:zen-browser/desktop is:issue created:2024-11-01..2024-11-30

Issue Metrics 2024 2024 12 01..2024 12 31 (`docs/issue-metrics/2024_2024-12-01..2024-12-31.md`) Copy Section

Issue Metrics

This report was generated with the Issue Metrics Action
Search query used to find these items: repo:zen-browser/desktop is:issue created:2024-12-01..2024-12-31

Issue Metrics 2025 2025 01 01..2025 01 31 (`docs/issue-metrics/2025_2025-01-01..2025-01-31.md`) Copy Section

Issue Metrics