Plugins
Learn about SoulCache's plugin system for extensibility
Plugins
The Plugin System allows you to extend SoulCache with custom behavior.
Usage
SoulCache provides a plugin infrastructure for internal extension. The plugin system is
an internal module of @soulcache/core: PluginManager, Plugin, and PluginContext
are not exported from the package root, there is no plugins option on
QueryClientConfig, and the @soulcache/core/plugin subpath does not resolve. There is
no public plugin registration API in the current release.
Lifecycle
Plugins go through a well-defined lifecycle:
| State | Description |
|---|---|
discovered | Plugin found |
validated | Metadata valid |
registered | Added to manager |
initialized | onBeforeInit/onAfterInit called |
active | Hooks running |
suspended | Temporarily disabled |
resuming | Being resumed from suspension |
stopping | Disposal in progress |
disposed | Cleaned up |
removed | Unregistered from manager |
error | Initialization failed |
Hooks
| Hook | When |
|---|---|
onBeforeInit | Before initialization |
onAfterInit | After initialization |
onBeforeQuery | Before query execution |
onAfterQuery | After query completion |
onBeforeMutation | Before mutation |
onAfterMutation | After mutation |
onCacheUpdated | Cache entry updated |
onCacheInvalidated | Cache entry invalidated |
onShutdown | Runtime shutdown |
onSuspend | Plugin suspended |
onResume | Plugin resumed |
onDispose | Plugin disposed |
Features
Dependency Resolution
Automatic dependency resolution ensures correct load order
Error Isolation
Each hook is isolated so errors don't cascade
State Machine
Well-defined lifecycle states for predictable behavior
Dependency Checking
Automatic verification of plugin dependencies
Best Practices
Plugin Guidelines
- Keep plugins small — Single responsibility principle
- Handle errors — Hooks are isolated but should be robust
- Declare dependencies — Ensure correct load order
- Clean up — Use onDispose for resource cleanup