A minimal plugin runtime for building modular JavaScript applications.
Stop wiring up infrastructure. Start building features.
npm install skeleton-crew@^0.6.0True atomic hot-swap. The new plugin's setup runs against a buffered context that doesn't touch the live registries. If it throws, the buffer is dropped and the old plugin is observably untouched — actions still serve, services still resolve, event handlers still fire. If it succeeds, the buffer commits to the live registries in one synchronous batch.
await runtime.swapPlugin({
name: 'my-plugin',
version: '2.0.0',
setup(ctx) {
// v1 is still fully live here. ctx.services.get('cfg') falls back to
// v1's value until v2 registers its own. Events emitted here are
// handled by v1.
ctx.actions.registerAction({ id: 'my-plugin:greet', handler: () => 'v2' });
throw new Error('boom'); // v1 keeps running. Action 'greet' still returns 'v1'.
},
});Sequence:
- Pre-flight (semver, deps,
validateConfig) — same as 0.5.0. - Buffered setup of the new plugin — writes go into an in-memory
SwapBuffer, reads merge buffer over live. - Commit (synchronous) —
replaceAtomicflips each id in the live registries, ids the old plugin owned that the new plugin omitted are retired. plugin:swappedevent.- Then
disposeof the old plugin (behavior change from 0.5.0 — was step 1).
Other 0.6.0 surface:
replaceAtomicandunregisteradded toActionEngine,ScreenRegistry,ServiceRegistry— the primitives the swap commit step uses. Available to plugins but typically not needed outside hot-swap.- Read semantics during buffered setup:
ctx.services.get/actions.hasAction/screens.getScreen/plugins.getPluginall read buffer-first, fall through to live. - Event subscriptions during buffered setup are queued and committed at commit time — a subscription registered inside
setupwon't fire on events emitted during the same setup. This avoids leaking subscriptions on rollback.
A correctness release driven by an internal code review of the plugin system, with hot-swap as the focal point. Every finding was first captured as a failing reproducer test (shipped in tests/unit/review-reproducers.test.ts), then fixed one commit at a time.
- Hot-swap is now pre-flight-safe (
runtime.swapPlugin()): semver, dependency presence, andvalidateConfigare all checked before any side effect. If any pre-flight check rejects, the running plugin is completely untouched. Previously, a failed config validation tore down the running plugin with no recovery. (Note: the residual atomicity window — a throw from the new plugin's own setup — is closed in 0.6.0.) - SemVer 2.0 pre-release support:
isNewerVersion(and thereforeswapPlugin) now correctly handles1.2.4-rc.1-style versions, backed by thesemverpackage. - Concurrent swap protection: a second
swapPlugincall for the same plugin while one is in flight rejects withPluginSwapErrorinstead of corrupting registry state. - Error class preservation:
runtime.initialize()failures now re-throw the original error class (e.g.ValidationError) with custom properties andError.causeintact —instanceof-based error handling works as documented. - Rollback completeness: a plugin whose setup throws mid-way no longer leaks its partially-registered actions/screens/services.
- Loader diagnostics: missing dependencies are now warned about at discovery time, pointing at the likely load failure instead of a confusing init-time error.
PluginRegistry.reset()replaces the misleadingly-namedclear()(deprecated alias retained until 0.6).
- Action Retry: New
retryfield onActionDefinition. On failure, the action is retried up toretrytimes with exponential backoff (100ms, 200ms, 400ms…). Timeout and memory errors are never retried. - Action Memory Limit: New
memoryLimitMbfield onActionDefinition. Measures heap delta before/after execution and throwsActionMemoryErrorif the limit is exceeded. No-op in browser environments whereprocess.memoryUsageis unavailable. - Execution Recorder (
ctx.trace): New first-class observability API onRuntimeContext. Every action run produces a frozenTraceEntrywithrunId,actionId,input,output,status,durationMs,startedAt,error, andattempt. Accessible viactx.trace.getEntries(),ctx.trace.getEntriesFor(id), andctx.trace.clear(). Capped at 1000 entries by default. ActionMemoryError: New error class thrown when an action exceeds itsmemoryLimitMb.ExecutionRecorderImpl: New exported class for the in-memory recorder implementation.- Types:
TraceEntry,TraceStatus,ExecutionRecorder,PluginSwapErrorexported from the core package.ActionMetadatanow includesretryandmemoryLimitMbfields.
ActionEngineconstructor: Now accepts an optionalonTracecallback for recording execution entries. Fully backward compatible — existing code passing only a logger is unaffected.RuntimeContextImplconstructor: Now accepts an optionalExecutionRecorderImplinstance. Falls back to a standalone recorder when not provided (e.g. in tests).
✅ Browser Compatibility - Fixed critical runtime crash in browsers by lazy-loading Node.js dependencies
📝 Documentation - Updated all examples to use proper TypeScript import type syntax
🔧 Stability - Improved test reliability for performance monitoring
✅ Service Locator API - New ctx.services API for type-safe inter-plugin communication
📝 Service Locator Guide - New dedicated guide for using the Service Locator pattern
✅ Config Validation - Validate plugin configuration before setup runs with detailed error reporting
📝 Logger Documentation - Comprehensive guide to the built-in logging system and external integrations
📊 Optimized Telemetry - Cleaner startup logs with consolidated plugin loading information
🔍 Introspection - Enhanced plugin metadata for better runtime transparency
🔍 Plugin Discovery - Automatic plugin loading from file paths and npm packages
🔄 Dependency Resolution - Automatic topological sorting for correct plugin initialization order
🛠️ Enhanced DX - Better error messages with dependency hints for missing actions
🚀 Production Ready - All critical bugs fixed based on real-world usage feedback
✅ Verified Stable - Tested and validated in production migrations
// Automatic plugin discovery - no manual registration needed!
const runtime = new Runtime<MyConfig>({
config: myConfig,
// Load plugins from directories
pluginPaths: [
'./plugins', // Load all plugins from directory
'./custom-plugin.js' // Load specific plugin file
],
// Load plugins from npm packages
pluginPackages: [
'@my-org/auth-plugin',
'my-custom-plugin'
]
});
await runtime.initialize(); // Plugins auto-loaded and sorted by dependencies!🎯 Generic Runtime/Context - Full TypeScript generic support for type-safe configuration
⚡ Sync Config Access - Direct synchronous access to configuration via ctx.config
🔗 Plugin Dependencies - Explicit dependency resolution with validation
📝 Enhanced Logger - Logger available on context for all plugins
🔄 100% Backward Compatible - All v0.1.x code continues to work
// v0.1.x
const runtime = new Runtime({
hostContext: { config: myConfig }
});
// v0.2.0 - Fully typed!
interface MyConfig { apiUrl: string; }
const runtime = new Runtime<MyConfig>({
config: { apiUrl: 'https://api.example.com' }
});- Installation - Install and setup
- API Reference - Complete TypeScript API
- Core Concepts - Understand the fundamentals
- Your First Plugin - Build your first feature
- Logger Guide - Master the built-in logging system
- Config Validation - How to validate plugin configuration
- Service Locator - Type-safe inter-plugin communication
- v0.1.x → v0.2.0 Migration - Complete migration walkthrough
- Plugin Dependencies - Dependency patterns and best practices
- Sync vs Async Patterns - Configuration and execution patterns
- Real-World Examples - Production-ready implementations
- Migration Guide - Integrate with existing apps
- Examples Guide - Learn through code examples
- Browser Extensions - Build browser tools
- CLI Applications - Command-line tools
- Real-Time Apps - Collaboration and sync
- Architecture - How it works under the hood
- Troubleshooting - Common issues and solutions
Skeleton Crew Runtime is a lightweight foundation for building applications where features can be added, removed, or replaced without touching existing code. Think VS Code's extension system, but for any JavaScript application.
Core idea: Your app is a collection of plugins. Each plugin registers actions (business logic), screens (UI definitions), and events (communication). The runtime coordinates everything.
Result: Add features by dropping in plugins. Remove features by taking them out. No refactoring. No breaking changes.
You're building something modular and you might know these challenges:
- Wiring up infrastructure - Event buses, plugin loaders, action registries
- Tight coupling - Changing one feature breaks three others
- Testing nightmares - Can't test features in isolation
- Framework lock-in - Married to React/Vue/whatever forever
- Refactoring hell - Adding features means touching existing code
Skeleton Crew Runtime gives you:
- Plugin isolation - Features don't know about each other
- Event-driven communication - Plugins coordinate without coupling
- Framework freedom - Business logic separate from UI
- Testability - Mock what you need, test what matters
- Minimal core - < 5KB, zero dependencies
Here's a complete plugin that adds a feature to your app:
import { Runtime } from 'skeleton-crew';
import type { PluginDefinition, RuntimeContext } from 'skeleton-crew';
// v0.2.0: Define your config interface
interface AppConfig {
notifications: {
apiKey: string;
defaultTimeout: number;
};
features: {
pushNotifications: boolean;
};
}
// 1. Create typed runtime
const runtime = new Runtime<AppConfig>({
config: {
notifications: {
apiKey: process.env.NOTIFICATION_API_KEY!,
defaultTimeout: 5000
},
features: {
pushNotifications: true
}
}
});
await runtime.initialize();
const ctx = runtime.getContext();
// 2. Write a plugin (this is a complete feature)
const notificationsPlugin: PluginDefinition<AppConfig> = {
name: 'notifications',
version: '1.0.0',
dependencies: [], // v0.2.0: Explicit dependencies
setup(ctx: RuntimeContext<AppConfig>) {
// ✅ Fully typed config access
const { notifications, features } = ctx.config;
if (!features.pushNotifications) {
ctx.logger.info('Push notifications disabled');
return;
}
// Register business logic with type safety
ctx.actions.registerAction<
{ userId: string; message: string },
{ success: boolean; messageId: string }
>({
id: 'notifications:send',
handler: async ({ userId, message }, ctx) => {
// ✅ Typed config access in handlers
const { apiKey, defaultTimeout } = ctx.config.notifications;
// Your logic here
const messageId = await sendPushNotification(userId, message, {
apiKey,
timeout: defaultTimeout
});
// Let other plugins know
ctx.events.emit('notification:sent', { userId, messageId });
return { success: true, messageId };
},
timeout: notifications.defaultTimeout
});
// React to other plugins
ctx.events.on('user:registered', async (user: any) => {
await ctx.actions.runAction('notifications:send', {
userId: user.id,
message: 'Welcome!'
});
});
ctx.logger.info('Notifications plugin initialized');
}
};
// 3. Register and use
ctx.plugins.registerPlugin(notificationsPlugin);
// anywhere in your app - fully typed!
const result = await ctx.actions.runAction('notifications:send', {
userId: '123',
message: 'Your order shipped!'
});
console.log(`Message sent: ${result.messageId}`);That's it. The plugin is isolated, testable, fully typed, and can be removed without breaking anything.
No more manual plugin registration! The runtime can automatically discover and load plugins:
import { Runtime } from 'skeleton-crew';
const runtime = new Runtime<MyConfig>({
config: myConfig,
// Discover plugins from file system
pluginPaths: [
'./src/plugins', // Directory: loads all .js/.mjs files
'./auth-plugin.js', // Single file: loads specific plugin
'./dist/plugins' // Works with compiled TypeScript too!
],
// Discover plugins from npm packages
pluginPackages: [
'@my-org/auth-plugin', // npm package with plugin export
'my-logging-plugin' // Any package that exports a plugin
]
});
await runtime.initialize();
// ✅ All plugins auto-loaded and sorted by dependencies!Dependency Resolution: Plugins are automatically sorted by their dependencies array, so they initialize in the correct order.
A plugin is just an object with a name and a setup function:
import type { PluginDefinition, RuntimeContext } from 'skeleton-crew';
// v0.2.0: Define your config type
interface MyAppConfig {
apiUrl: string;
features: { analytics: boolean };
}
export const myPlugin: PluginDefinition<MyAppConfig> = {
name: 'my-plugin',
version: '1.0.0',
dependencies: ['config'], // v0.2.0: Explicit dependencies
setup(ctx: RuntimeContext<MyAppConfig>) {
// ✅ Fully typed config access
const { apiUrl, features } = ctx.config;
if (features.analytics) {
ctx.logger.info(`Plugin initialized for ${apiUrl}`);
}
// Register your feature here
},
dispose(ctx: RuntimeContext<MyAppConfig>) {
// Optional: cleanup resources when plugin is removed
// Use this for: closing connections, clearing timers, releasing memory
// Event listeners auto-cleanup, so you usually don't need this
}
};Actions are named functions that do work:
// v0.2.0: Type-safe action registration
interface CreateOrderParams {
customerId: string;
items: Array<{ id: string; quantity: number }>;
}
interface Order {
id: string;
customerId: string;
total: number;
status: 'pending' | 'confirmed';
}
// Register an action
ctx.actions.registerAction<CreateOrderParams, Order>({
id: 'orders:create',
handler: async (orderData, ctx) => {
// ✅ Typed config access
const { apiUrl } = ctx.config;
// ✅ Typed parameters
const { customerId, items } = orderData;
const order = await createOrder(customerId, items);
ctx.events.emit('order:created', order);
ctx.logger.info(`Order created: ${order.id}`);
return order; // ✅ Typed return value
},
timeout: 10000 // Optional timeout
});
// Call from anywhere - fully typed!
const order = await ctx.actions.runAction<CreateOrderParams, Order>(
'orders:create',
{ customerId: '123', items: [{ id: 'item1', quantity: 2 }] }
);Plugins communicate without knowing about each other:
// Plugin A: Emit event
ctx.events.emit('order:created', order);
// Plugin B: React (doesn't know about Plugin A)
ctx.events.on('order:created', (order) => {
sendConfirmationEmail(order);
});
// v0.2.0: Async event handling
await ctx.events.emitAsync('order:created', order); // Wait for all handlersDirect synchronous access to typed configuration:
import { Runtime } from 'skeleton-crew';
interface AppConfig {
database: { url: string; maxConnections: number };
api: { baseUrl: string; timeout: number };
features: { caching: boolean; analytics: boolean };
}
const runtime = new Runtime<AppConfig>({
config: {
database: {
url: process.env.DATABASE_URL!,
maxConnections: 10
},
api: {
baseUrl: 'https://api.example.com',
timeout: 5000
},
features: {
caching: true,
analytics: process.env.NODE_ENV === 'production'
}
}
});
// In plugins: direct typed access
setup(ctx: RuntimeContext<AppConfig>) {
// ✅ Fully typed, synchronous access
const { database, api, features } = ctx.config;
if (features.caching) {
initializeCache();
}
// ✅ Available in action handlers
ctx.actions.registerAction({
id: 'api:request',
handler: async (endpoint: string) => {
const { baseUrl, timeout } = ctx.config.api;
return await fetch(`${baseUrl}${endpoint}`, { timeout });
}
});
}Inject your existing services so plugins can use them:
import { Runtime } from 'skeleton-crew';
const runtime = new Runtime<AppConfig>({
config: myTypedConfig,
hostContext: {
// Legacy services
db: yourDatabase,
cache: redisClient,
logger: yourLogger
}
});
await runtime.initialize();
const ctx = runtime.getContext();
// Plugins access via ctx.host (for legacy integration)
const { db, logger } = ctx.host;Plugins can register and consume shared services without hard dependency coupling:
// Plugin A: Register a service
setup(ctx) {
const myService = {
doSomething: () => console.log('Service in action!')
};
ctx.services.register('my-api', myService);
}
// Plugin B: Consume the service
setup(ctx) {
// Wait for the providing plugin to initialize first!
const api = ctx.services.get<MyApiType>('my-api');
api.doSomething();
}Define screens that any UI framework can render:
ctx.screens.registerScreen({
id: 'orders:list',
title: 'Orders',
component: 'OrderListComponent' // string, class, function, or any type
});Skeleton Crew works for any modular JavaScript application:
- CLI tools - Task runners, deployment scripts, dev environments
- Browser extensions - Tab managers, productivity tools, dev tools
- Build tools - Custom bundlers, code generators, linters
- Admin panels - User management, content moderation, analytics
- Dashboards - Monitoring, reporting, data visualization
- Workflow tools - Approval systems, task management, automation
- Collaboration tools - Shared editing, presence, chat
- Live dashboards - Stock tickers, sports scores, IoT monitoring
- Multiplayer features - Game state sync, player coordination
- Plugin marketplaces - Let users extend your app
- White-label products - Different features for different customers
- Microservices - Coordinate distributed services
Not ideal for: Public-facing websites (use Next.js), complex routing (use React Router), heavy state management (use Redux).
What you'll see: Interactive CLI that runs commands, shows output, handles errors. All plugin-based.
# Build a command palette for Git, npm, and Docker:
cd demo/dev-launcher
npm install && npm startWhat you'll see: Multiple clients syncing state in real-time. No Firebase, no Socket.io boilerplate.
# Build a multi-user sync system:
cd demo/collab-hub
npm install && npm run build
npm run server # Terminal 1
npm run client # Terminal 2-3No. Skeleton Crew runs alongside your existing code. Write new features as plugins, keep old code unchanged.
You can gradually replace legacy code with plugins using feature flags. Or don't — both approaches work fine.
Yes. Skeleton Crew is UI-agnostic. Use React, Vue, Svelte, or no UI at all. The runtime doesn't care.
Possibly. If you have a simple app with no legacy code and no plans to grow, you might not need this. But if you're dealing with technical debt or planning for modularity, it's a good fit.
Less than 5KB gzipped. Minimal overhead.
Yes. The runtime is stable and tested. Start with non-critical features, then expand.
Built for developers who need to modernize legacy apps without the risk of a full rewrite.