gapmiss/obsidian-plugin-skill / .agents/skills/obsidian
obsidian
VerifiedComprehensive guidelines for Obsidian.md plugin development including ESLint rules from eslint-plugin-obsidianmd v0.6.0, TypeScript best practices, memory management, API usage (requestUrl vs fetch), UI/UX standards, popout window compatibility, community.obsidian.md submission process, and Scorecard optimization. Use when working with Obsidian plugins, main.ts files, manifest.json, Plugin class, MarkdownView, TFile, vault operations, or any Obsidian API development.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.0 KB |
| reference/accessibility.md | markdown | 8.0 KB |
| reference/code-quality.md | markdown | 21.9 KB |
| reference/community-scanner.md | markdown | 10.8 KB |
| reference/css-styling.md | markdown | 10.7 KB |
| reference/eslint-setup.md | markdown | 72.3 KB |
| reference/file-operations.md | markdown | 6.1 KB |
| reference/memory-management.md | markdown | 6.3 KB |
| reference/submission.md | markdown | 5.2 KB |
| reference/type-safety.md | markdown | 1.5 KB |
| reference/ui-ux.md | markdown | 29.0 KB |
reference/memory-management.md
View on GitHub# Memory Management & Lifecycle
Proper memory management is critical in Obsidian plugins to prevent memory leaks and ensure smooth performance.
## Use registerEvent() and addCommand() for Cleanup
Rule: Official guidelines
✅ **CORRECT**:
```typescript
async onload() {
// These are automatically cleaned up on unload
this.registerEvent(
this.app.workspace.on('file-open', (file) => {
// Handle file open
})
);
this.addCommand({
id: 'my-command',
name: 'My command',
callback: () => { }
});
// For DOM events, use registerDomEvent
this.registerDomEvent(document, 'click', (evt) => {
// Handle click
});
// For intervals, use registerInterval
this.registerInterval(
window.setInterval(() => {
// Do something periodically
}, 5000)
);
}
onunload() {
// No manual cleanup needed!
// Obsidian handles it automatically
}
```
Rationale: Use `registerEvent()`, `addCommand()`, `registerDomEvent()`, and `registerInterval()` for automatic cleanup when the plugin unloads. This prevents memory leaks.
---
## Use registerDomEvent() Instead of Manual addEventListener
Rule: Best practice (NOT caught by the linter)
The linter enforces `activeDocument` over `document` and `registerEvent()` for Obsidian events, but it does **not** flag manual `addEventListener` calls paired with manual cleanup. That pattern hides a subtle leak: `activeDocument` and `activeWindow` are dynamic getters that follow window focus, so calling them at setup and again at cleanup can return **different documents** (e.g., focus moved to a popout or the settings window in between).
❌ **INCORRECT** (leaks when focus changes between setup and cleanup):
```typescript
export default class MyPlugin extends Plugin {
private onClick = (evt: MouseEvent) => { /* ... */ };
onload() {
// Registers on whichever document is focused NOW
activeDocument.addEventListener('click', this.onClick);
}
onunload() {
// May be a DIFFERENT document — the original listener is never removed
activeDocument.removeEventListener('click', this.onClick);
}
}
```
✅ **CORRECT**:
```typescript
onload() {
// Target is captured once at registration; removal is automatic on unload
this.registerDomEvent(activeDocument, 'click', (evt) => {
// Handle click
});
}
```
If manual management is truly unavoidable, capture the document once and use the same reference for both calls:
```typescript
const doc = activeDocument;
doc.addEventListener('click', this.onClick);
// later, in the cleanup path:
doc.removeEventListener('click', this.onClick);
```
### Scope Listeners to the Owning Component
`registerDomEvent()` is a `Component` method, so views and modals have it too. Register on the component whose lifecycle matches the listener — not always the plugin:
```typescript
export class MyView extends ItemView {
async onOpen() {
// Cleaned up when the view unloads, not when the plugin unloads
this.registerDomEvent(this.containerEl.ownerDocument, 'mousemove', (evt) => {
// ...
});
}
}
```
Helper classes that can't extend `Component` should receive the owning view/component and call its `registerDomEvent()` instead of managing cleanup themselves.
### Covering Popout Windows
A listener registered on one document never fires in other windows. For app-wide listeners, register on each window as it opens:
```typescript
this.registerDomEvent(document, 'click', this.onClick); // main window
this.registerEvent(
this.app.workspace.on('window-open', (workspaceWindow) => {
this.registerDomEvent(workspaceWindow.doc, 'click', this.onClick);
})
);
```
**When plain `addEventListener` is fine:** listeners on short-lived elements your own code creates (e.g., a button inside a settings tab) are garbage-collected with the element. The managed pattern is mandatory for long-lived targets — `document`, `window`, workspace containers — and anything that outlives the registering code.
Rationale: `registerDomEvent()` captures the event target at registration time and removes the listener automatically when the owning component unloads. This eliminates both the manual-cleanup burden and the `activeDocument` drift bug.
---
## Don't Store View References in Plugin
Rule: `obsidianmd/no-view-references-in-plugin`
❌ **INCORRECT**:
```typescript
this.registerView(VIEW_TYPE, (leaf) => {
this.view = new MyCustomView(leaf); // Memory leak!
return this.view;
});
```
✅ **CORRECT**:
```typescript
this.registerView(VIEW_TYPE, (leaf) => {
return new MyCustomView(leaf); // Create and return directly
});
```
Rationale: Storing view instances as plugin properties prevents proper cleanup and causes memory leaks.
---
## Don't Use Plugin as Component
Rule: `obsidianmd/no-plugin-as-component`
❌ **INCORRECT**:
```typescript
// Passing plugin instance
MarkdownRenderer.render(app, markdown, el, sourcePath, this);
// Inline new Component()
MarkdownRenderer.render(app, markdown, el, sourcePath, new Component());
```
✅ **CORRECT**:
```typescript
const component = new Component();
MarkdownRenderer.render(app, markdown, el, sourcePath, component);
// Later: component.unload() when done
```
Rationale: Plugin lifecycle is too long, causing memory leaks. Components must be stored to call `unload()`.
---
## Don't Detach Leaves in onunload
Rule: `obsidianmd/detach-leaves` (auto-fixable)
❌ **INCORRECT**:
```typescript
onunload() {
this.app.workspace.detachLeavesOfType(VIEW_TYPE);
}
```
✅ **CORRECT**:
```typescript
onunload() {
// Let Obsidian handle leaf cleanup automatically
}
```
Rationale: Obsidian handles leaf cleanup automatically. Manual detachment can cause issues. Since v0.5.1 the rule reports (and autofixes) only the `onunload()` of a class that extends `Plugin` — a `Component` that detaches the leaves of a view type it then unregisters is not reported.
---
## Use getActiveLeavesOfType() Instead of Storing Views
Rule: Official guidelines (relates to no-view-references-in-plugin)
❌ **INCORRECT**:
```typescript
// Don't store view references
this.customViews = [];
```
✅ **CORRECT**:
```typescript
// Get views when needed
const views = this.app.workspace.getLeavesOfType(VIEW_TYPE)
.map(leaf => leaf.view as MyCustomView);
```
Rationale: Don't store references to custom views. Use `getLeavesOfType()` or `getActiveLeavesOfType()` to access them when needed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |