Creating Extensions
Last updated
Last updated
Extensions allow you to customize and enhance the functionality of Bike.
Extensions are written in TypeScript. They can add new commands, keybindings, and other features to Bike. Sensitive features are protected by a permission system.
Extensions are loaded from Bike's extensions folder. Use the menu Bike > Extensions… to open that folder in the Finder.
Inside, you will find two folders:
@Bike: These are documentation files, they don't contain any code that is run. This folder is replaced each time Bike launches with latest API and documentation.
@Startup: This extension is always loaded first and will be recreated if deleted. Changes you make are preserved. It's a good place to experiment.
Open the entire Extensions folder in an editor with good TypeScript support. and work well. The folder structure looks like this:
Each extension has two key files:
./manifest.json
This file configures your extension:
version
: The extension version.
api_version
: The version of Bike's API that this extension requires. This is not the same as Bike's version number.
safari_inspectable
: If true (and Safari is set up for debugging) Bike will launch a JavaScript inspector in Safari when it starts.
permissions
: An array defining what the extension is allowed to do. By default, the startup extension has permission to read and write to the clipboard.
./src/main.ts
This is the entry point for your extension. It should export an activate
function, which is called when Bike launches and when extensions are reloaded.
In the @Startup extension, you can see examples of how commands, keybindings, and sidebar items are added to Bike. Right-click on any symbol and then choose "Go to Definition" from the popup to see API comments and options.
Many APIs follow a similar pattern: when you add something (like a command), a Disposable
is returned. This disposable acts as a handle to the addition. To remove it, call .dispose()
.
Bike automatically disposes of everything added by your extension when it reloads, so you only need to keep track of disposables if you plan to update or remove items dynamically.
Let's modify the @Startup extension to define a new "Archive Done" command. The command will move all completed items to an "Archive" row.
Extensions involve programming, and having the right environment makes it easier.
Open the @Startup
extension in an editor with TypeScript support. This provides autocomplete and error-checking.
Enable Safari debugging in manifest.json
and in Safari:
Go to Safari > Settings > Advanced and check "Show features for web developers".
This adds a new "Develop" menu to Safari's main menu.
Develop > Your Computer Name > Automatically Show Web Inspector for JSContexts.
When you launch Bike, Safari should open a web inspector, allowing you to debug your extension.
archiveDoneCommand
FunctionIn commands.ts
, add:
In main.ts
, import and register the command:
After saving your changes, Bike will automatically reload extensions, and the command will be available in the Command Pallet (Command-Shift-P
). Try it out!
Modify activate
to add the keybinding:
Now, enter block mode (press Escape
), then type a
. You should see "Archive Done!" printed to the console.
archiveDoneCommand
The Archive Done command needs to:
Find checked-off rows.
Locate (or create) the Archive row.
Move completed items into the Archive row.
Update archiveDoneCommand
in commands.ts
:
Now, when you run the Archive Done command, completed rows will be moved into the Archive section.
I hope that helps you get started. Let me now when you have questions or run into bugs.
This guide should help you get started. Experiment with modifying @Startup
, exploring the API, and building your own commands. Let me know if you have any questions or run into bugs!
Thanks!