Cordis Plugin Loader Events: Complete Reference Guide

The definitive Cordis plugin loader events reference is located in packages/loader/src/index.ts at lines 15‑22, where the Events interface declares five core events including loader/config-update, loader/entry-init, loader/partial-dispose, loader/patch-context, and exit.

Cordis provides a powerful plugin system with lifecycle hooks that let you react to configuration changes, entry initialization, and context patching. This guide gives you the complete technical reference for all Cordis plugin loader events as implemented in the cordiverse/cordis repository.

Where Loader Events Are Defined

The source of truth for Cordis plugin loader events is the loader package's entry point. In packages/loader/src/index.ts, the Events interface is extended to include loader-specific lifecycle hooks between lines 15‑22.

This is a TypeScript declaration file, meaning you get full type safety and IntelliSense when subscribing to these events in your own code.

Complete List of Cordis Plugin Loader Events

Each event serves a distinct purpose in the loader lifecycle. Here's the full reference:

Event	Emitted When	Payload
loader/config-update	After the loader processes a configuration update	None
loader/entry-init	A new loader entry is initialized	The entry object with entry.id
loader/partial-dispose	A loader entry is partially disposed	entry, legacy options, active boolean
loader/patch-context	The loader patches a context	entry and next callback
exit	Cordis receives a shutdown signal	NodeJS.Signals value

All events are available on any Cordis context (ctx) through standard event subscription methods.

Subscribing to Loader Events

Use ctx.on(), ctx.once(), or ctx.off() to manage event listeners. The examples below demonstrate practical patterns for each Cordis plugin loader event.

Configuration Updates

// packages/loader/src/index.ts declares: 'loader/config-update'
ctx.on('loader/config-update', () => {
  console.log('Loader configuration has been refreshed')
  // Trigger downstream reloads or cache invalidation
})

Entry Lifecycle

// React when a new entry is created
ctx.on('loader/entry-init', (entry) => {
  console.log('New loader entry:', entry.id)
  // Initialize per-entry resources or metrics
})

// Handle partial disposal with full context
ctx.on('loader/partial-dispose', (entry, legacy, active) => {
  console.log(`Entry ${entry.id} partially disposed`, { legacy, active })
  // Cleanup state bound to this entry when active was true
})

Context Patching

The loader/patch-context event is unique—it provides a next callback for control flow:

ctx.on('loader/patch-context', (entry, next) => {
  console.log('Patching context for entry', entry.id)
  
  // Perform custom modifications here
  entry.customProperty = computeValue(entry)
  
  // Continue the normal patch flow
  next()
  
  // Or conditionally skip: if (shouldSkip) return
})

Calling next() delegates to subsequent handlers or completes the patching process. Omitting it halts the chain.

Shutdown Handling

// Capture Cordis shutdown signals
ctx.on('exit', (signal) => {
  console.log(`Cordis is exiting due to signal ${signal}`)
  // SIGTERM, SIGINT, etc.—perform graceful cleanup
})

Note that exit is a generic Cordis event, not loader-specific, but it's declared alongside loader events in the same interface.

Key Source Files for Deep Dives

Beyond the main declaration file, these locations provide implementation details and usage patterns:

• packages/loader/src/index.ts — Event declarations (L15‑22) and core loader logic
• packages/loader/tests/index.spec.ts — Test cases demonstrating event usage in real scenarios
• packages/loader/tests/utils.ts — Helper utilities revealing loader lifecycle internals

The test files are particularly valuable for understanding edge cases and proper cleanup patterns.

TypeScript Type Safety

Because events are declared via interface extension, TypeScript provides full type inference:

// ctx.on is fully typed—no @ts-ignore needed
ctx.on('loader/partial-dispose', (entry, legacy, active) => {
  // entry.id: string
  // legacy: unknown (specific to your config schema)
  // active: boolean
})

If you attempt to use an invalid event name or wrong handler signature, compilation fails.

Summary

• Cordis plugin loader events are declared in packages/loader/src/index.ts at lines 15‑22
• Five core events cover the full lifecycle: loader/config-update, loader/entry-init, loader/partial-dispose, loader/patch-context, and exit
• Subscribe with ctx.on(), ctx.once(), or ctx.off() on any Cordis context
• The loader/patch-context event uses a next callback pattern for middleware-style control flow
• Reference packages/loader/tests/index.spec.ts for production-tested usage examples

Frequently Asked Questions

How do I find the most up-to-date Cordis plugin loader events?

Check packages/loader/src/index.ts in the main branch of cordiverse/cordis. The Events interface extension at lines 15‑22 contains the authoritative, version-specific event list. Event additions or changes are rare but follow semantic versioning.

What's the difference between partial disposal and full disposal?

loader/partial-dispose fires when a loader entry is being torn down but may retain some state or be reinitialized. The active boolean tells you whether the entry was running, and legacy contains the previous configuration. Full disposal isn't exposed as a separate event—monitor ctx disposables for complete cleanup detection.

Can I prevent context patching from completing?

Yes. In your loader/patch-context handler, simply omit the next() call to halt the patching chain. Use this sparingly: it prevents all downstream handlers and the default loader behavior from executing. Always log or surface when you're blocking standard patching to aid debugging.

Do loader events work with the synchronous API?

All Cordis plugin loader events are emitted asynchronously through the standard event system. While handlers run synchronously in registration order, the emissions themselves don't block the calling code. For exit handlers, Cordis awaits async cleanup before process termination.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}