Optimize Obsidian plugin performance for smooth operation in large vaults.
Use when experiencing lag, memory issues, slow startup, or optimizing
plugin code for vaults with thousands of files.
Trigger with phrases like "obsidian performance", "obsidian slow",
"optimize obsidian plugin", "obsidian memory usage", "obsidian lag".
Optimize Obsidian plugin performance for smooth operation in large vaults.
Use when experiencing lag, memory issues, slow startup, or optimizing
plugin code for vaults with thousands of files.
Trigger with phrases like "obsidian performance", "obsidian slow",
"optimize obsidian plugin", "obsidian memory usage", "obsidian lag".
Designed for Claude Code, also compatible with Codex and OpenClaw
Obsidian Performance Tuning
Overview
Optimize Obsidian plugin performance for large vaults (10,000+ files): profile bottlenecks with DevTools, implement lazy initialization, process files in batches with UI yielding, use LRU caches with bounded memory, debounce event handlers, and optimize DOM rendering with virtual scrolling and DocumentFragment.
Prerequisites
Working Obsidian plugin with at least one performance concern
// BAD: updating DOM on every eventthis.registerEvent(this.app.vault.on('modify', () => {
this.containerEl.empty();
this.renderFullList(); // re-renders 1000 items on every keystroke
}));
// GOOD: DocumentFragment for batch DOM updatesprivaterenderFileList(container: HTMLElement, files: TFile[]) {
const fragment = document.createDocumentFragment();
for (const file of files) {
const el = document.createElement('div');
el.className = 'file-item';
el.textContent = file.basename;
el.addEventListener('click', () => {
this.app.workspace.getLeaf().openFile(file);
});
fragment.appendChild(el);
}
container.empty();
container.appendChild(fragment);
}
// GOOD: requestAnimationFrame for coalesced updatesprivate pendingRender = false;
privatescheduleRender() {
if (!this.pendingRender) {
this.pendingRender = true;
requestAnimationFrame(() => {
this.render();
this.pendingRender = false;
});
}
}
// GOOD: Virtual scrolling for long listsprivaterenderVirtualList(container: HTMLElement, items: string[], itemHeight = 24) {
const visibleCount = Math.ceil(container.clientHeight / itemHeight);
let scrollTop = 0;
const content = container.createEl('div', {
attr: { style: `height: ${items.length * itemHeight}px; position: relative;` },
});
constrenderVisible = () => {
const start = Math.floor(scrollTop / itemHeight);
const end = Math.min(start + visibleCount + 5, items.length);
content.empty();
for (let i = start; i < end; i++) {
content.createEl('div', {
text: items[i],
attr: { style: `position: absolute; top: ${i * itemHeight}px; height: ${itemHeight}px;` },
});
}
};
container.addEventListener('scroll', () => {
scrollTop = container.scrollTop;
requestAnimationFrame(renderVisible);
});
renderVisible();
}
Step 7: Memory Leak Prevention
// Common leak: WeakRef/WeakMap for file references// Files can be deleted — holding TFile references prevents GCprivate fileData = newWeakMap<TFile, ProcessedData>();
// Common leak: unregistered event listeners// BAD:document.addEventListener('click', this.handler); // leaks on unload// GOOD:this.registerDomEvent(document, 'click', this.handler); // auto-cleaned// Common leak: uncleaned intervals// BAD:setInterval(() =>this.sync(), 60000); // runs forever after unload// GOOD:this.registerInterval(window.setInterval(() =>this.sync(), 60000)); // auto-cleaned// Audit: check memory in DevTools// Console > Performance.memory.usedJSHeapSize// Enable/disable your plugin, check if memory drops back to baseline
Output
Performance profiler identifying specific bottlenecks in onload and commands
Lazy initialization deferring index builds until first use
Batch file processing with await sleep(0) yielding to prevent UI freezes
LRU cache with bounded memory (500 entries) and mtime-based invalidation
Debounced event handlers (global and per-file) for vault.on('modify')
DOM optimization with DocumentFragment, requestAnimationFrame, and virtual scrolling
Memory leak prevention checklist with WeakMap, registerEvent, registerInterval
Error Handling
Issue
Cause
Solution
Plugin slow to load
Heavy initialization in onload
Use lazy loading pattern (Step 2)
UI freezes during processing
Synchronous loop over all files
Batch with await sleep(0) (Step 3)
Memory keeps growing
Unbounded caches or leaked references
Use LRU cache (Step 4), WeakMap for file refs
Event handlers lag
Unthrottled modify handler
Debounce at 500ms minimum (Step 5)
Layout thrashing
DOM updates on every event
Coalesce with requestAnimationFrame (Step 6)
cachedRead returns stale data
Cache not yet updated
Use vault.read() when freshness is critical
Plugin doesn't release memory on disable
Missing cleanup
Use registerEvent/registerInterval exclusively
Examples
Pre-Release Performance Checklist
onload completes in < 100ms (check console timing)
No synchronous loops over all vault files in onload
File operations use cachedRead (not read) where possible
All event handlers debounced or throttled
Caches have explicit size limits (LRU or max-age)
Works smoothly in vault with 5,000+ files
Memory returns to baseline after disabling plugin
No raw addEventListener / setInterval (use register* methods)
Quick Memory Check
// Paste in Obsidian DevTools Console// Check before and after enabling your pluginconsole.log('Heap:', Math.round(performance.memory.usedJSHeapSize / 1048576), 'MB');
