Set up Obsidian plugin development environment with Node.js and TypeScript.
Use when starting a new plugin project, configuring the dev environment,
or initializing Obsidian plugin development from scratch.
Trigger with phrases like "obsidian setup", "obsidian plugin dev",
"create obsidian plugin", "obsidian development environment".
Set up Obsidian plugin development environment with Node.js and TypeScript.
Use when starting a new plugin project, configuring the dev environment,
or initializing Obsidian plugin development from scratch.
Trigger with phrases like "obsidian setup", "obsidian plugin dev",
"create obsidian plugin", "obsidian development environment".
Designed for Claude Code, also compatible with Codex and OpenClaw
Obsidian Install & Auth
Overview
Set up a complete Obsidian plugin development environment: clone the official sample plugin, install TypeScript + esbuild, configure a dev vault with symlink, verify the build pipeline, and establish the manifest.json / versions.json contract.
set -euo pipefail
# Clone the maintained template — includes esbuild, tsconfig, and a working main.ts
git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-obsidian-plugin
cd my-obsidian-plugin
# Start fresh git historyrm -rf .git
git init
git add -A
git commit -m "initial scaffold from obsidian-sample-plugin"
The sample plugin includes these key files:
esbuild.config.mjs — bundler with watch mode and external handling
tsconfig.json — TypeScript config targeting ES2018 with strict null checks
manifest.json — plugin metadata Obsidian reads at load time
src/main.ts — Plugin subclass with commands, settings, modal
Step 2: Install Dependencies
set -euo pipefail
npm install
# What gets installed:# - obsidian (type definitions only — the runtime is provided by the Obsidian app)# - typescript# - esbuild (fast bundler, <50ms builds)# - @types/node# - tslib (TypeScript helper library)
Step 3: Configure manifest.json
Every Obsidian plugin requires a manifest.json at the project root:
id must be lowercase kebab-case, match the folder name under .obsidian/plugins/
minAppVersion should be 1.5.0 or higher (supports modern APIs like processFrontMatter)
isDesktopOnly: false unless you use Electron-only APIs (child_process, fs, shell)
Step 4: Create versions.json
Maps each plugin version to the minimum Obsidian version it requires:
{"1.0.0":"1.5.0"}
Obsidian uses this to warn users on older versions that they cannot install your plugin. Update it every time you bump version in manifest.json.
Step 5: Create a Development Vault
set -euo pipefail
DEV_VAULT="$HOME/ObsidianDev"mkdir -p "$DEV_VAULT/.obsidian/plugins"mkdir -p "$DEV_VAULT/Test Notes"# Create a sample note for testingcat > "$DEV_VAULT/Test Notes/Sample.md" << 'EOF'
---
tags: [test, sample]
status: draft
---
# Sample Note
Test note for plugin development. Has [[wikilinks]], #tags, and frontmatter.## Section A
Some content with **bold** and `inline code`.
## Section B
- [ ] Task one
- [x] Task two
- [ ] Task three
EOF
echo"Dev vault created at $DEV_VAULT"
Open this vault in Obsidian: File > Open vault > select ~/ObsidianDev.
Step 6: Symlink Plugin into Dev Vault
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"
set -euo pipefail
# Production build
npm run build
ls -la main.js manifest.json
echo"Build output: $(wc -c < main.js) bytes"# Start dev mode with file watching
npm run dev
# esbuild watches src/ and rebuilds main.js on every save (~30ms)
In Obsidian:
Settings > Community plugins > Enable community plugins
Find your plugin in the list, toggle it on
Open Developer Console (Ctrl+Shift+I) — look for your plugin's load message
