obsidian-upgrade-migration

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, and test across Obsidian releases.

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() pattern so existing users' settings survive upgrades:

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 to the lowest Obsidian version that supports all APIs you use:

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

Update versions.json to map your plugin version to the minimum Obsidian version:

{
  "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

Examples

Simple version bump: Plugin works fine on new Obsidian, just need to update minAppVersion. Run Step 1 to audit, Step 5 to update manifest, Step 6 to verify.

CodeMirror 5 to 6 migration: Plugin uses editor.cm for custom decorations. Replace CM5 Decoration with CM6 EditorView extensions per Step 4. This is the most common large migration.

Settings schema change: Plugin v2 renamed darkMode: boolean to theme: 'light' | 'dark' | 'system'. Add migration in Step 3 that maps the old boolean to the new enum, preserving user preference.

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. For multi-environment testing, see obsidian-multi-env-setup.