Unified abstraction for obsidian plugins
npm install ts-obsidian-plugin
!Build & Test
BOTTOM CHANGELOG LICENSE ROADMAP
A TypeScript base package for Obsidian plugins that provides stable, persistent settings management.
The package includes an abstract base class AbstractObsidianPluginWithSettings, interfaces for persistent data and plugins with settings, and helper functions like deepPurge.
---
- Abstract base class for Obsidian plugins with a stable in-memory settings reference
- Full settings lifecycle implementation (loadSettings, saveSettings, onExternalSettingsChange)
- Support for default settings and merging with persisted data
- Low-level persistence via loadData and saveData
- Helper function deepPurge to recursively clear objects while preserving the reference
- Designed for TypeScript and Rollup bundling in Obsidian plugins
---
``bash`
npm install ts-obsidian-pluginor
pnpm add ts-obsidian-plugin
> Note: This package has obsidian as a peer dependency (>= 1.5.0). It must be available in the plugin context.
---
`ts
import { AbstractObsidianPluginWithSettings } from "ts-obsidian-plugin";
interface MyPluginSettings {
optionA: string;
optionB: number;
}
export class MyPlugin extends AbstractObsidianPluginWithSettings
public getDefaultSettings(): MyPluginSettings {
return {
optionA: "default",
optionB: 42
};
}
async onload() {
await this.loadSettings();
console.log(this.settings.optionA);
}
async saveCustomSettings() {
this._settings.optionB = 100;
await this.saveSettings();
}
}
`$3
`ts`
const data = await this.loadData();
await this.saveData({ custom: "value" });
---
The package uses Rollup for bundling and Vitest for testing.
`bashBuild
npm run build
---Bundling (Required)
Obsidian does not support loading external npm modules at runtime.
All dependencies must be bundled.
$3
js
import resolve from "@rollup/plugin-node-resolve";
import typescript from "@rollup/plugin-typescript";export default {
input: "src/main.ts",
output: {
file: "dist/main.js",
format: "cjs",
},
plugins: [
resolve(),
typescript(),
],
external: ["obsidian"],
};
`
---API Reference
$3
An abstract base class for Obsidian plugins with typed and persistent settings.
#### Properties
-
Returns the current in-memory settings object. The reference is stable, but individual properties may be updated internally during loading or merging. Consumers should not replace the object itself.#### Methods
-
getDefaultSettings(): TSettings (abstract)
Returns a fully populated default settings object. Must be implemented by subclasses.-
loadSettings(): Promise
Loads persisted settings from disk, merges them with default values, and updates the in-memory settings object. Reference to the settings object remains unchanged.-
saveSettings(): Promise
Persists the current in-memory settings to disk using the underlying saveData method.-
onExternalSettingsChange(): Promise
Reloads settings in response to external modifications of the data file (e.g., file sync or manual changes).-
loadData(): Promise
Low-level method to load raw persisted plugin data from disk. Returns the deserialized data.json contents or null/undefined if no data exists.-
saveData(data: unknown): Promise
Low-level method to save raw plugin data to disk. Performs no validation or transformation.---
TypeScript Interfaces
ObsidianDataPersistence
Defines the low-level contract for plugin data persistence:
-
loadData(): Promise – Load raw persisted plugin data.
- saveData(data: unknown): Promise – Save raw plugin data.PluginWithSettings
Extends ObsidianDataPersistence and adds a structured settings lifecycle:
-
settings: Readonly – Read-only access to in-memory settings.
- getDefaultSettings(): TSettings – Returns default settings.
- loadSettings(): Promise – Load and merge persisted settings.
- saveSettings(): Promise – Persist current settings.
- onExternalSettingsChange(): Promise