logseq-plugin-dev_skill

This skill helps you build, debug, and ship Logseq plugins using the @logseq/libs SDK across commands, content, and UI.

TypeScript

0

GitHub Stars

1

Bundled Files

3 weeks ago

Catalog Refreshed

2 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstart where the catalogue uses aiagentskills.

npx veilstart add skill 0xrichardh/agent-skills --skill logseq-plugin-dev

SKILL.md2.1 KB

Overview

This skill provides a practical, example-driven guide to building, debugging, and deploying Logseq plugins using TypeScript and the @logseq/libs SDK. It focuses on manifest setup, lifecycle hooks, Editor/App/DB/UI API usage, and recommended development workflows. Use it to get from scaffold to a working plugin with predictable behavior inside Logseq's iframe sandbox.

How this skill works

The skill explains how a plugin runs inside a sandboxed iframe and communicates with the main app via RPC, and how to initialize your code with logseq.ready(main). It covers manifest requirements, installing @logseq/libs, bundling with Vite or similar, and loading an unpacked plugin in developer mode. It also walks through using the Editor, App, DB, and UI APIs for read/write operations, commands, queries, and theme-aware UI injections.

When to use it

Create a new Logseq plugin from scratch (Vanilla TS or React + Vite).
Implement editor features: slash commands, block insertion, batch edits.
Integrate with Logseq DB: datascript queries and programmatic page/block queries.
Build UI inside Logseq: provideUI, main UI, and theme-aware components.
Debug, refactor, or optimize an existing plugin for stability and performance.

Best practices

Declare a clear logseq field in package.json and use logseq.ready(main) for initialization.
Use @logseq/libs types in TypeScript for safer API usage and autocompletion.
Keep heavy work off the main thread; batch DB writes and debounce editor operations.
Use Logseq CSS variables for theming so UI matches user themes and dark mode.
Keep RPC interactions minimal and validate responses; handle plugin unload/cleanup in lifecycle hooks.

Example use cases

Add a slash command that inserts templated content into the current page and preserves cursor position.
Create a sidebar React app that queries the DB for tasks and provides bulk-complete actions.
Build a small visualization using provideUI that respects Logseq theme variables and updates on DB changes.
Refactor a plugin to replace direct DOM access with provideUI and SDK APIs for better compatibility.
Debug intermittent errors by adding lifecycle logs, catching rejected promises, and testing in unpacked plugin developer mode.

FAQ

Enable Developer Mode in Logseq Settings, choose Load unpacked plugin, and select your plugin folder after building or using a dev server compatible with your manifest.

Which APIs are best for reading and writing content?

Use logseq.Editor methods for immediate editor actions (getCurrentPageBlocksTree, insertBlock) and logseq.DB.datascriptQuery for advanced queries; batch writes when possible to reduce RPC overhead.