Addon Development Tools

[zerebos]

Hi everyone, I've been working on a set of tools to help making development addons for Trilium a little bit easier. This applies for all kinds of addons like widgets, render notes, and even simple scripts. So in this post I'm going to try and break down some of these tools and the concepts I was going for and even show an example at the end.

Ideas

These come from issues or shortcomings I found developing the few scripts and widgets I've made. It also comes from some other discussions here on GitHub and noticing what some other developers do.

Remote

This one is pretty straightforward, but the idea here is to make developing your addons outside of Trilium as painless as possible. If you're making a single-file addon, copy and pasting can get tedious. If you're making a bundled addon with webpack or similar, waiting for a build to end then copy and pasting while waiting for the code editor to load can eat up a lot of time. Ideally, we want something we can either easily trigger to automatically update our note in Trilium, or something that can do so automatically at the end of a build. This could even be expanded into automatically creating and modifying notes as needed.

Types

I know many developers like to use TypeScript, so having a types package of some kind can be extremely beneficial rather than wasting time scaffolding the api. And even when using JavaScript, having that types package for autocompletion and verification is extremely helpful.

zip

This is something I came to appreciate more recently in another thread #4213 (comment). Distributing addons as a zip file for end users to import makes installing addons way less painful for users, especially the less technologically inclined. It also allows developers to leverage promoted attributes as a sort of settings panel for their addons. It works as a simple UI for the end user, while also being an easy and reliable API for developers. I highly recommend taking advantage of this.

From a development perspective the only annoying part about this is having to export via Trilium every time we want to make a release. But that also means removing any testing code, or notes or attributes we may have for debugging or future features or anything else like that. It would be ideal to be able to just pack a zip directly from our development environment.

Tools

Some tools/packages I've made to solve the issues and ideas from above.

trilium-etapi

As the name would suggest, this is a nodejs-based wrapper around the Trilium ETAPI. This has a dead simple API with a 1:1 mapping to the spec. With a package like this, you can update your code note in Trilium using a single line in your build script. It also opens the door to more advanced options like creating custom subtrees to map your local files to Trilium. This solves all the issues I had with remote development (so far).

trilium-types

This is a types package for both frontend and backend script notes. Fully compatible with TypeScript and JavaScript and includes more types than even the official API docs do. This solves the lack of typing issues from above.

trilium-pack

This package builds Trilium-compatible zip files in your local development environment given a simple json-like config. It can either be used in a cli-like fashion with a tpack.config.js or used directly in js const pack = require("trilium-pack"). This avoids the need to have a clean tree when exporting out of your own Trilium instance and can even allow for automated releases.

Example (Trilium Markdown Preview)

I recently updated my widget Trilium Markdown Preview to make use of these packages and the concepts I laid out up top. Transitioning to use these tools was actually rather painless.

Remote

The first thing I did was create a script I could run at any time to update my code note in Trilium with the copy of the widget in my development environment. So I installed two things trilium-etapi and dotenv. I make use of dotenv to securely store and use my token locally. I created my .env file

TRILIUM_ETAPI_TOKEN=redacted
NOTE_ID=redacted

and the script that sends it to Trilium scripts/send.js

const fs = require("node:fs");
const path = require("node:path");
const dotenv = require("dotenv");
const tepi = require("trilium-etapi").default;

dotenv.config();

const widget = path.join(__dirname, "..", "src", "widget.js");

tepi.token(process.env.TRILIUM_ETAPI_TOKEN);
tepi.putNoteContentById(process.env.NOTE_ID, fs.readFileSync(widget).toString());

then added it as a script to my package.json as "send": "node scripts/send.js". Now anytime I run npm run send the copy in Trilium notes is updated.

Types

Since I'm just using JavaScript, this one was dead simple. I installed the package npm install @types/trilium@npm:trilium-types, and checked my widget.js and saw that api was already recognized as the frontend api.

I then just went through the file and made sure there were no unrecognized usages of anything from the API. Obviously for TypeScript this will be a little but more thorough, but for me, it's good enough.

zip

Once again, installed the package trilium-pack and then I created my script in package.json as "pack": "tpack",. Then I created my configuration tpack.config.js

module.exports = {
    output: "dist/Trilium-MarkdownPreview.zip",
    notes: {
        title: "Markdown Preview",
        file: "src/widget.js",
        attributes: {
            "#widget": "",
            "#label:syntaxHighlighting": "promoted,single,boolean",
            "#syntaxHighlighting": "true"
        },
        children: [
            {type: "file", file: "lib/highlight.min.js"},
            {type: "file", file: "lib/marked.min.js"},
            {file: "src/styles.css"}
        ]
    }
};

In the config I am leveraging a promoted attribute as a setting to determine if the user wants syntax highlighting to occur and having the default be true. Everything else in the config should be pretty straightforward.

The last step was to make use of the setting, which was as easy as checking api.startNote.getLabel. Since I already installed the types package, it warns me that this can return null when the label doesn't exist, so we end up with something like this.

So now to build a release ready for users I just run npm run pack and send them the newly created zip file. Or in the case of a GitHub release, I upload it to the release. And now I don't have to worry about any extra stuff in my own Trilium tree I was testing with.

Conclusion

I honestly have no clue if this post or these tools will help anyone, but I hope they do! I think Trilium itself is an awesome tool and I like the idea of improving the development environment for those contributing to the community. I also hope that these tools can help improve the quality of addons for users, by helping to catch bugs via type checking, or by adding settings via promoted attributes and distributing as a zip file.

If anyone has any questions or thoughts or anything, please don't hesitate to post them below! I'm always open to improving these tools and even making more tools if other people find some other shortcoming during their addon development.

[sottey]

I love this post! All great ideas.

The only other pain point I am experiencing is for testing. I am thinking on creating some kind of Trilium native test harness which would allow a developer to do stuff when the script to be tested is executed that:

• Creates a temp tree test structure, putting in predefined data into the created notes
• Calls another script which is for test scaffolding

If I were to get SUPER crazy (and probably divorced), It would be super cool to have a developer pack for Trilium that you drop in which adds all of the tech that you mention as well as testing capabilities, maybe even leveraging diagrams to visually build the execution/test flow of the target code.

Thanks for writing this up!
Sean

[zerebos]

Glad to write it up, hopefully you can get some use out of it!

Yeah full end-to-end testing like that would be nice, but a lot lot lot of work, and I'm not quite crazy enough to tackle that... for now. So I'll just stick to unit testing like I'm doing currently since that still covers a lot of cases and potential bugs.

[zadam]

I appreciate all the effort and thought coming into this. I'm aware that the addon development is far from ergonomic, but so far I wasn't able to address - partly because of lack of inspiration, partly because of the prioritization.

Eventually I'd like to address the "remote" part natively in Trilium where you'd be able to mark a subtree as mounted to a filesystem and there would be a two-way sync. This would be useful for addon development, but also few other things. I still don't know when and how exactly this would be done ...

[zerebos]

Well I'm definitely willing to lend as much of a hand as you'd like for both inspiration and time/implementation. I've had the misfortune of making addon systems of my own for other projects I work on so hopefully I can make use of that experience here.

A 2-way mount into the filesystem would be cool, very curious what other use-cases you imagine for it.