How to Create Custom Build Variants and Branding for Brave Browser

You can create custom build variants and branding for Brave by setting GN arguments like brave_product and brave_variant in your args.gn file, then providing matching branding resources in src/brave/app/branding/ and string overrides in src/brave/branding/.

Brave's desktop browser is built on Chromium and uses the GN (Generate Ninja) build system. Custom build variants—such as debug versus release builds, specialized feature sets, or entirely rebranded browsers—are controlled through GN arguments and a structured set of branding resources within the brave/brave-browser repository. This guide explains how to leverage these mechanisms to generate tailored Brave binaries.

Understanding Brave's Build System Architecture

Brave extends Chromium's build infrastructure, storing configuration in src/brave/BUILD.gn and related .gni files. The build process reads from args.gn to determine target architecture, build type, and product branding. Key files include src/brave/branding/product.gni for product name constants and src/brave/app/branding/ for visual assets like icons and splash screens.

Controlling Build Variants with GN Arguments

Build variants in Brave are defined through GN arguments that modify compilation flags, feature sets, and target platforms.

Essential GN Arguments for Custom Builds

The primary arguments for controlling build variants reside in your out/[BuildName]/args.gn file:

• is_debug – Set to true for Debug builds or false for Release builds.
• is_component_build – Set to true to build shared libraries instead of a single static binary, significantly speeding up incremental builds.
• target_os and target_cpu – Specify cross-compilation targets such as target_os = "linux" and target_cpu = "arm64".

These arguments are processed during the gn gen phase and affect how src/brave/BUILD.gn constructs the build graph.

Creating Custom Feature Variants

You can define custom feature groups using the brave_variant variable, typically declared in src/brave/branding/variant.gni or similar configuration files:

# In your args.gn

brave_variant = "my_custom_variant"

This variable enables conditional compilation in src/brave/BUILD.gn:

if (brave_variant == "my_custom_variant") {
  # Enable experimental features or different code paths

  defines += [ "ENABLE_MY_CUSTOM_FEATURE" ]
}

Implementing Custom Branding in Brave

Custom branding allows you to change the product name, icons, UI strings, and theme colors without modifying core source code.

Product Name and Strings

Product names are controlled through brave_product and associated .gni files. Set the product identifier in args.gn:

brave_product = "mybrand"

Then create src/brave/branding/mybrand/product_name.gni:

brave_product_name = "MyBrowser"
brave_product_full_name = "MyBrowser – Private by Default"

