Skip to content
Cortex

Lifecycle and Bundling

Export a definePlugin object, activate lazily, bundle safely, and clean up when the plugin is disabled.

2 min readEdit on GitHub

A plugin bundle default-exports the result of definePlugin(...) from @cortex.md/api.

Lifecycle#

  1. Discover. Cortex reads manifest.json, evaluates the bundle, and validates the exported definePlugin object (manifest id, known permissions).
  2. Enable. Cortex loads plugin settings, then registers every static contribution in one batch: commands, views, sidebar/status bar/context menu items, the settings page, Markdown rules, property types, fold providers, and editorExtensions(ctx). No activate or load code runs.
  3. Activate (lazy). On the first command execution, first view render, or immediately when activation: "startup", Cortex awaits load() (if declared), then activate(ctx) from the definition and from the loaded implementation.
  4. Disable. Every registration, context subscription (onChange, onFileEvent, ...), and the cleanup returned by activate is disposed together.
ts
export default definePlugin({	manifest: manifest as PluginManifest,	activation: "startup",	activate(ctx) {		const timer = setInterval(() => console.log(ctx.manifest.id), 60_000)		return () => clearInterval(timer)	},})

activate may return a cleanup function or a Disposable. Use it for things Cortex cannot track for you, such as timers, in-memory caches, network subscriptions, and external resources.

Lazy Implementation#

Keep heavy code out of the startup path by declaring metadata inline and resolving handlers from load(). Commands without run and views without render are resolved from the loaded module.

ts
// index.tsexport default definePlugin({	manifest: manifest as PluginManifest,	contributes: {		commands: [{ id: "report", label: "Build Report" }],		views: [{ id: "report", label: "Report", icon: "chart", location: "tab" }],	},	load: () => import("./impl"),})// impl.tsimport type { PluginImplementation } from "@cortex.md/api"export default {	commands: { report: (ctx) => ctx.workspace.openView("report") },	views: { report: { render: () => ({ type: "text", value: "Ready" }) } },} satisfies PluginImplementation

Type the loaded module with satisfies PluginImplementation; deriving it from typeof plugin would be circular because the definition's type depends on load(). PluginContextOf<typeof plugin> types helper modules the definition does not import.

Bundle Contract#

Emit one CommonJS, browser-targeted bundle:

bash
bun build ./src/index.ts --outfile ./dist/index.js --target browser --format cjs --external @cortex.md/api --external @codemirror/state --external @codemirror/view

The host evaluates the bundle with a controlled require stub. Only three modules resolve at runtime:

  • @cortex.md/api provides definePlugin and PLUGIN_PERMISSIONS.
  • @codemirror/state and @codemirror/view are provided when the bundle references them.

Any other require fails the load. If CommonJS evaluation fails and the bundle looks like an ES module, the host retries it as a self-contained ESM import; prefer CommonJS for predictable loads. With CommonJS, load: () => import("./impl") is bundled inline; the laziness still defers running that code until first use.

Imports#

Allowed:

ts
import { definePlugin, type ViewDescriptor } from "@cortex.md/api"import { helper } from "./helper"

Avoid:

ts
import { useVaultStore } from "@cortex/core"import { EditorView } from "@cortex/editor/editor-view"import { getPlatform } from "@cortex/platform"

Community plugins must not import Cortex internals. Host APIs come through ctx.

Dependency Guidance#

  • Bundle third-party runtime dependencies into your plugin output.
  • Avoid global side effects at module top level.
  • Keep plugin state serializable when it flows through views, settings, or workspace tabs.

Search docs

Search Cortex documentation pages and headings.