Lifecycle and Bundling
Export a definePlugin object, activate lazily, bundle safely, and clean up when the plugin is disabled.
A plugin bundle default-exports the result of definePlugin(...) from @cortex.md/api.
Lifecycle#
- Discover. Cortex reads
manifest.json, evaluates the bundle, and validates the exporteddefinePluginobject (manifest id, known permissions). - 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). Noactivateorloadcode runs. - Activate (lazy). On the first command execution, first view render, or immediately when
activation: "startup", Cortex awaitsload()(if declared), thenactivate(ctx)from the definition and from the loaded implementation. - Disable. Every registration, context subscription (
onChange,onFileEvent, ...), and the cleanup returned byactivateis disposed together.
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.
// 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 PluginImplementationType 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:
bun build ./src/index.ts --outfile ./dist/index.js --target browser --format cjs --external @cortex.md/api --external @codemirror/state --external @codemirror/viewThe host evaluates the bundle with a controlled require stub. Only three modules resolve at
runtime:
@cortex.md/apiprovidesdefinePluginandPLUGIN_PERMISSIONS.@codemirror/stateand@codemirror/vieware 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:
import { definePlugin, type ViewDescriptor } from "@cortex.md/api"import { helper } from "./helper"Avoid:
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.