@libria/plugin-loader

A TypeScript-first plugin system for Node.js applications with dependency resolution, lifecycle hooks, and hot-reloading.

Features

• Dependency Resolution - Plugins can depend on other plugins with semver version requirements
• Circular Dependency Detection - Throws clear errors when circular dependencies are found
• Async Plugin Initialization - Factories can be async for loading configs, connecting to databases, etc.
• Lifecycle Hooks - onLoad and onUnload hooks for setup and cleanup
• Hot-Reloading - Watch for file changes and reload plugins on the fly
• Plugin Queries - Find plugins by type, get metadata, list all loaded plugins
• TypeScript First - Full type safety with generics for plugin APIs
• ESM & CJS Support - Load plugins in either module format

Installation

npm install @libria/plugin-loader

Quick Start

1. Define a Plugin

Create a plugin with definePlugin:

// plugins/greeter/src/index.ts
import { definePlugin } from '@libria/plugin-loader';

interface GreeterAPI {
    greet(name: string): string;
}

export default definePlugin<GreeterAPI>({
    id: 'greeter',
    pluginType: 'util',

    create(ctx) {
        return {
            api: {
                greet(name) {
                    return `Hello, ${name}!`;
                }
            }
        };
    }
});

2. Create a Plugin Manifest

Each plugin needs a plugin.json in its directory:

{
    "id": "greeter",
    "name": "Greeter Plugin",
    "pluginType": "util",
    "version": "1.0.0",
    "module": "./dist/index.mjs"
}

3. Load and Use Plugins

import { PluginManager } from '@libria/plugin-loader';

const manager = new PluginManager();

// Load all plugins from a directory
await manager.loadPlugins(['./plugins/*']);

// Use a plugin
const greeter = manager.getPlugin<GreeterAPI>('greeter');
console.log(greeter.greet('World')); // "Hello, World!"

Plugin Manifest

The plugin.json file defines your plugin's metadata:

{
    "id": "my-plugin",
    "name": "My Plugin",
    "pluginType": "feature",
    "version": "1.0.0",
    "description": "Optional description",
    "module": "./dist/index.mjs",
    "main": "./dist/index.cjs",
    "dependencies": [
        { "id": "other-plugin", "version": "^1.0.0" }
    ]
}

| Field | Required | Description | |-------|----------|-------------| | id | Yes | Unique identifier for the plugin | | pluginType | Yes | Category/type of the plugin (for queries) | | version | Yes | Semver version string | | name | No | Human-readable name | | description | No | Plugin description | | module | No* | Path to ESM entry point | | main | No* | Path to CJS entry point | | dependencies | No | Array of plugin dependencies |

*At least one of module or main is required.

Plugin Dependencies

Plugins can depend on other plugins. Dependencies are loaded first, and the loading order is determined by topological sort.

{
    "id": "plugin-a",
    "pluginType": "feature",
    "version": "1.0.0",
    "module": "./dist/index.mjs",
    "dependencies": [
        { "id": "plugin-b", "version": "^1.0.0" },
        { "id": "plugin-c", "version": ">=2.0.0" }
    ]
}

Access dependencies in your plugin via the context:

export default definePlugin<MyAPI>({
    id: 'plugin-a',
    pluginType: 'feature',

    create(ctx) {
        // Dependencies are guaranteed to be loaded
        const pluginB = ctx.getPlugin<PluginBAPI>('plugin-b');
        const pluginC = ctx.getPlugin<PluginCAPI>('plugin-c');

        return {
            api: {
                doSomething() {
                    return pluginB.getValue() + pluginC.calculate();
                }
            }
        };
    }
});

Version Requirements

Dependencies use semver ranges:

• "1.0.0" - Exact version
• "^1.0.0" - Compatible with 1.x.x
• "~1.0.0" - Compatible with 1.0.x
• ">=1.0.0 <2.0.0" - Range
• "*" - Any version

Async Initialization

Plugin factories can be async for loading configs, connecting to services, etc:

export default definePlugin<DatabaseAPI>({
    id: 'database',
    pluginType: 'service',

    async create(ctx) {
        const config = await loadConfig();
        const connection = await connectToDatabase(config);

        return {
            api: {
                query: (sql) => connection.query(sql),
                close: () => connection.close()
            }
        };
    }
});

Lifecycle Hooks

Plugins can implement lifecycle hooks for setup and cleanup:

export default definePlugin<MyAPI>({
    id: 'my-plugin',
    pluginType: 'feature',

    create(ctx) {
        let intervalId: NodeJS.Timeout;

        return {
            api: {
                // ... your API
            },

            onLoad() {
                // Called after plugin is registered
                console.log('Plugin loaded!');
                intervalId = setInterval(() => {
                    console.log('heartbeat');
                }, 1000);
            },

            async onUnload() {
                // Called before plugin is unloaded
                // Can be async for cleanup
                clearInterval(intervalId);
                await saveState();
                console.log('Plugin unloaded!');
            }
        };
    }
});

