Creating Extensions

Extensions allow you to customize and enhance the functionality of Bike.

Overview

Extensions are written in TypeScript. They can add new commands, keybindings, views, and other features to Bike. Sensitive features are protected by a permission system. Extensions don't require that you install a build tool such as NPM.

Extensions Folder

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: This extension ships with Bike and includes API documentation. It is replaced each time Bike launches. This is extension is always loaded first and is a good place to see how Bike APIs work.

• @Startup: This extension is always loaded second and will be recreated if deleted. Changes you make are preserved. It's a good place to experiment.

Quick Tour

Open the entire Extensions folder in an editor with good TypeScript support. VS Code and Zed work well. The folder structure looks like this:

Extensions/
  @Bike/
    @configs/
    @types/
    src/
  @Startup/
    manifest.json
    src/
      dom/
      main.ts

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.

export function activate(context: ExtensionContext) {
  ...
}

In the @Bike 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. You only need to keep track of disposables if you plan to update or remove items dynamically.

Setup Environment

Extensions involve programming, and having the right environment makes it easier.

1. Open the @Startup extension in an editor with TypeScript support. This provides autocomplete and error-checking.

2. Enable Safari debugging in manifest.json and in Safari:

   • Go to Safari > Settings > Advanced and check "Show features for web developers".

   • Choose menu item Safari > Develop > Inspect Apps and Devices to show a window with all inspectable script contexts.

   • Start Bike 2 and it should show in the Safari window from previous state. You may want to click the ... to the right of Bike's icon and check "Automatically Inspect New JSContexts". When you launch Bike, Safari should open a web inspector, allowing you to debug your extension.

3. Enable Console.app logging for Bike:

   • Open Console.app

   • Choose menu item Start > Streaming

   • Filter Console.app with: Process: Bike Category: Extensions Category: ScriptContext

   • You should now see errors from your scripts and extensions logged

Understand Environment

Each extension runs in its own isolated JSContext.

Bike includes an embedded version of the esbuild build tool. This is used to bundle your extension code into a single script so that it can be loaded into the JSContext. This step is required because JSContext doesn't support Typescript or import statements.

Create a new Command

Let's modify the @Startup extension to define a new "Archive Done" command. The command will move all completed items to an "Archive" row.

Define archiveDoneCommand Function

In main.ts, add:

function archiveDoneCommand(): boolean {
  console.log("Archive Done!");
  return true;
}

Adding a New Bike Command

In main.ts, import and register the command:

export function activate(context: ExtensionContext) {
  bike.commands.addCommands({
    source: "Startup",
    commands: {
      "startup:archive-done": archiveDoneCommand,
    },
  });
}

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!

Add a Keybinding for the Command

Modify activate to add the keybinding:

export function activate(context: ExtensionContext) {
  ...
  bike.keybindings.addKeybindings({
    keymap: "block-mode",
    source: "startup",
    keybindings: {
      "a": "startup:archive-done",
    },
  });
}

Now, enter block mode (press Escape), then type a. You should see "Archive Done!" printed to the console.

Implement the Full archiveDoneCommand

The Archive Done command needs to:

1. Find checked-off rows.

2. Locate (or create) the Archive row.

3. Move completed items into the Archive row.

Update archiveDoneCommand in main.ts:

import { Row } from "outline";

...

function archiveDoneCommand(): boolean {
  // Get frontmost editor
  let editor = bike.frontmostOutlineEditor
  if (!editor) return false

  // Get the outline, done rows, and archive row
  let outline = editor.outline
  let donePath = "//@data-done except //@id = archive//*"
  let doneRows = outline.query(donePath).value as Row[]
  let archiveRow = (outline.query("//@id = archive").value as Row[])[0]
  
  // Insert an Archive row if needed and move done rows
  outline.transaction({ animate: "default" }, () => {
    if (!archiveRow) {
      archiveRow = outline.insertRows([{ 
        id: "archive",
        text: "Archive",
      }], outline.root)[0]
    }
    outline.moveRows(doneRows, archiveRow)
  })
    
  return true
}

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.

Next Steps

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!