These constants propagate to src/brave/ui/strings/*.grd files, which define the UI text resources. Duplicate the existing .grd files in a mybrand subdirectory and replace instances of "Brave" with your brand name.

Icons and Visual Assets

Visual assets reside in src/brave/app/branding/. To use custom icons:

1. Create a new directory: src/brave/app/branding/mybrand/
2. Copy and modify assets from src/brave/app/branding/default/ (or brave/)
3. Ensure your assets match the required sizes and formats (PNG for icons, SVG for scalable graphics)

Update src/brave/app/branding/branding.gni to conditionally import your assets:

if (brave_product == "mybrand") {
  import("//src/brave/app/branding/mybrand/branding_mybrand.gni")
} else {
  import("//src/brave/app/branding/default/branding_default.gni")
}

In branding_mybrand.gni, define the paths to your icon files:

brave_branding_path = "//src/brave/app/branding/mybrand"
brave_logo_path = "$brave_branding_path/logo.png"
brave_icon_256_path = "$brave_branding_path/icon_256.png"

Theme Colors and UI Customization

Theme colors are defined in src/brave/ui/theme/theme_color.gni. Override these in your custom branding file:

brave_theme_color = "0xFF1E90FF"  # Dodger Blue instead of Brave Orange

This constant feeds into the Chromium theme system, affecting toolbar backgrounds and dialog highlights throughout the browser UI.

Step-by-Step Workflow for Custom Brave Builds

Follow this complete workflow to generate a custom-branded Brave binary:

1. Clone and sync the repository:

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

2. Generate build configuration:

   gn gen out/MyBuild

3. Configure build arguments by editing out/MyBuild/args.gn:

   is_debug = false
   target_os = "linux"
   target_cpu = "x64"
   brave_product = "mybrand"
   brave_variant = "myvariant"

4. Create branding resources:

   • Create src/brave/app/branding/mybrand/ with custom icons
   • Create src/brave/branding/mybrand/product_name.gni with custom strings
   • Update src/brave/app/branding/branding.gni to import your resources conditionally

5. Regenerate and build:

   gn gen out/MyBuild
   npm run build Release

6. Verify the output:

   out/MyBuild/Brave Browser

   Confirm that the window title, about dialog, and icons reflect your custom branding.

Code Examples and Configuration Files

Custom GN Arguments File

# out/MyBuild/args.gn

is_debug = false
is_component_build = false
target_os = "linux"
target_cpu = "x64"

# Custom branding and variant selection

brave_product = "mybrand"
brave_variant = "enterprise"

Branding Resource Import Logic

# src/brave/app/branding/branding.gni

if (brave_product == "mybrand") {
  import("//src/brave/app/branding/mybrand/branding_mybrand.gni")
  branding_assets_path = "//src/brave/app/branding/mybrand"
} else if (brave_product == "brave") {
  import("//src/brave/app/branding/brave/branding_brave.gni")
  branding_assets_path = "//src/brave/app/branding/brave"
}

Product Name Definition

# src/brave/branding/mybrand/product_name.gni

brave_product_name = "MyEnterpriseBrowser"
brave_product_full_name = "MyEnterpriseBrowser – Secure by Design"
brave_product_short_name = "MEB"

Feature Flag Conditional

# src/brave/feature_flags.gni

declare_args() {
  enable_enterprise_vpn = false
}

if (brave_variant == "enterprise") {
  enable_enterprise_vpn = true
}

Summary

• GN arguments in args.gn control build variants through variables like is_debug, target_cpu, and custom variables such as brave_variant.
• Custom branding is implemented by setting brave_product and providing replacement assets in src/brave/app/branding/[product]/ and string definitions in src/brave/branding/[product]/.
• The branding import pattern uses conditional GN imports in src/brave/app/branding/branding.gni to select the correct resource set at build time.
• Product strings are defined in .gni files and propagate to UI resources through the GRD (Google Resource Description) system used by Chromium.
• No source code modifications are required—only GN configuration files and asset replacements—to create a fully custom-branded Brave binary.

Frequently Asked Questions

What is the difference between brave_product and brave_variant in Brave's build system?

brave_product selects the branding identity—controlling the product name, icons, and visual assets—while brave_variant enables or disables specific feature sets or build configurations. For example, you might set brave_product = "mybrand" for custom enterprise branding and brave_variant = "enterprise" to activate VPN or policy features specific to that deployment.

Do I need to modify C++ source code to change the product name in Brave?

No. The product name and branding are controlled entirely through GN build files and resource assets. By creating a new directory under src/brave/branding/[your_product]/ with a product_name.gni file defining brave_product_name and brave_product_full_name, and updating src/brave/app/branding/branding.gni to import your assets, the build system automatically substitutes your branding throughout the UI without touching C++ source files.

How do I create a debug build versus a release build for a custom Brave variant?

Set is_debug in your args.gn file. For a debug build, use is_debug = true and optionally is_component_build = true to enable shared libraries for faster incremental compilation. For a release build, set is_debug = false and is_component_build = false to produce a fully optimized static binary. After editing args.gn, run gn gen out/[YourBuild] to regenerate the build configuration before compiling with npm run build.

Where should I place custom icon files when rebranding Brave?

Place them in src/brave/app/branding/[your_product]/. Create a new directory matching your brave_product value (e.g., mybrand/) and include PNG files for each required icon size (typically 16, 32, 48, 128, and 256 pixels) plus any SVG source files. Then create a branding_[your_product].gni file in that directory defining variables like brave_icon_256_path pointing to your assets, and import this file conditionally in src/brave/app/branding/branding.gni when brave_product == "mybrand".

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