Skip to content

Instantly share code, notes, and snippets.

@xyhp915
Last active August 12, 2024 12:46
Show Gist options
  • Save xyhp915/bb9f67f5b430ac0da2629d586a3e4d69 to your computer and use it in GitHub Desktop.
Save xyhp915/bb9f67f5b430ac0da2629d586a3e4d69 to your computer and use it in GitHub Desktop.

Logseq Plugin Setup Guide

[WIP] Logseq Plugin System is currently under Alpha Testing phase.

For Developers

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.

Install Node.js and NPM

You can download Node.js here, which will include NPM: https://nodejs.org/en/download/.

Install TypeScript

To install TypeScript, run npm install -g typescript in a terminal.

Get Logseq desktop app

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.

Go to Settings > Turn on Developer Mode

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.

Create plugin package from scaffold

We will use logseq-hello-world as scaffold. Download this package files using Git or download zip straight to your own plugin package directory.

Explain package.json

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-plugin is better for Googling.
  • version [required] semantic version
  • main [optional] entry of plugin, optional for theme plugin only.
    • .html file entry indicate that the plugin provide main iframe ui.
    • .js file 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 of pkg#name would 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.

Develop your code

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.

1. import user plugin SDK [required]

import '@logseq/libs'

It provides TS types and global sdk namespace logseq.

2. bootstrap your main function [required]

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!

3. show your code [required]

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!

Next steps

For users

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment