brave-browser vs brave-core: Understanding the Brave Build System Architecture

The brave-browser repository serves as the build harness that orchestrates Chromium downloads and compilation, while brave-core contains the actual Brave browser code and patches, living as a git submodule at src/brave/.

Understanding the relationship between brave-browser vs brave-core is essential for anyone building Brave from source. The brave/brave-browser repository acts as the outer wrapper that manages dependencies and build orchestration, while brave/brave-core houses the product-specific features, UI components, ad-block engines, and the patches that customize Chromium. This separation allows the build system to cleanly manage the massive Chromium base while maintaining Brave's distinct functionality.

What Is brave-browser?

The brave-browser repository is the build orchestration layer. It contains no browser source code itself; instead, it holds the scripts and configuration needed to fetch Chromium, apply patches, and compile the final binary.

Key responsibilities include:

• Build orchestration: Defines npm scripts in package.json that drive the entire compilation process.
• Dependency management: Specifies which external projects are needed (Chromium and brave-core) via package.json and src/brave/DEPS.
• Patch application: Manages the workflow for applying Brave-specific patches to the Chromium source.
• Chromium download: Handles fetching the correct Chromium revision via depot_tools and gclient.

According to the repository's README.md, brave-browser "fetches and syncs code from the projects defined in package.json and src/brave/DEPS" and mounts brave-core at src/brave.

What Is brave-core?

The brave-core repository contains the actual Brave source code—the UI, ad-block engine, rewards system, and the set of patches applied to Chromium. It lives as a git submodule inside the brave-browser checkout.

Key characteristics include:

• Submodule location: Checked out under src/brave/ inside the brave-browser directory structure.
• Product code: Houses all Brave-specific functionality including UI components, Brave Rewards, Brave Shields, and the ad-block library.
• Patch definitions: Maintains the src/brave/DEPS file that lists the exact Chromium revision and other dependencies required.
• Build configuration: Contains build scripts in src/brave/build/ that configure the GN/Ninja build system on top of Chromium's infrastructure.

The CONTRIBUTING.md file in brave-browser clarifies that there are "two repositories: the root (brave-browser) and the sub-module (brave-core) located under src/brave".

How brave-browser and brave-core Work Together

The separation between brave-browser and brave-core creates a clean build pipeline where the wrapper manages dependencies and the submodule provides the product code.

Repository Initialization

When you first clone brave-browser, you receive only the build harness. Running npm run init triggers the following sequence:

1. Chromium fetch: Uses depot_tools and gclient to download the Chromium source tree.
2. Submodule setup: Creates the src/brave directory and clones the brave-core repository as a git submodule.
3. Dependency sync: Processes the src/brave/DEPS file to ensure all transitive dependencies match the required versions.
4. Patch application: Applies the Brave-specific patch set to the Chromium source code.

The Build Workflow

Once initialized, the build process flows between the two repositories:

• Command entry: Developers run commands like npm run sync or npm run build from the brave-browser root.
• Synchronization: The npm run sync -- --init command re-syncs the src/brave submodule to the configured ref, reapplies patches, and updates DEPS.
• Compilation: The npm run build command starts a component build (default Debug) of the Chromium source with Brave patches applied.
• Testing: Unit tests for brave-core JavaScript code are executed via cd src/brave && npm run test-unit.

Essential Commands and File Paths

Understanding the specific files and commands clarifies the division of responsibilities between the two repositories.

Key Configuration Files

File	Repository	Purpose
package.json	brave-browser	Defines npm scripts (init, sync, build) and top-level dependencies.
README.md	brave-browser	Documents that brave-core is "mounted at src/brave" and explains the fetch/sync process.
CONTRIBUTING.md	brave-browser	Clarifies the two-repository structure: root (brave-browser) and sub-module (brave-core at src/brave).
src/brave/DEPS	brave-core	Lists the exact Chromium revision and other dependencies; acts as the bridge telling brave-browser which Chromium version to pull.
src/brave/build/*	brave-core	Contains GN/Ninja build configuration scripts applied on top of Chromium's build system.

Common Build Commands

Goal	Command	Context
Initialise the whole source tree	npm run init	Run from brave-browser root; downloads Chromium, checks out brave-core, applies patches.
Update Chromium and brave-core	npm run sync -- --init	Re-syncs src/brave to the configured ref, reapplies patches, updates DEPS.
Build a debug component	npm run build	Starts a component build (default Debug) of Chromium with Brave patches.
Run brave-core JS unit tests	cd src/brave && npm run test-unit	Executes the JavaScript test suite inside the brave-core checkout.
Re-apply patches only	cd src/brave && npm run apply_patches	Re-applies Brave patches without re-downloading Chromium; useful after git pull.

Summary

• brave-browser acts as the build harness and orchestration layer, managing Chromium downloads, dependency synchronization, and the compilation pipeline through npm scripts defined in package.json.
• brave-core contains the actual product code—including UI components, Brave Rewards, Shields, and ad-block functionality—plus the patches that customize Chromium, living as a git submodule at src/brave.
• The src/brave/DEPS file inside brave-core specifies the exact Chromium revision, creating the bridge between the two repositories.
• Developers interact primarily with brave-browser commands (npm run init, npm run sync, npm run build) while editing code in either repository depending on whether they are modifying build logic or browser features.

Frequently Asked Questions

Is brave-core a separate repository?

Yes, brave-core is a separate Git repository hosted at https://github.com/brave/brave-core. It is integrated into the brave-browser repository as a git submodule checked out under the src/brave/ directory. This separation allows the core browser code to evolve independently while the build harness remains stable.

Why does Brave use two repositories instead of one?

The two-repository architecture separates concerns: brave-browser handles the complex orchestration of downloading Chromium (several gigabytes of source) and managing the build toolchain, while brave-core contains only Brave-specific code and patches. This prevents the massive Chromium history from polluting the product code repository and allows developers to work on Brave features without needing to sync the entire Chromium tree.

Where are the Chromium patches stored?

Chromium patches are stored within the brave-core repository, specifically in the src/brave/ directory structure. The src/brave/DEPS file lists dependencies and patch locations, while the src/brave/build/ directory contains scripts that configure how these patches are applied to the Chromium source during the build process. You can re-apply patches manually by running npm run apply_patches from within the src/brave directory.

Can I build brave-core without brave-browser?

No, you cannot build brave-core in isolation because it depends on the Chromium source code and build toolchain that brave-browser orchestrates. The brave-browser repository contains the npm scripts and gclient configuration necessary to download Chromium, sync the brave-core submodule, and apply patches. Without this harness, brave-core lacks the underlying Chromium headers and build system required for compilation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}