Home    |    GitHub Page    |    API    |    FAQ

Help installing plugins?

Hi, was starting to dig in to the new plugins (with the hope that I could build off a basic one), so I figured I'd test one out first to see how they worked. Wasn't able to get it working, so I thought I'd share the steps I took in case it helps with documentation. I read some of the developer tutorial and this page https://joplinapp.org/plugins/

What I tried (attempting to get the TOC working)

  1. Copied code to a toc folder inside a plugin folder inside joplin-desktop.

  2. It was unclear what files I needed, especially since the readme seems to be boilerplate. Tried the 4 from the src file and the whole folder. Neither worked after restarting.

  3. Tried setting an explicit development plugin path in Preferences.

Joplin 1.3.2 (prod, darwin) Mac

Sorry if I'm missing something obvious, excited to play with plugins.

Hi @uxamanda,

Looking at the plugin getting started document, I think you always need to specify the plugin path (which I can see you tried). And the folder in the path needs to contain a dist folder with the compiled plugin. I think you missed the compilation step. It looks like a few of the example plugins are already compiled but not the toc example.
You can find the build steps in the getting started document I linked above.

Sorry for not being more detailed, I just have my phone right now and couldn't confirm any of what I'm saying. I have played around with plugins already though (they do work), but I'm a bit fuzzy on the details. I hope you can get the plugins running on your computer!

Besides what Caleb mentioned, perhaps one issue is that the directory should be called "plugins" and not "plugin".

Also as the details are still being worked on, the best way for now to load a plugin is to add it to the "Plugins" section in the Config screen. When it's loaded that way it will display a console on startup which might help understand what's happening.

Is it possible to add more than one plugin this way?

Haven't tried it myself yet, but looks like you can have multiple paths with a comma between.

Thanks for the help, I got the toc plugin to work :slight_smile:


  1. I saw the note about a dist and promptly forgot. Running npm run dist in the folder worked. It prompted me to install the required webpack-cli automatically.

  2. Added the path to preferences. My folder was named plugins, mistyped it here. The path ended up being /Users/<user>/.config/joplin-desktop/plugins/toc.

Note: it would be helpful to be able to copy and paste into the path input field. For some reason it's blocked, at least on Mac.

Thanks for the help, I will start playing around.

1 Like

Can this field accept a relative path to a folder within the profile directory? Any examples I have seen have all been absolute paths. I could only get your "SideBarToggle" plugin working on Windows 10 with an absolute path but that's a bit awkward for the portable version.

Currently not as this field is mostly for development, where you expect the plugin to be always in the same place. Otherwise, you can simply put the plugin in the "plugins" directory and it will be auto-loaded when the app starts and that should work with the portable app too.

1 Like

Much obliged for clearing that up. Makes perfect sense.

So how do I autoload more than one plugin? Do I have to create subdirectories for each plugin?

Suggested implementation: Drag and drop the zip package (or select from the file manager in Joplin) to automatically complete the installation, otherwise the process is still too troublesome @laurent

Yes, and I should document the loading logic somewhere. Currently it will load these files:

  • plugins/FILE.js
  • plugins/SUBDIR/FILE.js
  • plugins/SUBDIR/dist/FILE.js
  • Any directory or file that starts with "_" will be excluded (convenient to quickly disable a plugin)

SUBDIR and FILE can be any arbitrary string.

1 Like

Great, thanks. So, if plugins/FILE.js is found, it won't load plugins/SUBDIR/FILE.js or will the second override the first and so on?
Usually that shouldn't be a problem, since SUBDIR should have the .ts files and the dist dir the js files.
But it could still happen...

Cool thing with the underscore. :+1:

Everything that is found will be loaded. So for example, if you have this structure:


it will load all the above files.

Ok, this means something like this will most likely result in an error:


Because you can't register the same plugin twice. It's not a problem, just something people should be aware of.
Depending on the algorithm, plugins/toc/index.js is loaded and plugins/toc/dist/index.js will be a silent error, thus the first one is active.
Or it could mean that plugins/toc/dist/index.js overwrites plugins/toc/index.js and thus the second one is active.