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

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

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 folder
ln -sfn "$PLUGIN_DIR" "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID"

# Verify
ls -la "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID/manifest.json"
echo "Symlinked $PLUGIN_ID into dev vault."

On Windows, use an admin terminal:

mklink /D "%USERPROFILE%\ObsidianDev\.obsidian\plugins\my-plugin" "%cd%"

Step 4: Run esbuild in watch mode

Watch mode rebuilds

main.js

npm run dev
# esbuild watches src/ and rebuilds main.js on save
# Output: "build finished" messages in the terminal

The

esbuild.config.mjs

Step 5: Hot-reload in Obsidian

After esbuild rebuilds, reload the plugin in Obsidian:

Method A -- Keyboard (fastest): Press

Ctrl+R

Cmd+R

main.js

Method B -- Hot Reload plugin (automatic): Install the Hot Reload community plugin. It watches for

main.js

1. In Obsidian, install "Hot Reload" from Community plugins
2. Enable it
3. Create a

   .hotreload

   file in your plugin directory:

   touch .hotreload

4. Now every esbuild rebuild triggers an automatic plugin reload

Method C -- Command palette: Press

Ctrl+P

Step 6: Debug with Chrome DevTools

Obsidian is an Electron app, so full Chrome DevTools are available.

1. Press

   Ctrl+Shift+I

   (or

   Cmd+Option+I

   on macOS) to open DevTools
2. Console tab -- see

   console.log

   output from your plugin
3. Sources tab -- set breakpoints in your code (source maps required)
4. Network tab -- inspect any HTTP requests your plugin makes
5. 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

set -euo pipefail
npm install --save-dev vitest

Create

vitest.config.ts

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
  },
});

Create a mock for the obsidian module at

__mocks__/obsidian.ts

export class Plugin {
  app = {};
  loadData = vi.fn().mockResolvedValue({});
  saveData = vi.fn().mockResolvedValue(undefined);
  addCommand = vi.fn();
  addRibbonIcon = vi.fn();
  addSettingTab = vi.fn();
  addStatusBarItem = vi.fn().mockReturnValue({ setText: vi.fn() });
  registerEvent = vi.fn();
  registerInterval = vi.fn();
}

export class Notice {
  constructor(public message: string) {}
}

export class PluginSettingTab {
  containerEl = { empty: vi.fn(), createEl: vi.fn() };
  constructor(public app: any, public plugin: any) {}
  display() {}
}

export class Setting {
  constructor(el: any) {}
  setName = vi.fn().mockReturnThis();
  setDesc = vi.fn().mockReturnThis();
  addText = vi.fn().mockReturnThis();
  addToggle = vi.fn().mockReturnThis();
}

export class Modal {
  app: any;
  contentEl = { createEl: vi.fn(), empty: vi.fn() };
  constructor(app: any) { this.app = app; }
  open = vi.fn();
  close = vi.fn();
  onOpen() {}
  onClose() {}
}

Write a test:

// src/__tests__/main.test.ts
import { describe, it, expect, vi } from "vitest";

vi.mock("obsidian");

describe("Plugin settings", () => {
  it("merges defaults with saved data", async () => {
    const { Plugin } = await import("obsidian");
    const { default: MyPlugin } = await import("../main");

    const plugin = new MyPlugin() as any;
    plugin.loadData = vi.fn().mockResolvedValue({ greeting: "Custom" });
    plugin.saveData = vi.fn();

    await plugin.loadSettings();

    expect(plugin.settings.greeting).toBe("Custom");
    expect(plugin.settings.showRibbon).toBe(true); // default preserved
  });
});

Run tests:

npx vitest run           # single run
npx vitest --watch       # watch mode alongside npm run dev

Add to

package.json

{
  "scripts": {
    "dev": "node esbuild.config.mjs",
    "build": "node esbuild.config.mjs production",
    "test": "vitest run",
    "test:watch": "vitest --watch"
  }
}

Output

After completing all steps:

• Dev vault at

  ~/ObsidianDev

  with test notes
• Plugin symlinked into vault (no manual copying)

• npm run dev

  for sub-second rebuilds on save
• Hot Reload plugin for automatic Obsidian reload (or Ctrl+R manual)
• Chrome DevTools available via Ctrl+Shift+I with source maps
• vitest configured with obsidian mocks for unit testing
• Two-terminal workflow: terminal 1 runs

  npm run dev

  , terminal 2 runs

  npx vitest --watch

Error Handling

ls -la

.hotreload

touch .hotreload

sourcemap: false

sourcemap: "inline"

build

dev

npm run dev

__mocks__/obsidian.ts

Examples

Quick dev startup script (

dev.sh

#!/usr/bin/env bash
set -euo pipefail

# Terminal 1: esbuild watch
npm run dev &
ESBUILD_PID=$!

# Terminal 2: vitest watch
npx vitest --watch &
VITEST_PID=$!

echo "Dev servers running. Ctrl+C to stop."
trap "kill $ESBUILD_PID $VITEST_PID" EXIT
wait

VSCode task for integrated dev:

{
  "version": "2.0.0",
  "tasks": [{
    "label": "Obsidian Dev",
    "type": "npm",
    "script": "dev",
    "isBackground": true,
    "problemMatcher": {
      "pattern": { "regexp": "^x]$" },
      "background": {
        "activeOnStart": true,
        "beginsPattern": ".",
        "endsPattern": "build finished"
      }
    }
  }]
}

Resources

• Obsidian Sample Plugin
• Obsidian Development Workflow
• Hot Reload Plugin
• esbuild Watch Mode
• Vitest Documentation

Next Steps

• Build UI features: see

  obsidian-core-workflow-b

• Apply production patterns: see

  obsidian-sdk-patterns