Obsidian Plugin Dev

Obsidian Plugin Development

When This Skill Applies

Use this skill when the user is:

• Creating a new Obsidian plugin from scratch
• Implementing plugin features (commands, views, modals, settings, editor extensions)
• Debugging plugin issues or unexpected behavior
• Configuring build tools (Vite, esbuild, rollup)
• Writing tests for Obsidian plugins
• Setting up CI/CD and release workflows
• Preparing a plugin for community submission
• Working with CodeMirror 6 editor extensions
• Integrating React/Svelte/Vue into Obsidian views

Critical Rules (Always Follow)

Quick Reference

Plugin Lifecycle

import { Plugin } from 'obsidian';

export default class MyPlugin extends Plugin {
	async onload() {
		// 1. Load settings FIRST
		await this.loadSettings();
		// 2. Add settings tab
		this.addSettingTab(new MySettingTab(this.app, this));
		// 3. Register commands
		this.addCommand({ id: 'my-command', name: 'My command', callback: () => {} });
		// 4. Register views
		this.registerView(MY_VIEW_TYPE, leaf => new MyView(leaf));
		// 5. Register editor extensions
		this.registerEditorExtension(myExtension);
		// 6. Register events
		this.registerEvent(this.app.vault.on('modify', file => {}));
		this.registerDomEvent(document, 'click', evt => {});
		this.registerInterval(window.setInterval(() => {}, 1000));
	}

	async onunload() {
		// Resources registered with register*() are auto-cleaned
		// Manual cleanup needed for: MutationObserver, React root, vault.on() in React
	}
}

Essential API Cheatsheet

Command Callback Decision Tree

Does the command need an active editor?
├─ YES → editorCallback
│        (automatically hidden when no editor; gives you editor + view)
│
└─ NO → Does it need any context to run? (active file, leaf, etc.)
         ├─ YES → checkCallback
         │        (return true when available; run action on !checking)
         │
         └─ NO → callback
                  (always visible, always runs)

Examples:

// Always available — no conditions
this.addCommand({
	id: 'open-settings',
	name: 'Open plugin settings',
	callback: () => {
		this.openSettings();
	},
});

// Needs active file — use checkCallback
this.addCommand({
	id: 'copy-stats',
	name: 'Copy note statistics',
	checkCallback: checking => {
		const file = this.app.workspace.getActiveFile();
		if (file) {
			if (!checking) this.copyStats(file);
			return true;
		}
		return false;
	},
});

// Needs editor — use editorCallback
this.addCommand({
	id: 'wrap-callout',
	name: 'Wrap selection in callout',
	editorCallback: editor => {
		const sel = editor.getSelection();
		editor.replaceSelection(`> [!note]\n> ${sel}`);
	},
});

Import Hygiene

Only import what you actually use. Submission reviewers flag unused imports.

// Good — only what's needed
import { MarkdownView, Notice, Plugin, PluginSettingTab, Setting } from 'obsidian';

// Bad — unused imports
import { App, Editor, Modal, Notice, Plugin, PluginSettingTab, Setting } from 'obsidian';
//      ^^^ ^^^^^^ ^^^^^ — never used

Common Pitfalls

1. Storing view references → use getLeavesOfType() on demand
2. Passing plugin as Component → use this.addChild() instead
3. Detaching leaves in onunload → they reinitialize on update
4. Not removing sample code → MyPlugin, SampleSettingTab must be renamed
5. Using vault.modify() on active file → use Editor API instead
6. Manual YAML parsing → use processFrontMatter() instead
7. fetch() for API calls → use requestUrl() instead
8. Hardcoded colors in CSS → use var(--text-normal), etc.
9. navigator.platform → use Platform.isMacOS instead
10. var declarations → use const/let instead
11. Promise chains → use async/await instead
12. console.log in production → remove or use console.debug with conditional
13. Regex lookbehind (?<=...) → breaks on iOS Safari < 16.4; use alternative patterns
14. Object.assign(defaults, saved) → mutates defaults; use Object.assign({}, defaults, saved)
15. Hardcoded .obsidian path → use this.app.vault.configDir instead
16. Shallow merge for nested settings → use deep merge; shallow merge loses nested defaults
17. vault.delete() for removing files → use fileManager.trashFile() to respect user settings
18. Liam's TextInputSuggest → use built-in AbstractInputSuggest instead
19. Missing styles.css → create empty file if no styles (submission bot checks for it)
20. Missing versions.json → create with { "1.0.0": "1.0.0" } (submission bot checks for it)
21. No settings version tracking → add _settingsVersion to settings interface for migration support

Detailed References

Development Workflow

Quick Dev Loop (with Obsidian CLI)

# Build and hot-reload
npm run build && obsidian plugin:reload id=<plugin-id>

# Check for errors
obsidian dev:errors

# Inspect DOM
obsidian dev:dom selector=".my-plugin-view"

# Take screenshot
obsidian dev:screenshot

# Evaluate JS in Obsidian context
obsidian eval code="app.plugins.plugins"

Without Obsidian CLI

# Build and copy to test vault
npm run build && cp main.js manifest.json styles.css /path/to/TestVault/.obsidian/plugins/<plugin-id>/
# Then reload in Obsidian: Ctrl+P → "Reload app without saving"

Pre-Submission Checklist

Before creating a release or submitting to community plugins, verify:

Submission Validation (Bot checks — will auto-reject if incorrect)

• id in manifest.json does not contain "obsidian"; doesn't end with "plugin"; lowercase only
• name does not contain "Obsidian"; doesn't end with "Plugin"; doesn't start with "Obsi" or end with "dian"
• description does not contain "Obsidian" or "This plugin"; must end with .?!) punctuation; max 250 chars
• manifest.json id, name, description match submission entry in community-plugins.json
• LICENSE file present; copyright holder ≠ "Dynalist Inc."; year is current
• styles.css exists (empty if no styles)
• versions.json exists with correct version mapping
• GitHub release has main.js, manifest.json, styles.css attached

Code Quality

• All sample/template code removed (MyPlugin, SampleSettingTab, SampleModal)
• No innerHTML/outerHTML anywhere in code
• No default hotkeys set
• No console.log in production (remove or use conditional console.debug)
• No unused imports
• setHeading() used instead of <h2> in settings
• Sentence case for all UI text (run ESLint to verify)
• this.app used everywhere (not global app)
• All resources cleaned up in onunload()
• No Object.assign(defaults, saved) — use Object.assign({}, defaults, saved)
• Use fileManager.trashFile() not vault.delete()
• No regex lookbehind ((?<=...)) — breaks on iOS
• Use vault.configDir not hardcoded .obsidian

Accessibility (MANDATORY)

• All interactive elements keyboard accessible (Tab, Enter, Space)
• ARIA labels on all icon-only buttons
• :focus-visible styled with Obsidian CSS variables
• Touch targets ≥ 44×44px
• Can use entire plugin without a mouse

ESLint & Release

• ESLint passes with eslint-plugin-obsidianmd (npx eslint .)
• manifest.json version correct, minAppVersion set
• isDesktopOnly: true only if using Node/Electron APIs

Reference Source Tracking

To update references: check each source for new content, cross-reference with obsidian developer docs changelog.

Design Decisions

1. SKILL.md stays under 500 lines — quick reference + links to detailed docs
2. Reference files are topic-based — load only what you need
3. Code examples are real — from actual plugin patterns, not toy demos
4. Do/Don't tables — clear before/after comparisons