How to debug Obsidian plugins

Hi folks

I am using Obsidian on a daily basis and sometimes I need to investigate some plugin behavior.

I would like to share some tricks. Some of them I even discovered on my own, as I could not find them by googling.

Developer Tools

As Obsidian is an Electron app, it’s essentially the wrapper on Google Chrome, so if you know how to debug things there, you already know the most essential parts.

Just press Ctrl + Shift + I and you will open Developer Tools.

Plugin ID

Your plugin logic resides in [Vault Path]\.obsidian\plugins\[Plugin ID]\main.js

Usually if you know the plugin name, it’s simple to to find the Plugin ID but if it is not the case, just go to Settings > Community Plugins > [Plugin Name] .> Copy share link

And the link looks like obsidian://show-plugin?id=[Plugin Id]

Debug without sources

Plugins are loaded dynamically using eval JavaScript function, therefore it is impossible to search for the plugin code during execution in Sources pane in Developer Tools.

So this requires a little trick. Go to Developer Tools and type in the console

app.plugins.plugins["[Plugin ID]"].constructor

Here obviously [Plugin ID] has to be replaced with the real Plugin ID.

As the result you will get a function in the console

If you click on that function, you will be redirected to the Sources pane with the code of eval-ed plugin.

Here you can debug normally, set breakpoints etc.

If you want to make permanent changes you can modify [Vault Path]\.obsidian\plugins\[Plugin ID]\main.js accordingly.

TypeScript sources

Actually the main language for Obsidian plugins is TypeScript. It is being later on compiled into JavaScript [Vault Path]\.obsidian\plugins\[Plugin ID]\main.js.

For more advanced changes, dealing with compiled JavaScript is troublesome. Async functions are being compiled into JavaScript generator functions. Overall, the experience is not as pleasant.

To get TypeScript sources you have to find [plugin-repo-url]

git clone [plugin-repo-url]
cd [plugin-dir]
npm install # installs all the dependencies required to compile the plugin
npm run dev # start the daemon that watches changes in the TypeScript source code and compiles them into main.js

Then you can make your changes, main.js will be automatically recompiled every time you save TypeScript changes.

When you are done, copy main.js into [Vault Path]\.obsidian\plugins\[Plugin ID]\main.js

Reload changed plugin

You have multiple ways to reload the plugin after changes

  1. Just restart Obsidian app.
  2. Manually turn on and off the plugin

  1. Reload all plugins at once

  1. Reload via code in Developer Tools console.
await app.plugins.disablePlugin("[Plugin ID]");
await app.plugins.enablePlugin("[Plugin ID]");
  1. Use Hot Reload plugin

Hot Reload plugin automatically reloads plugins under certain conditions. See its documentation.

Also note that this plugin doesn’t exist in the standard community plugins registry, so it has to be installed manually.

Hopefully this guide will help you to master Obsidian plugins. Don’t forget to send pull requests if you made useful changes to the plugins.

Stay tuned.

%d bloggers like this: