obsidian-sdk-patterns

Obsidian SDK Patterns

Overview

Production-ready patterns for Obsidian plugin development in TypeScript.

Prerequisites

• Completed obsidian-install-auth setup
• Familiarity with TypeScript and async/await
• Understanding of Obsidian's plugin lifecycle

Instructions

Step 1: Type-Safe Settings Pattern

// src/settings.ts
import { App, PluginSettingTab, Setting } from 'obsidian';
import type MyPlugin from './main';

export interface MyPluginSettings {
  apiEndpoint: string;
  enableFeatureX: boolean;
  maxItems: number;
  excludedFolders: string[];
}

export const DEFAULT_SETTINGS: MyPluginSettings = {
  apiEndpoint: 'https://api.example.com',
  enableFeatureX: true,
  maxItems: 100,
  excludedFolders: ['templates', 'archive'],
};

export class MyPluginSettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  display(): void {
    const { containerEl } = this;
    containerEl.empty();

    new Setting(containerEl)
      .setName('API Endpoint')
      .setDesc('The API endpoint for fetching data')
      .addText(text => text
        .setPlaceholder('https://api.example.com')
        .setValue(this.plugin.settings.apiEndpoint)
        .onChange(async (value) => {
          this.plugin.settings.apiEndpoint = value;
          await this.plugin.saveSettings();
        }));

    new Setting(containerEl)
      .setName('Enable Feature X')
      .setDesc('Toggle experimental feature')
      .addToggle(toggle => toggle
        .setValue(this.plugin.settings.enableFeatureX)
        .onChange(async (value) => {
          this.plugin.settings.enableFeatureX = value;
          await this.plugin.saveSettings();
        }));

    new Setting(containerEl)
      .setName('Max Items')
      .setDesc('Maximum number of items to display')
      .addSlider(slider => slider
        .setLimits(10, 500, 10)
        .setValue(this.plugin.settings.maxItems)
        .setDynamicTooltip()
        .onChange(async (value) => {
          this.plugin.settings.maxItems = value;
          await this.plugin.saveSettings();
        }));
  }
}

Step 2: Service Layer Pattern

// src/services/vault-service.ts
import { App, TFile, TFolder, Vault } from 'obsidian';

export class VaultService {
  constructor(private app: App) {}

  async getMarkdownFiles(folder?: string): Promise<TFile[]> {
    const files = this.app.vault.getMarkdownFiles();
    if (!folder) return files;

    return files.filter(f => f.path.startsWith(folder));
  }

  async readFile(file: TFile): Promise<string> {
    return this.app.vault.read(file);
  }

  async writeFile(file: TFile, content: string): Promise<void> {
    await this.app.vault.modify(file, content);
  }

  async createFile(path: string, content: string): Promise<TFile> {
    return this.app.vault.create(path, content);
  }

  async ensureFolder(path: string): Promise<TFolder> {
    const folder = this.app.vault.getAbstractFileByPath(path);
    if (folder instanceof TFolder) return folder;

    await this.app.vault.createFolder(path);
    return this.app.vault.getAbstractFileByPath(path) as TFolder;
  }

  getFileByPath(path: string): TFile | null {
    const file = this.app.vault.getAbstractFileByPath(path);
    return file instanceof TFile ? file : null;
  }
}

Step 3: Event Management Pattern

// src/events.ts
import { Plugin, EventRef, Events } from 'obsidian';

export class EventManager {
  private eventRefs: EventRef[] = [];

  constructor(private plugin: Plugin) {}

  register(events: Events, name: string, callback: (...args: any[]) => any): void {
    const ref = events.on(name as any, callback);
    this.eventRefs.push(ref);
    this.plugin.registerEvent(ref);
  }

  registerWorkspaceEvent(name: string, callback: (...args: any[]) => any): void {
    this.register(this.plugin.app.workspace, name, callback);
  }

  registerVaultEvent(name: string, callback: (...args: any[]) => any): void {
    this.register(this.plugin.app.vault, name, callback);
  }

  cleanup(): void {
    // Events are automatically cleaned up by Obsidian
    // But keep track for manual cleanup if needed
    this.eventRefs = [];
  }
}

