---
title: Plugin Loading
description: Plugin Loading protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# Plugin Loading Protocol

Defines the enhanced plugin loading mechanism for the microkernel architecture.

Inspired by industry best practices from:

- Kubernetes CRDs and Operators

- OSGi Dynamic Module System

- Eclipse Plugin Framework

- Webpack Module Federation

This protocol enables:

- Lazy loading and code splitting

- Dynamic imports and parallel initialization

- Capability-based discovery

- Hot reload in development

- Advanced caching strategies

<Callout type="info">
**Source:** `packages/spec/src/kernel/plugin-loading.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel';
import type { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel';

// Validate data
const result = PluginCaching.parse(data);
```

---

## PluginCaching

Plugin caching configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **storage** | `Enum<'memory' \| 'disk' \| 'indexeddb' \| 'hybrid'>` | ✅ |  |
| **keyStrategy** | `Enum<'version' \| 'hash' \| 'timestamp'>` | ✅ |  |
| **ttl** | `integer` | optional | Time to live in seconds (0 = infinite) |
| **maxSize** | `integer` | optional | Max cache size in MB |
| **invalidateOn** | `Enum<'version-change' \| 'dependency-change' \| 'manual' \| 'error'>[]` | optional |  |
| **compression** | `Object` | optional |  |


---

## PluginCodeSplitting

Plugin code splitting configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **strategy** | `Enum<'route' \| 'feature' \| 'size' \| 'custom'>` | ✅ |  |
| **chunkNaming** | `Enum<'hashed' \| 'named' \| 'sequential'>` | ✅ |  |
| **maxChunkSize** | `integer` | optional | Max chunk size in KB |
| **sharedDependencies** | `Object` | optional |  |


---

## PluginDependencyResolution

Plugin dependency resolution configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **strategy** | `Enum<'strict' \| 'compatible' \| 'latest' \| 'pinned'>` | ✅ |  |
| **peerDependencies** | `Object` | optional |  |
| **optionalDependencies** | `Object` | optional |  |
| **conflictResolution** | `Enum<'fail' \| 'latest' \| 'oldest' \| 'manual'>` | ✅ |  |
| **circularDependencies** | `Enum<'error' \| 'warn' \| 'allow'>` | ✅ |  |


---

## PluginDynamicImport

Plugin dynamic import configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **mode** | `Enum<'async' \| 'sync' \| 'eager' \| 'lazy'>` | ✅ |  |
| **prefetch** | `boolean` | ✅ | Prefetch module in idle time |
| **preload** | `boolean` | ✅ | Preload module in parallel with parent |
| **webpackChunkName** | `string` | optional | Custom chunk name for webpack |
| **timeout** | `integer` | ✅ | Dynamic import timeout (ms) |
| **retry** | `Object` | optional |  |


---

## PluginHotReload

Plugin hot reload configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **environment** | `Enum<'development' \| 'staging' \| 'production'>` | ✅ | Target environment controlling safety level |
| **strategy** | `Enum<'full' \| 'partial' \| 'state-preserve'>` | ✅ |  |
| **watchPatterns** | `string[]` | optional | Glob patterns for files to watch |
| **ignorePatterns** | `string[]` | optional | Glob patterns for files to ignore |
| **debounceMs** | `integer` | ✅ |  |
| **preserveState** | `boolean` | ✅ |  |
| **stateSerialization** | `Object` | optional |  |
| **hooks** | `Object` | optional |  |
| **productionSafety** | `Object` | optional |  |


---

## PluginInitialization

Plugin initialization configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **mode** | `Enum<'sync' \| 'async' \| 'parallel' \| 'sequential'>` | ✅ |  |
| **timeout** | `integer` | ✅ |  |
| **priority** | `integer` | ✅ |  |
| **critical** | `boolean` | ✅ | If true, kernel bootstrap fails if plugin fails |
| **retry** | `Object` | optional |  |
| **healthCheckInterval** | `integer` | optional | Health check interval in ms (0 = disabled) |


---

## PluginLoadingConfig

Complete plugin loading configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **strategy** | `Enum<'eager' \| 'lazy' \| 'parallel' \| 'deferred' \| 'on-demand'>` | ✅ | Plugin loading strategy |
| **preload** | `Object` | optional | Plugin preloading configuration |
| **codeSplitting** | `Object` | optional | Plugin code splitting configuration |
| **dynamicImport** | `Object` | optional | Plugin dynamic import configuration |
| **initialization** | `Object` | optional | Plugin initialization configuration |
| **dependencyResolution** | `Object` | optional | Plugin dependency resolution configuration |
| **hotReload** | `Object` | optional | Plugin hot reload configuration |
| **caching** | `Object` | optional | Plugin caching configuration |
| **sandboxing** | `Object` | optional | Plugin sandboxing configuration |
| **monitoring** | `Object` | optional | Plugin performance monitoring configuration |


---

## PluginLoadingEvent

Plugin loading lifecycle event

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'load-started' \| 'load-completed' \| 'load-failed' \| 'init-started' \| 'init-completed' \| 'init-failed' \| 'preload-started' \| 'preload-completed' \| 'cache-hit' \| 'cache-miss' \| 'hot-reload' \| 'dynamic-load' \| 'dynamic-unload' \| 'dynamic-discover'>` | ✅ |  |
| **pluginId** | `string` | ✅ |  |
| **timestamp** | `integer` | ✅ |  |
| **durationMs** | `integer` | optional |  |
| **metadata** | `Record<string, any>` | optional |  |
| **error** | `Object` | optional |  |


---

## PluginLoadingState

Plugin loading state

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pluginId** | `string` | ✅ |  |
| **state** | `Enum<'pending' \| 'loading' \| 'loaded' \| 'initializing' \| 'ready' \| 'failed' \| 'reloading' \| 'unloading' \| 'unloaded'>` | ✅ |  |
| **progress** | `number` | ✅ |  |
| **startedAt** | `integer` | optional |  |
| **completedAt** | `integer` | optional |  |
| **lastError** | `string` | optional |  |
| **retryCount** | `integer` | ✅ |  |


---

## PluginLoadingStrategy

Plugin loading strategy

### Allowed Values

* `eager`
* `lazy`
* `parallel`
* `deferred`
* `on-demand`


---

## PluginPerformanceMonitoring

Plugin performance monitoring configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **metrics** | `Enum<'load-time' \| 'init-time' \| 'memory-usage' \| 'cpu-usage' \| 'api-calls' \| 'error-rate' \| 'cache-hit-rate'>[]` | optional |  |
| **samplingRate** | `number` | ✅ |  |
| **reportingInterval** | `integer` | ✅ |  |
| **budgets** | `Object` | optional |  |
| **onBudgetViolation** | `Enum<'warn' \| 'error' \| 'ignore'>` | ✅ |  |


---

## PluginPreloadConfig

Plugin preloading configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **priority** | `integer` | ✅ |  |
| **resources** | `Enum<'metadata' \| 'dependencies' \| 'assets' \| 'code' \| 'services'>[]` | optional |  |
| **conditions** | `Object` | optional |  |


---

## PluginSandboxing

Plugin sandboxing configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **scope** | `Enum<'automation-only' \| 'untrusted-only' \| 'all-plugins'>` | ✅ | Which plugins are subject to isolation |
| **isolationLevel** | `Enum<'none' \| 'process' \| 'vm' \| 'iframe' \| 'web-worker'>` | ✅ |  |
| **allowedCapabilities** | `string[]` | optional | List of allowed capability IDs |
| **resourceQuotas** | `Object` | optional |  |
| **permissions** | `Object` | optional |  |
| **ipc** | `Object` | optional |  |


---

