🌐 Chromium WebUI Pages in iBrowe

WebUI pages in iBrowe (based on Chromium) utilize the same underlying system for routing, compiling, and optimizing HTML/JS modules. These modules can be referenced relatively (e.g., ../my_module.html) or absolutely via internal URLs (e.g., ibrowe://settings/my_module.html).

Resources must be accessible both via HTTP and FileSystem during the build process. Each ibrowe:// URL is mapped to a corresponding file path using the optimize_web_ui GN build action.

🧱 Typical Build Steps for Chromium-Based WebUIs

For most standard WebUIs (like ibrowe://settings), the GN pipeline includes:

  1. Closure Compiler – Type-checking for JS modules
  2. Grit Tool – Packs resources into a .pak file via a .grd manifest
  3. Unpacking – Extracts .pak contents into a staging directory
  4. optimize_web_ui – Flattens/minifies modules into a single file
  5. Repacking – Final optimized .pak is created with Grit again

🔁 URL to Filesystem Path Resolution

To resolve paths like ibrowe://resources/..., optimize_web_ui.py uses built-in mappings:

_URL_MAPPINGS = [
    ('chrome://resources/cr_components/', _CR_COMPONENTS_PATH),
    ('chrome://resources/cr_elements/', _CR_ELEMENTS_PATH),
    ('chrome://resources/css/', _CSS_RESOURCES_PATH),
    ('chrome://resources/html/', _HTML_RESOURCES_PATH),
    ('chrome://resources/js/', _JS_RESOURCES_PATH),
    ('chrome://resources/polymer/v1_0/', _POLYMER_PATH),
    ('chrome://brave-resources/', _BR_RESOURCES_PATH)  # becomes ibrowe-resources in iBrowe
]

For non-core paths like ibrowe://history, the mapping is defined directly in the GN build:

optimize_webui("build") {
  host = "history"
  input = rebase_path(".", root_build_dir)
  ...
}

This tells the build system to map ibrowe://history/xyz.html to the corresponding filesystem directory.

🧪 Debug Builds vs Release Builds

  • 🔧 Debug Builds Serve individual files directly (e.g., ibrowe://settings/module1.js) No flattening or minification occurs Useful for debugging module loading in raw form

  • 🚀 Release Builds WebUIs are optimized using optimize_web_ui Flattened and minified bundles are served Requires additional testing to ensure compatibility in both modes

🐾 iBrowe-Specific WebUIs

WebUIs created specifically for iBrowe (not inherited from Chromium) do not use optimize_web_ui. Instead, they rely on Webpack, which offers:

  • TypeScript + JavaScript support
  • Module resolution and tree-shaking
  • Code splitting or bundling
  • Minification
  • Dynamic .grd generation from import statements

📚 For more info, see: https://github.com/brave/brave-browser/wiki/Javascript-and-Typescript-Bundling

Adapted and refactored from Brave’s documentation on Chromium WebUI: https://github.com/brave/brave-browser/wiki All references to chrome:// and brave:// are mapped to ibrowe:// in this context.