obsidianmd/obsidian-api

Type definitions for the latest Obsidian API.

Summary

The obsidianmd/obsidian-api repository provides TypeScript type definitions for the Obsidian note-taking application's plugin API. It serves as the official type package that plugin developers import when extending Obsidian. The project is released under the MIT license and is maintained by the Obsidian team.

What it is useful for

This repository is useful for developers building Obsidian plugins who want type checking and IDE autocomplete against the plugin API surface. The README documents the major modules that the types describe: App (the global object accessible as this.app inside a plugin), Vault (for interacting with files and folders in the vault), Workspace (for interacting with panes on the screen), and MetadataCache (which holds cached metadata about each markdown file, including headings, links, embeds, tags, and blocks).

The README also documents the contract a plugin's main.js must follow, including that it export a default class extending Plugin and that all external dependencies be bundled in. Through inheritance from Plugin, the types cover adding ribbon icons (this.addRibbonIcon), status bar items (this.addStatusBarItem), global commands (this.addCommand), settings tabs (this.addSettingTab), and views (this.registerView), along with persisting data via this.loadData and this.saveData. It also documents event registration patterns intended to keep handlers scoped to the plugin's lifetime.

How engineers can use it

The README does not document a specific install command; it points engineers to the Plugin API documentation at https://docs.obsidian.md/ and to the sample plugin at https://github.com/obsidianmd/obsidian-sample-plugin for a working starting point. The documented pattern for importing the API inside a plugin's main.js is require('obsidian'), with NodeJS or Electron APIs imported via require('fs') or require('electron'), and external dependencies bundled using Rollup, Webpack, or another JavaScript bundler.

The README lists the manifest.json fields a plugin must declare: id, name, author, version, minAppVersion, description, and isDesktopOnly, plus optional authorUrl and fundingUrl. For event handling, the documented pattern is to wrap app and workspace events with this.registerEvent, persist DOM listeners with this.registerDomEvent (for elements that outlive the plugin, such as window or document), and wrap timers with this.registerInterval so they are released when the plugin unloads. Bug reports and new API requests are routed to the Obsidian forum at https://forum.obsidian.md/c/developers-api/14 rather than GitHub Issues, which is a documented limitation of where feedback can be filed.