Set up a fast Obsidian plugin development loop with hot reload.
Covers cloning the sample plugin, esbuild watch mode, symlinking
into a vault, Ctrl+R hot reload, Chrome DevTools debugging, and
testing with vitest. Use when starting plugin development or
configuring a dev environment.
Trigger with "obsidian dev loop", "obsidian hot reload",
"obsidian development setup", "develop obsidian plugin".
Set up a fast Obsidian plugin development loop with hot reload.
Covers cloning the sample plugin, esbuild watch mode, symlinking
into a vault, Ctrl+R hot reload, Chrome DevTools debugging, and
testing with vitest. Use when starting plugin development or
configuring a dev environment.
Trigger with "obsidian dev loop", "obsidian hot reload",
"obsidian development setup", "develop obsidian plugin".
Designed for Claude Code, also compatible with Codex and OpenClaw
Obsidian Local Dev Loop
Overview
Establish a fast edit-build-test cycle for Obsidian plugins. Clone the official
sample plugin, run esbuild in watch mode, symlink into a dev vault, hot-reload
with Ctrl+R, debug with Chrome DevTools, and run tests with vitest. Aimed at
sub-second feedback from save to reload.
Prerequisites
Node.js 18+ with npm
Git
Obsidian desktop app installed
A vault dedicated to development (keep it separate from your real notes)
Instructions
Step 1: Clone the official sample plugin
Start from the maintained template rather than from scratch:
set -euo pipefail
git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-plugin
cd my-plugin
rm -rf .git
git init
npm install
The sample includes esbuild.config.mjs, tsconfig.json, manifest.json, and
a working src/main.ts.
Step 2: Create a dedicated dev vault
Keep a vault just for testing. Pre-populate it with sample notes.
set -euo pipefail
DEV_VAULT="$HOME/ObsidianDev"mkdir -p "$DEV_VAULT/.obsidian/plugins"mkdir -p "$DEV_VAULT/Test Notes"cat > "$DEV_VAULT/Test Notes/Sample.md" << 'EOF'
---
tags: [test, sample]
---
# Sample Note
This note exists for plugin development testing.
## Section A
Some content with a [[link]] and a #tag.## Section B
- Item 1
- Item 2
- Item 3
EOF
echo"Dev vault ready at $DEV_VAULT"
Open this vault in Obsidian: File > Open vault > select .
~/ObsidianDev
Step 3: Symlink the plugin into the dev vault
Instead of copying files after every build, symlink the entire project directory.
The build outputs main.js at the project root, right where Obsidian expects it.
set -euo pipefail
DEV_VAULT="$HOME/ObsidianDev"
PLUGIN_DIR="$(pwd)"
PLUGIN_ID=$(node -e "console.log(require('./manifest.json').id)")
# Symlink project root into vault plugins folderln -sfn "$PLUGIN_DIR""$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID"# Verifyls -la "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID/manifest.json"echo"Symlinked $PLUGIN_ID into dev vault."
Watch mode rebuilds main.js on every source file change (typically <50ms).
npm run dev
# esbuild watches src/ and rebuilds main.js on save# Output: "build finished" messages in the terminal
The esbuild.config.mjs from the sample plugin already supports this.
Inline source maps are enabled in dev mode for accurate stack traces.
Step 5: Hot-reload in Obsidian
After esbuild rebuilds, reload the plugin in Obsidian:
Method A -- Keyboard (fastest):
Press Ctrl+R (or Cmd+R on macOS) to reload the app. This unloads all plugins
and reloads them, picking up the new main.js.
Method B -- Hot Reload plugin (automatic):
Install the Hot Reload community plugin.
It watches for main.js changes in plugin directories and auto-reloads only the
changed plugin. No manual refresh needed.
In Obsidian, install "Hot Reload" from Community plugins
Enable it
Create a .hotreload file in your plugin directory: touch .hotreload
Now every esbuild rebuild triggers an automatic plugin reload
Method C -- Command palette:
Press Ctrl+P, type "Reload app without saving", Enter.
Step 6: Debug with Chrome DevTools
Obsidian is an Electron app, so full Chrome DevTools are available.
Press Ctrl+Shift+I (or Cmd+Option+I on macOS) to open DevTools
Console tab -- see console.log output from your plugin
Sources tab -- set breakpoints in your code (source maps required)
Network tab -- inspect any HTTP requests your plugin makes
Elements tab -- inspect Obsidian's DOM for CSS/layout work
Tips:
With inline source maps enabled, your TypeScript source appears in Sources > src/main.ts
Use debugger; statements in code for precise breakpoints
console.log('[MyPlugin]', ...) prefix makes filtering easy
// Add to onload() for development:if (process.env.NODE_ENV !== "production") {
console.log("[MyPlugin] Dev mode active. Use Ctrl+Shift+I for DevTools.");
}
Step 7: Testing with vitest
Obsidian plugins can be unit-tested by mocking the obsidian module.
