插件开发指南
Learn how to author, package, and publish high-performance preview and metadata plugins for Bowerbird using the official @bowerbird/plugin-sdk.
支持多版本切换 (v1/v0)、中英双语检索与 AI Agent 读取优化。
Installation & basic template
manifest.json fields & priority
File handles, streams, metadata
ESM build & protocol install
1. Quick Start
Create a new directory for your plugin and install @bowerbird/plugin-sdk.
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"
}| Field | Type | Description |
|---|---|---|
| id | string | Unique namespaced reverse-domain identifier (e.g. "official.audio-player") |
| kind | "preview" | "metadata" | "preview" replaces the main viewport; "metadata" extends inspector tabs |
| priority | number (1 - 85) | Higher priority plugins are evaluated first during file resolution |
| extensions | string[] | File extensions handled without dot (e.g. ["mp3", "wav"]) |
| main | string | Compiled 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:
