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

> Understand the Brave build system architecture comparing brave-browser and brave-core. Learn how brave-browser orchestrates Chromium builds while brave-core holds the Brave browser code.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/brave/brave-browser/blob/main/package.json) that drive the entire compilation process.
- **Dependency management**: Specifies which external projects are needed (Chromium and brave-core) via [`package.json`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/README.md), brave-browser "fetches and syncs code from the projects defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/package.json) | brave-browser | Defines npm scripts (`init`, `sync`, `build`) and top-level dependencies. |
| [`README.md`](https://github.com/brave/brave-browser/blob/main/README.md) | brave-browser | Documents that brave-core is "mounted at `src/brave`" and explains the fetch/sync process. |
| [`CONTRIBUTING.md`](https://github.com/brave/brave-browser/blob/main/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`](https://github.com/brave/brave-browser/blob/main/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.