{"id":11999,"library":"seneca","title":"Seneca Microservices Framework","description":"Seneca is a mature Node.js microservices framework designed to help organize application business logic through a pattern-matching approach to message passing. Currently at stable version 3.38.0, its release cadence is active but irregular, with a focus on stability and a smaller core. Key differentiators include its flexible pattern-matching for defining commands, transport independence that abstracts message delivery, and a robust ecosystem of plugins for common microservice concerns like data storage, user management, and distributed logic. The framework emphasizes breaking down applications into 'stuff that happens' rather than strict data models, providing a flexible toolkit for building Minimum Viable Products and complex distributed systems. It supports Node.js versions 10 and above and ships with TypeScript types.","status":"active","version":"3.38.0","language":"javascript","source_language":"en","source_url":"https://github.com/senecajs/seneca","tags":["javascript","micro","service","microservice","micro-service","microservices","micro-services","services","micro services","typescript"],"install":[{"cmd":"npm install seneca","lang":"bash","label":"npm"},{"cmd":"yarn add seneca","lang":"bash","label":"yarn"},{"cmd":"pnpm add seneca","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` is the primary usage pattern demonstrated in official examples, compatible with Node.js >=10.","wrong":"import Seneca from 'seneca'","symbol":"Seneca","correct":"const Seneca = require('seneca')"},{"note":"For ESM environments (Node.js versions with stable ESM support), `Seneca` is the default export. Ensure your project is configured for ESM if using this import style.","wrong":"const Seneca = require('seneca')","symbol":"Seneca","correct":"import Seneca from 'seneca'"},{"note":"Utility modules like Eraro, Jsonic, Nid, and Patrun are exposed directly on the main Seneca export via `Seneca.util` since v3.7.0. They are not separate top-level imports.","symbol":"Seneca.util","correct":"const Seneca = require('seneca'); const { Eraro, Jsonic, Nid, Patrun } = Seneca.util;"}],"quickstart":{"code":"'use strict'\n\nvar Seneca = require('seneca')\n\nfunction rejector () {\n  this.add('cmd:run', (msg, done) => {\n    return done(null, {tag: 'rejector'})\n  })\n}\n\nfunction approver () {\n  this.add('cmd:run', (msg, done) => {\n    return done(null, {tag: 'approver'})\n  })\n}\n\nfunction local () {\n  this.add('cmd:run', function (msg, done) {\n    this.prior(msg, (err, reply) => {\n      return done(null, {tag: reply ? reply.tag : 'local'})\n    })\n  })\n}\n\nSeneca()\n  .use(approver)\n  .listen({type: 'http', port: '8260', pin: 'cmd:*'})\n\nSeneca()\n  .use(rejector)\n  .listen(8270)\n\nfunction handler (err, reply) {\n  console.log(err, reply)\n}\n\nSeneca()\n  .use(local)\n  .act('cmd:run', handler)\n\nSeneca()\n  .client({port: 8270, pin: 'cmd:run'})\n  .client({port: 8260, pin: 'cmd:run'})\n  .use(local)\n  .act('cmd:run', handler)\n\nSeneca()\n  .client({port: 8260, pin: 'cmd:run'})\n  .client({port: 8270, pin: 'cmd:run'})\n  .use(local)\n  .act('cmd:run', handler)","lang":"javascript","description":"This example demonstrates defining and loading plugins, setting up HTTP listeners for microservices, and client-side message dispatching with pattern matching and priority handling."},"warnings":[{"fix":"Identify missing plugin functionality, install the corresponding `seneca-` plugin from npm, and add `seneca.use('plugin-name')` to your Seneca instance initialization.","message":"Seneca v3.0.0 removed all default plugins (except `seneca-transport`) to make the core smaller and more stable. Applications upgrading from v2.x or earlier must explicitly install and load any previously implicitly available plugins (e.g., `seneca-basic`, `seneca-web`, etc.).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To restore entity functionality, install `seneca-entity` (`npm install seneca-entity`) and explicitly load it with `seneca.use('entity')`.","message":"Seneca v2.0.0 made a significant change by no longer installing and using the `seneca-entity` plugin by default. Projects relying on database entity interactions implicitly will encounter errors.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"For pretty logging, install `seneca-legacy-logger` and use it. For custom loggers, ensure they are compatible with JSON input or update them accordingly.","message":"Since v3.0.0, Seneca defaults to JSON output for logs. If you relied on the previous 'pretty' logging format or had custom log handlers, you will need to adjust your logging configuration or use the `seneca-legacy-logger` plugin.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Review your action callback implementations to standardize on an error-first or error-omitting style for consistency, especially when integrating with new plugins or migrating old code.","message":"Seneca v3.3.0 introduced a change allowing action callbacks to omit the Error parameter (hapi style). While this adds flexibility, it can lead to inconsistent callback signatures if not managed carefully across your codebase.","severity":"gotcha","affected_versions":">=3.3.0"},{"fix":"It is highly recommended to upgrade to the latest stable 3.x version of Seneca to benefit from critical memory leak and stability fixes.","message":"Earlier versions of Seneca (prior to v3.7.0 and v3.2.0) had known memory leak issues, specifically related to the history mechanism and Gate Executor timeouts. Running older 3.x versions might lead to resource exhaustion over time.","severity":"gotcha","affected_versions":"<3.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the plugin via `npm install seneca-entity` and add `seneca.use('entity')` to your Seneca instance initialization.","cause":"The `seneca-entity` plugin, responsible for database entity operations, was removed from Seneca's core distribution in v2.0.0 and must now be explicitly installed and loaded.","error":"Error: Seneca: Plugin 'seneca-entity' not found."},{"fix":"Verify the exact pattern used in `seneca.act()` matches an existing `seneca.add()` definition. Ensure all necessary plugins defining actions are loaded using `seneca.use()`, and check that message properties align with the pattern's requirements.","cause":"The message sent via `seneca.act()` does not match any registered action patterns (`seneca.add()`). This can be due to a typo, an unloaded plugin that defines the action, or incorrect message parameters.","error":"Error: Seneca: No matching action for pattern { cmd: 'my-command', ... }"},{"fix":"If using CommonJS, ensure you're using `const Seneca = require('seneca'); const seneca = Seneca();`. If using ESM, ensure `import Seneca from 'seneca'; const seneca = Seneca();` and that your Node.js environment is configured for ESM.","cause":"This error typically occurs when attempting to call `new Seneca()` or `Seneca()` when `Seneca` was imported using a CommonJS `require` statement, but the module is expecting a default export in an ESM context, or vice-versa.","error":"TypeError: Seneca is not a constructor"},{"fix":"Ensure that no other applications or services are running on the desired port. If running multiple Seneca instances, configure each to use a unique port for its listeners, or ensure previous processes are properly shut down before starting new ones.","cause":"The specified port for a Seneca transport listener (e.g., HTTP) is already being used by another process or another instance of your application.","error":"Error: listen() failed: port already in use"}],"ecosystem":"npm"}