Skip to main content
This guide will walk you through installing the Obsidian API types and setting up a new plugin project.

​
Installing the API Types

The Obsidian API package provides TypeScript type definitions that you’ll use when building your plugin. 
npm install obsidian --save-dev
The obsidian package should be installed as a dev dependency since it only provides type definitions. The actual Obsidian runtime will be available when your plugin runs inside the app.

​
Package Details

The package includes:
  • Version: 1.12.3 (follows Obsidian’s release cycle)
  • Main Types: obsidian.d.ts
  • Dependencies:
    • @types/codemirror - CodeMirror 5 types
    • moment - Date/time library types
  • Peer Dependencies:
    • @codemirror/state (6.5.0) - CodeMirror 6 state
    • @codemirror/view (6.38.6) - CodeMirror 6 view

​
Using the Sample Plugin Template

The easiest way to start building a plugin is to use the official sample plugin template:
1

Clone the template

git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-plugin
cd my-plugin
2

Install dependencies

The template already includes obsidian and all necessary build tools.
npm install
3

Build the plugin

npm run dev
This starts a watcher that automatically rebuilds when you make changes.

Sample Plugin Template

The official template includes TypeScript, esbuild configuration, and example code to get you started quickly.

​
Setting Up From Scratch

If you prefer to set up your project manually:
1

Initialize your project

mkdir my-obsidian-plugin
cd my-obsidian-plugin
npm init -y
2

Install dependencies

npm install --save-dev obsidian typescript esbuild
3

Configure TypeScript

Create a tsconfig.json file:
{
  "compilerOptions": {
    "target": "ES2021",
    "module": "ESNext",
    "lib": ["ES2021", "DOM"],
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": ".",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"]
}
4

Create manifest.json

Every plugin needs a manifest.json file:
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "0.15.0",
  "description": "A description of my plugin",
  "author": "Your Name",
  "authorUrl": "https://yourwebsite.com",
  "isDesktopOnly": false
}
5

Create your plugin

Create src/main.ts with a basic plugin:
import { Plugin } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    console.log('Loading my plugin');
  }
  
  onunload() {
    console.log('Unloading my plugin');
  }
}

​
TypeScript Configuration

Key TypeScript settings for Obsidian plugins:
  • target: Use ES2021 or later for modern JavaScript features
  • module: Set to ESNext for ES module syntax
  • lib: Include ES2021 and DOM for standard APIs
  • moduleResolution: Use node for npm package resolution
  • strict: Enable strict type checking (recommended)
Make sure strict mode is enabled in your TypeScript config to catch potential errors early and take full advantage of the type safety provided by the Obsidian API.

​
Build Configuration

You’ll need a bundler to package your plugin. The sample plugin template uses esbuild for fast builds: 
require('esbuild').build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  external: ['obsidian'],
  format: 'cjs',
  target: 'es2021',
  outfile: 'main.js',
  watch: process.argv.includes('--watch'),
}).catch(() => process.exit(1));
The obsidian package must be marked as external in your bundler config since it’s provided by the Obsidian app at runtime.

​
File Structure

A typical plugin project structure: 
my-plugin/
├── src/
│   └── main.ts          # Main plugin code
├── manifest.json        # Plugin manifest
├── package.json         # npm dependencies
├── tsconfig.json        # TypeScript config
├── esbuild.config.js    # Build configuration
└── main.js              # Compiled output

​
Next Steps

Now that you have the API types installed, you’re ready to build your first plugin!

Quickstart Guide

Follow our step-by-step guide to create a working plugin with commands and UI elements.

Build docs developers (and LLMs) love

Get started for freeTalk to us