How Brave Browser Handles Sessions and Preferences: A Deep Dive into the Chromium-Based Architecture

Brave inherits Chromium’s PrefService and SessionService architecture to manage user settings and browsing state, extending it with Brave-specific preferences like shields and wallet settings while persisting data to JSON files in the user profile directory.

The brave/brave-browser repository builds upon Chromium’s foundation to handle sessions and preferences, adding privacy-focused customizations while maintaining compatibility with the underlying storage mechanisms. Understanding this architecture is essential for developers contributing to Brave or building extensions that interact with user settings.

Understanding the Preference Architecture in Brave

The PrefService Hierarchy

At the core of Brave’s preference system is the PrefService, a singleton created for each BrowserContext (profile) in chrome/browser/profiles/profile_impl.cc. This service manages a layered hierarchy of preference stores:

• Default store: Read-only values shipped with the browser
• User store: A PrefStore backed by JSONPrefStore that persists to disk
• Managed store: Enterprise policy overrides

When code calls Profile::GetPrefs(), it receives the PrefService instance for that profile, which coordinates reads and writes across these layers.

Brave-Specific Preference Keys

Brave extends the standard Chromium preference set by registering custom keys in components/brave_shields/common/pref_names.h and brave/browser/prefs/brave_browser_prefs.cc. These include:

• brave.shields.enabled
• brave.show_wallet_button
• brave.brave_ads.enabled

Registration occurs during profile creation via PrefRegistrySimple, where each key is bound to a default value and type.

Persistence and Storage Format

User-level preferences serialize to a JSON file located at <profile>/Preferences on disk. The JSONPrefStore class in components/prefs/json_pref_store.h handles atomic read/write operations to prevent corruption during crashes.

Access in code follows this pattern:

PrefService* prefs = profile->GetPrefs();
bool shields_enabled = prefs->GetBoolean(brave_shields::prefs::kShieldsEnabled);

How Brave Manages User Sessions

The SessionService Core

Brave uses Chromium’s SessionService (defined in chrome/browser/sessions/session_service.h) to track the live state of browser windows and tabs. Each tab receives a unique SessionID, and the service maintains a mapping of SessionID → TabNavigation objects that capture:

• Current URL and title
• Scroll position
• Navigation history
• Session storage data

Session Persistence Across Launches

When the browser shuts down, SessionService::SaveLastSession() serializes the current window and tab state to the profile directory. These files reside in <profile>/Session Storage/ and include:

• Last Session files containing tab navigation data
• Window state descriptors
• Tabs metadata

On startup, SessionRestore (implemented in chrome/browser/sessions/session_restore.cc) reads these files through the SessionService and reconstructs the previous browsing session. The restore logic triggers via Browser::SessionRestore() when the preference prefs::kRestoreOnStartup indicates restoration is desired.

Web-Level Session Storage

Separate from the UI session management, individual websites use sessionStorage for temporary data persistence. Brave handles this through SessionStorageNamespace (defined in content/browser/renderer_host/session_storage_namespace_impl.h), which isolates storage per tab and clears it when the tab closes.

Practical Code Examples

Reading a Brave-Specific Preference

// In any component that has a Profile* (e.g., a UI controller)

PrefService* prefs = profile->GetPrefs();
bool shields_enabled = prefs->GetBoolean(brave_shields::prefs::kShieldsEnabled);
// Use the value to conditionally show UI elements or adjust behavior

Source: chrome/browser/ui/webui/settings/settings_localized_strings_provider.cc

Persisting a Custom Preference

// Registration (usually done during profile creation in brave_browser_prefs.cc)
void RegisterBravePrefs(PrefRegistrySimple* registry) {
  registry->RegisterBooleanPref(brave::kMyFeatureEnabled, false);
}

// Later, toggling the flag based on user interaction
void SetMyFeatureEnabled(Profile* profile, bool enabled) {
  profile->GetPrefs()->SetBoolean(brave::kMyFeatureEnabled, enabled);
  // The JSONPrefStore automatically handles atomic writes to disk
}

Source: components/brave_shields/common/pref_names.h

Restoring the Last Session on Startup

// Browser startup flow (simplified from chrome/browser/ui/browser.cc)
void Browser::Init() {
  // … other initialization …
  if (ShouldRestoreLastSession()) {
    SessionRestore::RestoreSession(profile_);
  }
}

// Helper that checks user preference
bool Browser::ShouldRestoreLastSession() {
  return !profile_->GetPrefs()->GetBoolean(prefs::kRestoreOnStartup);
}

Source: chrome/browser/sessions/session_restore.cc

Saving the Current Session on Shutdown

void Browser::Shutdown() {
  // … other shutdown work …
  profile_->GetSessionService()->SaveLastSession();
  // Serializes to <profile>/Session Storage/Last Session
}

Source: chrome/browser/sessions/session_service.cc

Summary

• Brave extends Chromium’s architecture for sessions and preferences, using PrefService for settings and SessionService for browsing state.
• Preferences are stored in a layered hierarchy (default, user, managed) and persist to <profile>/Preferences as JSON via JSONPrefStore.
• Brave-specific settings like shields and wallet options are registered in components/brave_shields/common/pref_names.h and accessed via Profile::GetPrefs().
• Sessions track windows and tabs using SessionID mappings, serializing to <profile>/Session Storage/ on shutdown and restoring via SessionRestore on startup.
• Web-level session storage is handled separately through SessionStorageNamespace for per-tab isolation.

Frequently Asked Questions

Where does Brave store user preferences on disk?

Brave stores user preferences in a JSON file located at <profile>/Preferences within your user data directory. This file is managed by the JSONPrefStore class, which ensures atomic writes to prevent corruption. The preferences include both Chromium defaults and Brave-specific settings like shields configuration and wallet preferences.

How does Brave handle session restoration on startup?

When Brave starts, the SessionRestore mechanism checks the prefs::kRestoreOnStartup preference. If restoration is enabled, it reads the serialized session data from <profile>/Session Storage/Last Session and recreates the previous windows and tabs. This process uses the SessionService to map stored SessionID values back to live TabNavigation objects.

What is the difference between SessionService and sessionStorage?

SessionService is a browser-level component that manages the UI state of windows and tabs, including navigation history and scroll positions, persisting across browser restarts. In contrast, sessionStorage is a Web API that provides temporary storage for individual websites, isolated per tab and cleared when the tab closes. Brave implements sessionStorage through SessionStorageNamespace in the content layer, separate from the SessionService in the browser layer.

How can developers access Brave-specific preferences in code?

Developers can access Brave-specific preferences by obtaining the PrefService from the current profile using Profile::GetPrefs(), then calling typed getter methods like GetBoolean() or SetBoolean(). Brave defines its preference keys in headers such as components/brave_shields/common/pref_names.h (e.g., brave_shields::prefs::kShieldsEnabled). Registration of new preferences should occur during profile initialization using PrefRegistrySimple.

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