Developer Guide

插件开发指南

Learn how to author, package, and publish high-performance preview and metadata plugins for Bowerbird using the official @bowerbird/plugin-sdk.

全新独立文档站点已上线 (Cloudflare Nimbus)

支持多版本切换 (v1/v0)、中英双语检索与 AI Agent 读取优化。

前往新文档站点

1. Quick Start

Create a new directory for your plugin and install @bowerbird/plugin-sdk.

# Install plugin SDK as a dependency
pnpm add @bowerbird/plugin-sdk

Create your entry point src/index.tsx and use definePlugin:

import React from "react";
import {
  definePlugin,
  type PreviewPlugin,
  type PreviewViewportProps,
  type PreviewInspectorProps,
} from "@bowerbird/plugin-sdk";

function CustomViewport({ item, api }: PreviewViewportProps) {
  const file = api.getOriginalFile();

  return (
    <div className="flex flex-col items-center justify-center p-6 text-foreground">
      <h3 className="font-bold text-lg">{item.name}</h3>
      <p className="text-xs text-muted-foreground">Path: {file.path}</p>
      <button
        onClick={() => api.openWithDefaultApp()}
        className="mt-4 px-3 py-1.5 rounded-lg bg-primary text-primary-foreground text-xs font-semibold"
      >
        Open in System App
      </button>
    </div>
  );
}

export default definePlugin({
  id: "com.example.custom-preview",
  name: "Custom Preview",
  version: "1.0.0",
  description: "Custom file format preview plugin for Bowerbird",
  author: "Your Name",
  kind: "preview",
  priority: 50,
  extensions: ["xyz", "custom"],
  mimePrefixes: ["application/x-custom"],
  supportsZoom: false,
  Viewport: CustomViewport,
});

2. Plugin Manifest Schema

Every Bowerbird plugin must provide a valid manifest.json in its root directory.

{
  "id": "official.markdown-preview",
  "name": "Markdown Preview",
  "version": "1.0.0",
  "description": "Rich Markdown preview with syntax highlighting and frontmatter",
  "author": "Bowerbird Team",
  "kind": "preview",
  "priority": 50,
  "extensions": ["md", "markdown", "mdown", "mkd"],
  "mimePrefixes": ["text/markdown", "text/x-markdown"],
  "supportsZoom": true,
  "main": "index.js",
  "license": "MIT"
}
FieldTypeDescription
idstringUnique namespaced reverse-domain identifier (e.g. "official.audio-player")
kind"preview" | "metadata""preview" replaces the main viewport; "metadata" extends inspector tabs
prioritynumber (1 - 85)Higher priority plugins are evaluated first during file resolution
extensionsstring[]File extensions handled without dot (e.g. ["mp3", "wav"])
mainstringCompiled entrypoint JavaScript file (default: "index.js")

3. Host API & Capabilities

Each plugin component receives a secure PreviewPluginHostAPI instance allowing direct access to the file system and backend capabilities:

api.getOriginalFile()

Provides absolute file path, file size in bytes, HTTP asset streaming URL, and helpers like getText() and getBlob().

api.openWithDefaultApp()

Launches the physical file with the operating system's default registered desktop application.

api.revealInFinder()

Reveals and highlights the item in macOS Finder or Windows File Explorer.

api.updateItemDetails(patch)

Persists user-editable item metadata including notes, source URLs, star ratings, and prompt data.

4. Building & Publishing

Bundle your plugin into an ESM file named index.js with React externalized, because the Bowerbird host runtime provides React and core UI components:

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  build: {
    lib: {
      entry: "src/index.tsx",
      formats: ["es"],
      fileName: () => "index.js",
    },
    rollupOptions: {
      external: ["react", "react-dom", "react/jsx-runtime", "@bowerbird/plugin-sdk"],
    },
  },
});

1-Click Install via Bowerbird Protocol

Users can install your plugin with a single click using the custom OS protocol handler:

bowerbird://plugin/install?manifest=https://your-domain.com/manifest.json&id=your.plugin.id&version=1.0.0