How Brave Browser Integrates Chromium and brave-core: A Technical Deep Dive

Brave Browser integrates Chromium and brave-core by using a DEPS file and the gclient dependency manager to pin specific revisions of both repositories into a unified source tree, then applies Brave-specific patches and builds the final binary using GN and Ninja.

Understanding how Brave Browser integrates Chromium and brave-core is essential for developers looking to contribute to the browser or fork it for custom builds. The brave/brave-browser repository does not contain the actual browser source code; instead, it serves as a build orchestration layer that pulls together the Chromium engine and Brave's proprietary features through a sophisticated dependency management system.

Repository Architecture Overview

The integration relies on a separation of concerns between three distinct components, each managed through automated synchronization tools.

The brave-browser Repository

The brave/brave-browser repository contains only build scripts, configuration files, and patch sets. It acts as the entry point for developers, providing npm-based commands that abstract the underlying complexity of Chromium's build ecosystem. Key files include package.json, which defines the npm run sync and npm run build commands, and the patches/ directory containing .patch files that modify Chromium behavior.

brave-core and Chromium Sources

The actual source code resides in two external repositories:

• Chromium: Pulled from https://chromium.googlesource.com/chromium/src, providing the Blink rendering engine, V8 JavaScript runtime, and networking stack.
• brave-core: Pulled from https://github.com/brave/brave-core, containing Brave-specific implementations including Shields, Brave Rewards, the built-in ad-blocker, and Rust-based privacy components.

Dependency Management with DEPS and gclient

The technical integration centers on a DEPS file located at src/brave/DEPS within the brave-browser checkout. This file declares the exact Git revisions (commit hashes) for both Chromium and brave-core that should be used for a given build, ensuring reproducible builds across different environments.

The gclient tool, which is part of Chromium's depot_tools, processes this DEPS file. When executed, gclient sync creates a unified source tree with the following structure:

src/
 ├─ brave/          ← brave-core checkout (Brave-specific code)
 └─ third_party/
      └─ chromium/  ← Chromium source

This approach allows Brave to maintain a single source tree where Chromium and brave-core code can reference each other directly during compilation, enabling tight integration between the engine and Brave's privacy features.

The Sync Workflow: npm run sync

Developers initiate the integration process using npm commands defined in package.json. Running npm run sync (or npm run sync -- --init for a fresh checkout) executes a script that performs four critical operations:

1. Downloads sub-projects: Uses gclient sync to fetch the specific Chromium and brave-core revisions defined in src/brave/DEPS.
2. Applies Brave-specific patches: Iterates through the patches/ directory, applying .patch files to modify Chromium source files where direct modification isn't feasible.
3. Updates child dependencies: Installs Rust crates, npm modules, and other secondary dependencies required by brave-core.
4. Runs initialization hooks: Executes post-sync scripts such as npm install within the pulled repositories to prepare the build environment.

# Clone the build orchestration repository

git clone https://github.com/brave/brave-browser.git
cd brave-browser

# Fetch Chromium and brave-core, apply patches, install dependencies

npm run sync -- --init

# Build a debug component (fastest for development)

npm run build -- Debug

# Launch the built browser

npm start Component

Build Process Integration

Once synchronization completes, Brave uses Chromium's standard build system—GN (Generate Ninja) and Ninja—to compile the browser. The integration works by merging Brave's build configuration with Chromium's:

• GN Templates: Brave adds its own .gn and .gni files within src/brave that define how Brave-specific targets (like the Rewards service or Shields UI) should be built.
• Source Merging: The build graph includes source files from both src/brave (brave-core) and the Chromium tree, allowing Brave components to link against Chromium's base libraries.
• Patch Integration: Changes applied via the patches/ directory modify Chromium's build files where necessary to include Brave targets in the final binary.

Because Chromium is built from source rather than linked as a precompiled library, all Brave modifications compile directly into the engine. This ensures tight integration and performance parity with Google Chrome while maintaining Brave's privacy-focused feature set.

Why This Integration Approach?

Brave's architecture provides several technical advantages for maintaining a Chromium-based browser:

• Precise Version Pinning: The DEPS file creates reproducible builds by locking Chromium and brave-core to specific commits, preventing "works on my machine" issues.
• Upstream Tooling Compatibility: By using gclient, GN, and Ninja, Brave leverages Chromium's existing infrastructure for code review, continuous integration, and security auditing.
• Modular Modifications: Keeping Brave-specific code in brave-core and using patch files for minor Chromium tweaks makes it easier to rebase onto new Chromium versions and contribute changes upstream.

Summary

• Brave Browser integrates Chromium and brave-core using a DEPS file at src/brave/DEPS and the gclient dependency manager to create a unified source tree.
• The npm run sync command orchestrates downloading specific revisions of both repositories, applying patches from the patches/ directory, and installing dependencies.
• The build process uses standard Chromium tooling (GN and Ninja) to compile both engines together, ensuring tight integration and performance parity with Chrome.
• This architecture allows Brave to maintain precise version control, leverage upstream Chromium infrastructure, and modularize its privacy-focused features.

Frequently Asked Questions

What is the difference between brave-browser and brave-core?

The brave-browser repository contains build scripts, configuration files, and patch sets that orchestrate the build process but contains no browser source code. The brave-core repository contains the actual C++, Rust, and JavaScript implementation of Brave-specific features like Shields, Rewards, and the ad-blocker. brave-core is pulled in as a dependency during the npm run sync process.

How does Brave keep Chromium up to date?

Brave maintains a DEPS file at src/brave/DEPS that specifies the exact Git revision (commit hash) of Chromium to use. When Brave engineers want to update the underlying engine, they modify this file to point to a newer Chromium commit, then run the sync and build process to verify compatibility. This approach allows Brave to rebase its patches and brave-core code onto new Chromium versions in a controlled, reproducible manner.

What build system does Brave Browser use?

Brave uses the same build system as Chromium: GN (Generate Ninja) for build configuration and Ninja for actual compilation. The build process is initiated through npm commands like npm run build, which internally invoke GN to generate build files and Ninja to compile the unified source tree containing both Chromium and brave-core code.

Where are Brave's Chromium patches stored?

Brave-specific modifications to upstream Chromium that cannot be implemented through brave-core alone are stored as .patch files in the patches/ directory of the brave-browser repository. During the npm run sync process, these patches are automatically applied to the Chromium source tree, allowing Brave to modify the underlying engine while keeping changes modular and trackable.

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