// Usage in main.ts:
const eventManager = new EventManager(this);
eventManager.registerWorkspaceEvent('file-open', (file) => {
  if (file) console.log('Opened:', file.path);
});
eventManager.registerVaultEvent('modify', (file) => {
  console.log('Modified:', file.path);
});

Step 4: Command Builder Pattern

// src/commands.ts
import { Command, Editor, MarkdownView, Plugin } from 'obsidian';

interface CommandConfig {
  id: string;
  name: string;
  icon?: string;
  hotkeys?: { modifiers: string[]; key: string }[];
}

export class CommandBuilder {
  private commands: Command[] = [];

  constructor(private plugin: Plugin, private prefix: string) {}

  addSimple(config: CommandConfig, callback: () => void): this {
    this.commands.push({
      id: `${this.prefix}-${config.id}`,
      name: config.name,
      icon: config.icon,
      callback,
    });
    return this;
  }

  addEditor(
    config: CommandConfig,
    callback: (editor: Editor, view: MarkdownView) => void
  ): this {
    this.commands.push({
      id: `${this.prefix}-${config.id}`,
      name: config.name,
      icon: config.icon,
      editorCallback: callback,
    });
    return this;
  }

  addCheck(
    config: CommandConfig,
    check: () => boolean,
    callback: () => void
  ): this {
    this.commands.push({
      id: `${this.prefix}-${config.id}`,
      name: config.name,
      icon: config.icon,
      checkCallback: (checking) => {
        if (checking) return check();
        callback();
        return true;
      },
    });
    return this;
  }

  register(): void {
    this.commands.forEach(cmd => this.plugin.addCommand(cmd));
  }
}

// Usage:
new CommandBuilder(this, 'my-plugin')
  .addSimple({ id: 'greet', name: 'Show Greeting' }, () => {
    new Notice('Hello!');
  })
  .addEditor({ id: 'insert', name: 'Insert Text' }, (editor) => {
    editor.replaceSelection('Inserted text');
  })
  .register();

Step 5: Async Queue Pattern

// src/utils/async-queue.ts
export class AsyncQueue {
  private queue: (() => Promise<void>)[] = [];
  private processing = false;

  async add(task: () => Promise<void>): Promise<void> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          await task();
          resolve();
        } catch (e) {
          reject(e);
        }
      });
      this.process();
    });
  }

  private async process(): Promise<void> {
    if (this.processing) return;
    this.processing = true;

    while (this.queue.length > 0) {
      const task = this.queue.shift();
      if (task) await task();
    }

    this.processing = false;
  }
}

// Usage for rate-limited operations:
const writeQueue = new AsyncQueue();

async function safeWrite(file: TFile, content: string) {
  await writeQueue.add(async () => {
    await this.app.vault.modify(file, content);
  });
}

Output

• Type-safe settings management
• Service layer for vault operations
• Event registration with automatic cleanup
• Fluent command builder
• Async queue for rate limiting

Error Handling

Pattern	Use Case	Benefit
Settings validation	User input	Prevents invalid config
Service layer	Vault access	Centralizes file ops
Event manager	Lifecycle events	Prevents memory leaks
Command builder	Plugin commands	Cleaner registration
Async queue	Bulk operations	Prevents race conditions

Examples

Debounce Pattern

// src/utils/debounce.ts
export function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void {
  let timeout: NodeJS.Timeout | null = null;

  return (...args: Parameters<T>) => {
    if (timeout) clearTimeout(timeout);
    timeout = setTimeout(() => func(...args), wait);
  };
}

// Usage for search:
const debouncedSearch = debounce(async (query: string) => {
  const results = await performSearch(query);
  updateUI(results);
}, 300);

Singleton Service Pattern

// src/main.ts
export default class MyPlugin extends Plugin {
  private static instance: MyPlugin;
  private vaultService: VaultService;

  static getInstance(): MyPlugin {
    return MyPlugin.instance;
  }

  async onload() {
    MyPlugin.instance = this;
    this.vaultService = new VaultService(this.app);
  }

  getVaultService(): VaultService {
    return this.vaultService;
  }
}

Resources

• Obsidian API Reference
• Obsidian Plugin Developer Docs
• TypeScript Best Practices

Next Steps

Apply patterns in obsidian-core-workflow-a for vault operations.