[WIP] Logseq Plugin System is currently under Alpha Testing phase.
In this short guide, it will walk you through the steps needed to set up your development environment for writing and running a hello world simple inside of Logseq Desktop Client. You know Logseq Plugin based on Web Technologies composed of JS & HTML & CSS, but neither are mandatory, you can develop plugins use any language which can be translated to javascript (Logseq made by Clojurescript!). We will use Typescript to demonstrate this sample. Because there is a type definition file to make development experience even better.
You can download Node.js here, which will include NPM: https://nodejs.org/en/download/.
To install TypeScript, run npm install -g typescript in a terminal.
At this time, plugin development and testing needs to be done using the Logseq desktop app. This is because Logseq needs to read your code saved as a local file. The Logseq desktop app can be downloaded here: https://github.com/logseq/logseq/releases.
If you already have the desktop app, please make sure to update to the latest version, as several features have been added specifically in order to provide a better plugin development experience.
This will bring up the "Plugins" entry in three dots more menu list on top right of head bar. Go to Plugins page, and you will get a button with Load unpacked plugin label.
We will use logseq-hello-world as scaffold. Download this package files using Git or download zip straight to your own plugin package directory.
Generally Logseq plugin package is described by package.json file located root. Let's checkout these primary keys.
{
"name": "logseq-plugin-hello-world",
"version": "0.0.1",
"main": "dist/index.html",
"logseq": {
"id": "_edodonfur",
"title": "Say Hi to Logseq",
"icon": "logseq.png"
}
}- name [required] a name of plugin.
- it starts with
logseq-pluginis better for Googling.
- it starts with
- version [required] semantic version
- related link: https://semver.org/
- main [optional] entry of plugin, optional for theme plugin only.
.htmlfile entry indicate that the plugin provide main iframe ui..jsfile entry indicate that the plugin without main iframe ui.
- logseq [required] specs of plugin & indicate it's a Logseq package.
-
id[optional] the identity key of plugin. if you don't provide it that will be auto generated on load development package. -
title[optional] the title display of plugin list card. if not provieded, value ofpkg#namewould be used. -
icon[optional] plugin logo for your own brand :D.Apart from these primary keys, you might find other useful fields, e.g.
author,description,repository. Although these are not necessary, but completed fields are kind for your plugin users.
-
This scaffold using Parcel as ts bundler, just it works out of box. Of Course, you could choose another one what you prefer. Then install dependencies npm install and watch your code in development mode npm run dev. It will build the development version outputs to the dist directory. Go to plugins page and pick your plugin root directory by Load unpacked plugin button. You will get a message from this plugin. Let's explain the entry file of index.ts.
import '@logseq/libs'It provides TS types and global sdk namespace logseq.
logseq.ready(main).catch(console.error)Limited by the plugin system mechanism, user main function should wait for some preparations to make sure the SDK api works correctly!
function main () {
logseq.App.showMsg('❤️ Message from Hello World Plugin :)')
}Change your code and reload the plugin to make it works.
If you develop main ui in iframe, HMR feature provided by some ui frameworks is convenient that can avoid reloading plugin again and again.
🎉 Actually, you're done!
- Awesome samples
- Community plugins
- Community forums
Currently, Logseq plugin can only run in developer mode. Under this mode, plugin has ability to access notes data. So if you're working with sensitive data, you'd better confirm the plugin is from trusted resource before installing it.