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)#

#RuleWhy1Never use global app — use this.appGlobal app breaks in multi-window; submission rejected2Never use innerHTML/ outerHTML — use createEl(), createDiv(), setText()XSS vulnerability; instant rejection3Use registerEvent() for all event subscriptionsAuto-cleanup on unload; prevents memory leaks4No default hotkeys — let users configureHotkey conflicts with other plugins5Use requestUrl() over fetch()Bypasses CORS; works on mobile6Use normalizePath() for user-provided pathsHandles cross-platform path differences7Prefer vault.process() over vault.modify()Atomic operation; safe with concurrent edits8Use FileManager.processFrontMatter() for YAMLNever parse/serialize YAML manually9Use Sentence case for all UI textObsidian convention; submission requirement10Use setHeading() not <h1>/ <h2>Semantic; supports RTL; submission requirement11Import only what you use — no unused classesCleaner code; easier audits; submission reviewers check this12Use checkCallback when command depends on contextcallback = always available; checkCallback = conditionally shown; editorCallback = needs editor13Always provide .theme-dark / .theme-light CSS variantsObsidian CSS vars auto-adapt, but explicit theme blocks ensure edge cases render correctly; submission reviewers check this14No regex lookbehind — (?!...) OK, (?<=...) NOT OKBreaks on iOS Safari < 16.4; submission rejected15All interactive elements keyboard accessibleTab navigation + Enter/Space; submission requirement16ARIA labels on all icon-only buttonsScreen reader support; submission requirement17Touch targets ≥ 44×44pxMobile usability; submission requirement18Use vault.configDir not .obsidianCross-platform compatibility; submission requirement19Use fileManager.trashFile() not vault.delete()Respects user trash settings20Use AbstractInputSuggest not TextInputSuggestBuilt-in API; Liam's copy-pasted implementation is banned21Create versions.json — maps plugin version → min Obsidian versionSubmission bot checks for it; auto-reject if missing22Version your settings schema — _settingsVersion fieldEnables migration pipeline on upgrade; prevents data loss

Quick Reference#

Plugin Lifecycle#

typescript

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#

NeedAPIGet active filethis.app.workspace.getActiveFile()Read filethis.app.vault.cachedRead(file)Modify file (background)this.app.vault.process(file, (data) => data)Modify file (editor)editor.replaceSelection(), editor.getRange()Create filethis.app.vault.create(path, content)Delete filethis.app.fileManager.trashFile(file)Rename filethis.app.fileManager.renameFile(file, newPath)Read frontmatterthis.app.metadataCache.getFileCache(file)?.frontmatterWrite frontmatterthis.app.fileManager.processFrontMatter(file, (fm) => {})Show notificationnew Notice('message', duration)Open modalnew MyModal(this.app).open()Get active editorthis.app.workspace.activeEditor?.editorPlatform checkPlatform.isMacOS, Platform.isMobile, Platform.isDesktopNetwork requestrequestUrl({ url, method, headers, body })Persist datathis.loadData() / this.saveData(data)Secure storagethis.app.secretStorage.setSecret(id, value) (v1.11.4+)Detect themedocument.body.classList.contains('theme-dark')

Command Callback Decision Tree#

text

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:

typescript

// 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.

typescript

// 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#

TopicFileWhen to LoadLifecycle & Core APIreference/lifecycle.mdAlways; building any plugin featureESLint Rules (28 rules)reference/eslint-rules.mdESLint setup, pre-submission audit, rule referenceAccessibility (MANDATORY)reference/accessibility.mdKeyboard nav, ARIA labels, focus indicators, touch targetsCodeMirror 6 Editor Extensionsreference/editor-extensions.mdEditor decorations, syntax highlighting, live previewReact / Svelte / Vue Integrationreference/frameworks.mdUsing React/Vue/Svelte in views or settingsVault & File Operationsreference/vault-operations.mdFile CRUD, frontmatter, events, cachingSettings & Data Migrationreference/settings-migration.mdSettings UI, load/save, deep merge, migration pipelinesSecurity & SecretStoragereference/security.mdAPI keys, credentials, XSS prevention, network requestsCSS Stylingreference/css-accessibility.mdTheming, CSS variables, scoping, mobile stylesDev Workflow & CLIreference/dev-workflow.mdBuild, hot-reload, CLI debugging, Obsidian CLI, ESLint configTestingreference/testing.mdUnit tests, mocking Obsidian API, Jest/VitestCI/CD & Releasereference/cicd-release.mdGitHub Actions, version bump, community submission

Development Workflow#

Quick Dev Loop (with Obsidian CLI)#

bash

# 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#

bash

# 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#

Reference FilePrimary SourcesLast Verifiedlifecycle.mdobsidian API docs, gapmiss/obsidian-plugin-skill2026-03eslint-rules.mdobsidianmd/eslint-plugin v0.1.9, gapmiss/obsidian-plugin-skill2026-03accessibility.mdgapmiss/obsidian-plugin-skill, obsidian plugin guidelines2026-03editor-extensions.mdCM6 docs, @codemirror/view source2026-03frameworks.mdLeonezz/obsidian-plugin-dev-skill, React docs2026-03vault-operations.mdobsidian API docs, official plugin guidelines2026-03settings-migration.mdLeonezz/obsidian-plugin-dev-skill2026-03security.mdgapmiss/obsidian-plugin-skill, obsidian developer policies2026-03css-accessibility.mddavidvkimball/obsidian-dev-skills, obsidian sample theme2026-03dev-workflow.mdadriangrantdotorg/Obsidian-Skills, obsidian CLI docs2026-03testing.mdLeonezz/obsidian-plugin-dev-skill2026-03cicd-release.mdLeonezz/obsidian-plugin-dev-skill, obsidian submission docs2026-03

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