# Cordis Plugin Loader Events: Complete Reference Guide

> Find the complete Cordis plugin loader events reference in the cordiverse/cordis repository. Discover core events like loader config update, entry init, and exit.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: api-reference
- Published: 2026-08-23

---

**The definitive Cordis plugin loader events reference is located in [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/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](https://github.com/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`](https://github.com/cordiverse/cordis/blob/main/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

```typescript
// 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

```typescript
// 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:

```typescript
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

```typescript
// 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`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts)** — Event declarations (L15‑22) and core loader logic
- **[`packages/loader/tests/index.spec.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/tests/index.spec.ts)** — Test cases demonstrating event usage in real scenarios
- **[`packages/loader/tests/utils.ts`](https://github.com/cordiverse/cordis/blob/main/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:

```typescript
// 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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts) in the main branch of [cordiverse/cordis](https://github.com/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.