AddFox
  • English

      • Entry Concepts

      Entries correspond to the functional modules of browser extensions, such as background scripts, content scripts, popup pages, etc. Addfox provides three configuration methods that can be used individually or in combination.

      What are Entries

      Browser extensions consist of multiple independent functional modules, each requiring an entry file:

      Entry TypeBrowser Extension ConceptTypical Use
      backgroundService Worker / Background scriptHandle extension lifecycle, cross-page communication
      contentContent ScriptManipulate webpage DOM, interact with pages
      popupPopup pageInterface that appears after clicking toolbar icon
      optionsOptions pageExtension settings interface
      sidepanelSide panelChrome side panel
      devtoolsDeveloper toolsCustom DevTools panel
      offscreenOffscreen documentBackground tasks requiring DOM API

      Configuration Methods

      Do not configure entry, let the framework discover entries automatically by directory and file name.

      app
      background
      index.ts# → background entry
      content
      index.ts# → content entry
      popup
      index.ts# → popup entry
      ...

      Advantages:

      • Zero configuration, follow conventions
      • Add new entries by simply creating directories
      • Clear code structure

      See File-based Entry.

      Method 2: Config-based (entry + manifest)

      Configure entry-related capabilities through entry and manifest in addfox.config.ts:

      export default defineConfig({
  entry: {
    background: "background/index.ts",
    content: "content/index.ts",
    popup: "popup/index.ts",
  },
  manifest: {
    manifest_version: 3,
    action: { default_popup: "popup/index.html" },
  },
});

      Advantages:

      • Centralized entry and manifest configuration
      • Support custom entry names
      • Can override auto-discovery results

      See Config-based Entry and manifest configuration.

      Hybrid Usage

      These three methods can be used in combination with the following priority:

      1. Highest: entry in config
      2. Second: Source file paths in manifest
      3. Third: Auto-discovery
      export default defineConfig({
  entry: {
    // Highest priority: overrides all other configurations
    popup: "pages/popup/main.ts",
  },
  manifest: {
    // Second priority: used when entry is not specified
    background: { service_worker: "./background/index.ts" },
    // popup will use entry config, not this
    action: { default_popup: "./popup/index.ts" },
  },
  // Third priority: auto-discover unconfigured entries
});

      Core Principles

      Entries must be JS/TS

      Addfox is built on Rsbuild, and the real build entries can only be .js, .jsx, .ts, .tsx script files.

      HTML Handling

      • Entries without HTML: background, content only need script files
      • Entries with HTML: popup, options, sidepanel, devtools, offscreen
        • If no HTML is provided, Rsbuild will auto-generate (containing <div id="app"></div>)
        • If providing custom HTML template, must mark entry script with data-addfox-entry

      Example: Custom HTML Template

      <!-- app/popup/index.html -->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Popup</title>
  </head>
  <body>
    <div id="app"></div>
    <!-- Mark entry with data-addfox-entry -->
    <script type="module" data-addfox-entry src="./index.ts"></script>
  </body>
</html>

      Built-in and Custom Entries

      Built-in Entries (Reserved Names)

      The following names have special meanings and are automatically recognized by Addfox:

      Entry NameDescription
      backgroundService Worker (MV3) or background page (MV2)
      contentContent script
      popupToolbar popup
      optionsExtension options page
      sidepanelSide panel
      devtoolsDeveloper tools
      offscreenOffscreen document
      Warning

      Built-in entry names cannot be changed. The framework relies on these names for automatic recognition and manifest path filling.

      Custom Entries

      In addition to built-in entries, you can configure any name in entry as a custom entry (e.g., capture, my-page):

      export default defineConfig({
  entry: {
    capture: { src: "capture/index.ts", html: true },
  },
});

      Custom entries produce standalone pages accessible via chrome-extension://<id>/capture/index.html.

      Next Steps