Action

The action field in epos.json controls what happens when the user clicks your extension icon in the browser toolbar.

For many extensions, this click opens a popup or a side panel. But if your project uses neither of those, Epos can still give that click a meaning.

When action Applies

action is only relevant when your project does not have a popup or side panel.

• If your project has a <popup> target, clicking the icon opens the popup.
• If your project has a <sidePanel> target, clicking the icon opens the side panel.
• If neither of those targets exists, Epos looks at the action field.

action: true

When you set action to true, clicking the toolbar icon sends a special :action bus event to your project.

background.ts

epos.bus.on(':action', tab => {
  console.log('Action clicked. Active tab:', tab)
})

epos.json

{
  "name": "My Extension",
  "action": true,
  "matches": "<background>",
  "load": ["dist/background.js"]
}

Notice that the currently active tab is passed to the event listener. This makes it easy to do something with the active page when the icon is clicked.

action: <page>

Extensions created with Epos can have a dedicated page for rendering their interface. To open that page when the extension icon is clicked, set action to <page>:

epos.json

{
  "name": "My Extension",
  "action": "<page>"
}

This way, clicking the extension icon opens the extension page in a new tab. The page URL is automatically generated by Epos and looks like this:

chrome-extension://<extension-id>/view.html/?locus=page&id=<id>

To run your extension on that page, set matches to <page> in epos.json:

epos.json

{
  "name": "My Extension",
  "action": "<page>",
  "matches": "<page>",
  "load": ["page.css", "page.js"]
}

action as a URL

Instead of true and <page>, you can also set action to a URL.

epos.json

{
  "name": "My Extension",
  "action": "https://example.com"
}

When the icon is clicked, Epos opens that URL in a new tab. If the URL is already open in an existing tab, Epos focuses that tab instead of opening a duplicate.

This can be useful if your extension renders its UI on a regular web page instead of a popup or side panel. The toolbar icon then becomes a quick way to open that page.

Summary

• action accepts only true, <page>, or a valid URL string.
• If your project has a <popup> or <sidePanel> target, action is ignored.
• The :action event is fired through epos.bus.