Logseq Plugin Development
This skill helps you build high-quality plugins for Logseq using the @logseq/libs SDK.
Core Concepts
Logseq plugins run in a sandboxed iframe and communicate with the main Logseq application via an RPC bridge.
- Manifest: Every plugin needs a
package.jsonwith alogseqfield. - SDK: Use
@logseq/libsto interact with Logseq. - Lifecycle: Use
logseq.ready(main)to initialize your plugin.
Getting Started
- Scaffold:
- Basic TS: assets/template/ - React + Vite: assets/template-react/
- Install Dependencies:
npm install @logseq/libs. - Build: Use Vite or a similar bundler to package your JS/TS code.
- Load: In Logseq, go to
Settings -> Plugins -> Developer Mode, thenLoad unpacked pluginand select your plugin directory.
Common Workflows
1. Registering Commands
Use logseq.Editor.registerSlashCommand or logseq.App.registerCommandPalette.
2. Interacting with Content
- Read:
logseq.Editor.getCurrentPageBlocksTree() - Write:
logseq.Editor.insertBlock(parentBlockId, content) - Query:
logseq.DB.datascriptQuery(query)
3. UI and Theming
- UI: Use
logseq.provideUIto inject HTML orlogseq.showMainUIto show a full-screen app. - Theming: Use Logseq CSS variables (e.g.,
--ls-primary-background-color) for consistency.
Resources
- API Reference: See references/api.md for a detailed list of available methods and examples.
- Boilerplates:
- assets/template/ (Vanilla TS) - assets/template-react/ (React + Vite)
- Examples: See references/examples.md for common patterns like mind maps and slash commands.