Obsidian API

The obsidian npm package is the official TypeScript type-definitions package for the Obsidian note-taking app’s plugin API, published by Obsidian’s own team. It ships obsidian.d.ts (the core App/Vault/Workspace/MetadataCache/Plugin type surface), plus canvas.d.ts and publish.d.ts for Canvas and Obsidian Publish extensions, giving plugin authors full IntelliSense and compile-time type checking against the real, versioned Obsidian API.

It is not a runtime library — there’s no bundled implementation to import and execute — it is a types-only package (main: "", types: "obsidian.d.ts") that plugin developers install alongside a bundler (Rollup, Webpack, esbuild) to compile a main.js that Obsidian loads via require('obsidian') at runtime, with the actual API implementation supplied by the running Obsidian application itself.

What You Get

• Full TypeScript typings (obsidian.d.ts, ~8,500 lines) for the App, Vault, Workspace, MetadataCache, and Plugin base class APIs
• Additional typings for Obsidian Canvas (canvas.d.ts) and Obsidian Publish (publish.d.ts) extension surfaces
• Documented plugin structure conventions (manifest.json fields, main.js entry point contract) in the README
• Guidance on event registration patterns (this.registerEvent) that automatically detach handlers on plugin unload
• Compile-time type safety when building against require('obsidian') at runtime, with the real implementation supplied by the Obsidian app

Common Use Cases

• Building an Obsidian community plugin with full IntelliSense/autocomplete against the App, Vault, and Workspace APIs
• Adding UI extensions to Obsidian — ribbon icons, status bar items, commands, settings tabs, custom views — with typed constructors
• Reading and reacting to Obsidian’s MetadataCache (headings, links, tags, embeds) for plugins that analyze or index a vault
• Building Obsidian Canvas or Obsidian Publish integrations using the dedicated canvas.d.ts/publish.d.ts typings
• Type-checking a plugin’s use of Obsidian’s event system to ensure handlers are correctly registered and cleaned up

Under The Hood

Architecture: The package is purely declarative — obsidian.d.ts types the App/Vault/Workspace/MetadataCache module graph and the abstract Plugin base class plugin authors extend, canvas.d.ts types the Canvas JSON-based node/edge API, and publish.d.ts types Obsidian Publish-specific extension points. There is no compiled JavaScript implementation in this package; at runtime, a plugin’s bundled main.js calls require('obsidian'), which the actual Obsidian desktop/mobile app resolves to its own internal implementation — this package exists solely to type-check against that contract during development.

Tech Stack: A minimal npm package with types: "obsidian.d.ts" and no main entry, depending on @types/codemirror and moment (Obsidian bundles Moment.js for date handling) as dependencies, with @codemirror/state and @codemirror/view as peer dependencies reflecting Obsidian’s CodeMirror 6-based editor.

Code Quality: Maintained directly by the Obsidian team (obsidianmd org) with a CHANGELOG.md tracking API additions release-over-release, and versioned in lockstep with the Obsidian app itself (published under MIT license). As a hand-maintained types package (not auto-generated), correctness depends on the Obsidian team keeping it in sync with the real API, which the project’s active update cadence supports.

API Design: The typing surface directly mirrors Obsidian’s actual runtime API, so there’s no separate abstraction to learn beyond the Obsidian plugin API itself — the official obsidian-sample-plugin template (linked from the README) plus this package’s types together form the standard on-ramp for new plugin authors, and the forum-based issue/feature-request process gives a clear channel for API gaps.