Hot-Reloading

Reload plugins without restarting your application:

const manager = new PluginManager();
await manager.loadPlugins(['./plugins/*']);

// Manual reload
await manager.reloadPlugin('my-plugin');

// Watch for file changes
await manager.watch(['./plugins/*'], (id, event, error) => {
    if (event === 'reload') {
        console.log(`Plugin ${id} reloaded successfully`);
    }
    if (event === 'error') {
        console.error(`Failed to reload ${id}:`, error);
    }
});

// Stop watching
await manager.stopWatching();

Plugin Queries

Query loaded plugins by type or get metadata:

// Get all loaded plugin IDs
const ids = manager.getPluginIds();
// ['greeter', 'database', 'logger']

// Check if a plugin is loaded
if (manager.hasPlugin('greeter')) {
    // ...
}

// Get metadata for a plugin
const meta = manager.getPluginMetadata('greeter');
// { id: 'greeter', name: 'Greeter Plugin', version: '1.0.0', ... }

// Get all plugins of a specific type
const services = manager.getPluginsByType('service');
// [{ id: 'database', ... }, { id: 'cache', ... }]

// Get all metadata
const allMeta = manager.getAllMetadata();

Graceful Shutdown

Properly unload all plugins (calls onUnload hooks in reverse order):

process.on('SIGTERM', async () => {
    await manager.shutdown();
    process.exit(0);
});

Error Handling

The library provides typed errors for common scenarios:

import {
    PluginLoadError,           // Failed to load plugin module
    PluginInvalidExportError,  // Plugin doesn't export a valid factory
    PluginNotFoundError,       // Plugin not found (getPlugin, reload, unload)
    ManifestNotFoundError,     // plugin.json not found during reload
    DuplicatePluginError,      // Attempting to register same ID twice
    CircularDependencyError,   // Circular dependency detected
    DependencyNotFoundError,   // Required dependency not found
    VersionMismatchError,      // Dependency version doesn't match
} from '@libria/plugin-loader';

try {
    await manager.loadPlugins(['./plugins/*']);
} catch (err) {
    if (err instanceof CircularDependencyError) {
        console.error('Circular dependency:', err.cycle.join(' -> '));
    }
    if (err instanceof VersionMismatchError) {
        console.error(
            `${err.packageId}@${err.actualVersion} doesn't satisfy ${err.requiredVersion}`
        );
    }
}

try {
    await manager.reloadPlugin('my-plugin');
} catch (err) {
    if (err instanceof PluginNotFoundError) {
        console.error(`Plugin ${err.id} is not loaded`);
    }
    if (err instanceof ManifestNotFoundError) {
        console.error(`Manifest missing for ${err.pluginId} in ${err.dir}`);
    }
}

API Reference

PluginManager

| Method | Description | |--------|-------------| | loadPlugins(patterns: string[]) | Load plugins from glob patterns | | getPlugin<T>(id: string): T | Get a plugin's API by ID | | hasPlugin(id: string): boolean | Check if a plugin is loaded | | getPluginIds(): string[] | Get all loaded plugin IDs | | getPluginMetadata(id: string) | Get metadata for a plugin | | getPluginsByType(type: string) | Get all plugins of a type | | getAllMetadata() | Get all plugin metadata | | reloadPlugin(id: string) | Hot-reload a specific plugin | | unloadPlugin(id: string) | Unload a specific plugin | | watch(patterns, callback) | Watch for file changes | | stopWatching() | Stop watching for changes | | shutdown() | Unload all plugins and cleanup | | getContext() | Get the internal plugin context |

definePlugin<T>(factory: PluginFactory<T>)

Helper function for defining plugins with proper typing.

PluginContext

Passed to the create function:

| Method | Description | |--------|-------------| | getPlugin<T>(id: string): T | Get another plugin's API | | hasPlugin(id: string): boolean | Check if a plugin is loaded |

LibriaPlugin<T>

The return type of create:

interface LibriaPlugin<T> {
    api: T;
    onLoad?(): void | Promise<void>;
    onUnload?(): void | Promise<void>;
}

Directory Structure

Recommended project structure:

my-app/
├── src/
│   └── index.ts
├── plugins/
│   ├── greeter/
│   │   ├── plugin.json
│   │   ├── src/
│   │   │   └── index.ts
│   │   └── dist/
│   │       └── index.mjs
│   └── database/
│       ├── plugin.json
│       ├── src/
│       │   └── index.ts
│       └── dist/
│           └── index.mjs
└── package.json

License

MIT