obsidian-upgrade-migration

•

1.9k2643 months ago

Migrate Obsidian plugins between API versions and handle breaking changes. Use when upgrading to new Obsidian versions, handling API deprecations, or migrating plugin code to new patterns. Trigger with phrases like "obsidian upgrade", "obsidian migration", "obsidian API changes", "update obsidian plugin".

Quick Install

npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill obsidian-upgrade-migration

Instructions

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

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

obsidian

Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.

359,291

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

Tags & Topics

aiautomationclaude-codedevopsmcpai-agents

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

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

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

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

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;
}

// 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);

// 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) => { ... })
);

// 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
    }
  })
);

// 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'];
});

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

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

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

# 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

Error	Cause	Solution
`Property does not exist on type 'Plugin'`	API removed in newer `obsidian` types	Check changelog for replacement API
`Cannot find module 'obsidian'`	Types not installed	`npm install obsidian@latest --save-dev`
Settings lost after upgrade	No migration logic for `_version` jump	Add migration step for each version gap
`TypeError: x is not a function` at runtime	API exists in types but not in user's Obsidian	Lower `minAppVersion` or add runtime version check
Plugin loads but features missing	Feature flag not migrated	Check settings migration covers all paths

obsidian-upgrade-migration

Obsidian Upgrade Migration

Current State

Overview

Prerequisites

Instructions

Step 1: Audit Current Version Compatibility

Related Skills

skill-creator

skill-creator

obsidian

1password

Obsidian Upgrade Migration

Current State

Overview

Prerequisites

Instructions

Step 1: Audit Current Version Compatibility

Step 2: Update the Obsidian Type Definitions

Step 3: Settings Migration with Version Tracking

Step 4: Replace Deprecated API Calls

Step 5: Update manifest.json

Step 6: Test Across Obsidian Versions

Step 7: Handle the Release

Output

Error Handling

Examples

Resources

Next Steps

Related Skills

skill-creator

skill-creator

obsidian

1password

Related Skills

skill-creator

skill-creator

obsidian

1password