Surfaces

A surface is one of the entrypoint types Manifest V3 understands. Each top-level folder under src/app/ declares one. There are two kinds:

• Routable surfaces (popup, options, sidepanel): HTML pages running a full React app with file-based routing. The entry is a page.tsx.
• Script surfaces (background, content): plain scripts with no HTML page. The entry is an index.ts.

A surface exists if its folder and entry file exist. Extro generates the matching manifest fields automatically and adds nothing for surfaces you don't have.

Popup

The panel that opens when the user clicks your extension's toolbar icon.

export default function Popup() {
  return <h1>Hello.</h1>
}

Generates in the manifest:

{
  "action": { "default_popup": "popup.html" }
}

Popups size to their content, so give your root element an explicit width. Chrome caps popups at 800x600.

Options

The extension's settings page. Extro opens it in a full tab.

export default function Options() {
  return <h1>Settings</h1>
}

{
  "options_ui": { "page": "options.html", "open_in_tab": true }
}

To open it programmatically from another surface, call chrome.runtime.openOptionsPage().

Side panel

Chrome's persistent side panel surface.

export default function SidePanel() {
  return <h1>Side panel</h1>
}

{
  "side_panel": { "default_path": "sidepanel.html" }
}

Background

The MV3 service worker. Runs in the extension's own context with full access to the chrome.* APIs.

chrome.runtime.onInstalled.addListener(() => {
  console.log("Extension installed")
})

{
  "background": { "service_worker": "background.js" },
  "permissions": ["storage"]
}

storage is a default permission added when a background script is present and you haven't supplied your own permissions list. See Manifest Generation.

Content

A script injected into web pages. It has two modes, which can coexist:

• index.ts: a plain content script.
• page.tsx: a content script UI (CSUI), a React tree mounted into the host page.

console.log("Running inside", location.hostname)

{
  "content_scripts": [{ "matches": ["<all_urls>"], "js": ["content.js"] }],
  "host_permissions": ["<all_urls>"]
}

<all_urls> is the default; set content.matches in extro.config.ts to narrow it. Content scripts are a deep enough topic to get their own page.

Summary