anti
BrowseDocumentationCommunityFeedback
BROWSE / GETTING STARTED

Your first plugin

Create a Python extension, load it in Browse and add your first command.

Developer preview · macOS · Python SDK 1.1

Before you start

Browse plugins are called extensions in the app. They use Python to work with the browser: manage tabs, add commands, build native panels and widgets, or change matching pages. JavaScript is available for work inside a page.

You need a Browse development build and Python 3.11 or later for in-app testing. Settings → Extensions reports a missing Python runtime. You can also try commands and panels with the downloadable developer tools without opening Browse.

Create an extension

  1. Open Settings → Extensions → Add… → New Extension….
  2. Name it My Plugin and choose a parent folder. Browse creates a folder containing browse.toml and main.py.
  3. Review the permissions before installing. Keep the development folder separate from your personal files.
  4. Replace browse.toml and main.py with the examples below. Save both files; a development extension reloads when its source changes.

Describe it in browse.toml

id = "dev.local.my-plugin"
name = "My Plugin"
version = "1.0.0"
description = "A small command for the current tab."
author = "Your Name"
permissions = ["commands", "tabs"]

Write main.py

from browse import command, tabs

@command("My Plugin: say hello", id="hello", symbol="hand.wave")
async def hello():
    tab = await tabs.current()
    return f"Hello! You're on {tab.title if tab else 'no tab'}."

Open the command bar with ⌘T and search for My Plugin: say hello. Returning a string shows a short message. Browser calls are asynchronous: use async def and await. Reading the current tab needs tabs; registering the command needs commands.

Try it without the app

Unzip the SDK download, open Terminal in its browse-extension-sdk folder and run the following commands. The tool needs Python 3.11 or later and uses only the standard library. It creates my-plugin in the current folder. Use sh so the launcher works even if your unzip tool removes executable permissions.

sh bin/browse-ext new "My Plugin" --id dev.yourname.my-plugin
sh bin/browse-ext check my-plugin
sh bin/browse-ext run my-plugin --command "My Plugin: say hello"
sh bin/browse-ext pack my-plugin

← All documentation