Obsidian Upgrade Migration

Current State

!

npm list 2>/dev/null | head -20

cat manifest.json 2>/dev/null || echo 'No manifest.json in cwd'

Overview

Upgrade an Obsidian plugin between versions: migrate persisted settings with version checks, replace deprecated API calls, update

manifest.json

minAppVersion

Prerequisites

• Existing Obsidian plugin with source code
• Current

  manifest.json

  and

  versions.json

• Access to Obsidian changelog and breaking changes docs
• Node.js 18+ with npm or pnpm

Instructions

Step 1: Audit Current Version Compatibility

Check what your plugin currently targets and what the user's Obsidian version requires:

# Current plugin target
echo "=== manifest.json ==="
cat manifest.json | python3 -c "
import json, sys
m = json.load(sys.stdin)
print(f\"Plugin: {m['id']} v{m['version']}\")
print(f\"minAppVersion: {m['minAppVersion']}\")
"

# Current obsidian type definitions
echo "=== obsidian package version ==="
npm ls obsidian 2>/dev/null || echo "Not found in node_modules"

# Check versions.json for version history
echo "=== versions.json ==="
cat versions.json 2>/dev/null | python3 -m json.tool || echo "No versions.json"

Step 2: Update the Obsidian Type Definitions

# Update to latest obsidian types
npm install obsidian@latest --save-dev

# Check what changed
npm diff obsidian 2>/dev/null | head -100

Then check for TypeScript errors against the new types:

npx tsc --noEmit 2>&1 | head -50

Every error here is a breaking change you need to address.

Step 3: Settings Migration with Version Tracking

Implement a version-aware

loadData()

interface PluginSettings {
  _version: number; // Internal schema version
  // v1 fields
  enabled: boolean;
  // v2 fields (added in plugin v2.0.0)
  syncInterval: number;
  // v3 fields (added in plugin v3.0.0)
  theme: 'light' | 'dark' | 'system';
}

const CURRENT_SETTINGS_VERSION = 3;

const DEFAULT_SETTINGS: PluginSettings = {
  _version: CURRENT_SETTINGS_VERSION,
  enabled: true,
  syncInterval: 300,
  theme: 'system',
};

async loadSettings(): Promise<PluginSettings> {
  const raw = await this.loadData();
  if (!raw) return { ...DEFAULT_SETTINGS };

  const version = raw._version ?? 1;
  let settings = { ...raw };

  // v1 -> v2: add syncInterval
  if (version < 2) {
    settings.syncInterval = DEFAULT_SETTINGS.syncInterval;
    console.log('[your-plugin] Migrated settings v1 -> v2');
  }

  // v2 -> v3: add theme, rename old field
  if (version < 3) {
    settings.theme = DEFAULT_SETTINGS.theme;
    // Rename deprecated field
    if ('darkMode' in settings) {
      settings.theme = settings.darkMode ? 'dark' : 'light';
      delete settings.darkMode;
    }
    console.log('[your-plugin] Migrated settings v2 -> v3');
  }

  settings._version = CURRENT_SETTINGS_VERSION;
  await this.saveData(settings); // Persist the migration
  return settings as PluginSettings;
}

Step 4: Replace Deprecated API Calls

Common deprecations and their replacements:

Vault API changes:

// DEPRECATED: vault.modify with string path
await this.app.vault.modify(filePath, content);
// REPLACEMENT: use TFile object
const file = this.app.vault.getAbstractFileByPath(filePath);
if (file instanceof TFile) {
  await this.app.vault.modify(file, content);
}

// DEPRECATED: vault.create returns void in older versions
this.app.vault.create(path, content);
// REPLACEMENT: returns TFile, handle it
const newFile = await this.app.vault.create(path, content);

Event registration changes:

// DEPRECATED: workspace.on('file-open') with old signature
this.app.workspace.on('file-open', (file) => { ... });
// REPLACEMENT: use registerEvent for proper cleanup
this.registerEvent(
  this.app.workspace.on('file-open', (file) => { ... })
);

Editor API (CodeMirror 5 to 6 migration):

// DEPRECATED: accessing CM5 editor instance
const cm = (editor as any).cm;
cm.getValue(); // CM5

// REPLACEMENT: use Obsidian's Editor interface
const content = editor.getValue();
const cursor = editor.getCursor();
editor.replaceRange(text, cursor);

// For CM6-specific features, use EditorView extension:
import { EditorView, ViewPlugin } from '@codemirror/view';

this.registerEditorExtension(
  ViewPlugin.fromClass(class {
    constructor(view: EditorView) {
      // CM6 view access
    }
  })
);

FileManager changes:

// DEPRECATED: processFrontMatter sync signature
this.app.fileManager.processFrontMatter(file, (fm) => {
  fm.tags = ['updated'];
});
// REPLACEMENT: async signature (Obsidian 1.4+)
await this.app.fileManager.processFrontMatter(file, (fm) => {
  fm.tags = ['updated'];
});

Step 5: Update manifest.json

Bump

minAppVersion

{
  "id": "your-plugin",
  "name": "Your Plugin",
  "version": "3.0.0",
  "minAppVersion": "1.5.0",
  "description": "...",
  "author": "...",
  "isDesktopOnly": false
}

Update

versions.json

{
  "1.0.0": "0.15.0",
  "2.0.0": "1.0.0",
  "3.0.0": "1.5.0"
}

Step 6: Test Across Obsidian Versions

Build and verify:

# Clean build
rm -rf dist node_modules/.cache
npm install
npm run build

# Check for type errors
npx tsc --noEmit

# Check bundle for leftover deprecated calls
grep -rn 'cm\.getValue\|processFrontMatter.*sync\|vault\.modify.*string' src/ || echo "No deprecated patterns found"

Manual testing checklist:

1. Install plugin on the

   minAppVersion

   you declared -- confirm it loads without errors
2. Install on latest Obsidian -- confirm full functionality
3. Test settings migration: copy a

   data.json

   from an older version into the plugin directory, reload, verify settings are preserved and upgraded
4. Open Developer Console (Ctrl+Shift+I) and check for deprecation warnings

Step 7: Handle the Release

# Update version in package.json and manifest.json
npm version major  # or minor/patch

# Ensure versions.json includes the new mapping
python3 -c "
import json
v = json.load(open('versions.json'))
m = json.load(open('manifest.json'))
v[m['version']] = m['minAppVersion']
json.dump(v, open('versions.json', 'w'), indent=2)
print(f\"Added {m['version']} -> {m['minAppVersion']}\")
"

# Build the release artifacts
npm run build

Output

• Updated

  manifest.json

  with correct

  minAppVersion

• Updated

  versions.json

  with new version mapping
• Settings migration code that handles all previous schema versions
• All deprecated API calls replaced with current equivalents
• Clean

  tsc --noEmit

  with no type errors
• Tested on minimum and latest Obsidian versions

Error Handling

Property does not exist on type 'Plugin'

obsidian

Cannot find module 'obsidian'

npm install obsidian@latest --save-dev

_version

TypeError: x is not a function

minAppVersion

Examples

Simple version bump: Plugin works fine on new Obsidian, just need to update

minAppVersion

CodeMirror 5 to 6 migration: Plugin uses

editor.cm

Decoration

EditorView

Settings schema change: Plugin v2 renamed

darkMode: boolean

theme: 'light' | 'dark' | 'system'

Resources

• Obsidian Changelog
• Obsidian API Breaking Changes
• Obsidian Developer Docs
• Obsidian Plugin API Types
• CodeMirror 6 Migration

Next Steps

For CI/CD to automate release testing, see

obsidian-ci-integration

obsidian-multi-env-setup