Registering a Custom Plugin in Kraken.js

Learn how to add a custom plugin to Kraken.js: register it in the config, implement an async init function, and avoid common pitfalls like missing callbacks or route collisions.

Why Plugin Registration Matters

Kraken.js keeps its core lightweight by delegating extended functionality to plugins. A plugin is simply a Node module that exports an init function. When the application starts, Kraken loads each plugin listed in config/default.json, calls its init with the app instance, and waits for the callback (or promise) to finish. Understanding this sequence lets you add routes, middleware, or services without touching the core.

Step‑by‑Step Example: A “Hello” Route Plugin

Create the plugin folder
Place the plugin under plugins/hello and add an index.js file.

mkdir -p plugins/hello
cat > plugins/hello/index.js <<'EOF'
module.exports.init = function (app, done) {
  // Register a simple GET route
  app.get('/hello', (req, res) => res.send('Hello, world!'));
  // Signal that the plugin is ready
  done();
};
EOF

Register the plugin in the config
Edit config/default.json to include the relative path.
```
{
  "plugins": ["./plugins/hello"]
}
```
Start the application
Run node app.js (or npm start if you have a script). Kraken will:
1. Read config/default.json.
2. Resolve ./plugins/hello to the module.
3. Call init(app, done).
4. Wait for done() before proceeding to the next plugin.
Verify the route
Open http://localhost:3000/hello in a browser or use curl.
```
curl http://localhost:3000/hello
# Expected output: Hello, world!
```
Check the logs
Kraken prints a message for each plugin during startup. Look for:
```
[INFO] Initializing plugin: ./plugins/hello
```

Asynchronous Initialization and Error Handling

The init function can perform async work, such as connecting to a database. In that case, you must either invoke the callback after the async task completes or return a promise. If you forget to call the callback, Kraken will hang at startup, waiting forever for the plugin to finish.

module.exports.init = async function (app) {
  await db.connect();
  app.use('/api', apiRouter);
  // Returning a promise signals completion
  return Promise.resolve();
};

Errors thrown inside init are caught by Kraken and logged. To propagate the error and abort startup, rethrow or reject the promise.

Order and Dependencies

Plugins are initialized in the order they appear in the plugins array. A later plugin can rely on services registered by an earlier one, but you must be careful not to modify routes after they are defined. For example, adding a route in plugin B that matches a path already handled by plugin A will override the earlier handler, potentially breaking functionality.

Common Pitfalls

Missing callback – Causes a deadlock. Always call done() or return a promise.
Duplicate plugin names – If the same module is listed twice, Kraken will initialize it twice, which can lead to duplicate routes or services.
Using internal app properties – The app object may expose undocumented properties that change between releases. Stick to the documented app.use(), app.get(), etc.
Path resolution errors – Relative paths must be relative to the configuration file. Absolute paths can break when the app is moved.

Limitations of the Plugin API

No built‑in dependency injection or namespacing – plugins must manage their own scope.
Only synchronous or promise‑based async patterns are supported; callback‑only patterns are discouraged in newer releases.
Plugin configuration is flat; complex nested options require manual parsing.

Practical Checklists Before Deploying a Plugin

Run npm test or a lightweight integration test that sends a request to each route the plugin registers.
Verify that the plugin appears in the startup log and that no errors are reported.
Ensure the plugin does not modify routes that other plugins rely on; use app._router.stack to inspect route order if needed.
Confirm that any external resources (DB, cache, message bus) are cleaned up on process.on('SIGTERM') if the plugin opens connections.

Conclusion

Registering a plugin in Kraken.js is a matter of exporting an init function, adding the module to the plugins array, and handling async initialization correctly. By respecting the order, avoiding internal APIs, and testing the route list, you can safely extend Kraken with reusable modules that remain maintainable across framework upgrades.

How to Register and Use a Custom Plugin in Kraken.js