A Node.js toolkit for Microservice architectures

	This open source module is sponsored and supported by Voxgig.

seneca

• Lead Maintainer: Richard Rodger
• Sponsor: voxgig

Seneca is a toolkit for writing microservices and organizing the business logic of your application. You describe what your system does as messages, and write actions that handle them. Which action runs is decided by pattern matching on the message, so the code that handles a message, and the process it runs in, can change without changing the code that sends it.

Seneca provides:

• pattern matching: messages are plain objects, routed to the most specific matching action; special cases are new patterns, not branches
• composition: functionality is grouped into plugins that can extend each other by overriding patterns and calling the prior action
• transport independence: the same actions run in one process or across many, connected by transport plugins
• maturity: in production since 2010, with a deep and wide ecosystem of plugins
• a book: a guide to designing microservice architectures: taomicro

Install

npm install seneca

Seneca 4 requires Node.js 22 or later; Node.js 24 is the default version used for development, continuous integration and releases (see .nvmrc).

Network transports are plugins. For HTTP and TCP install seneca-transport as well.

Example

A plugin is a function that adds actions for patterns:

const Seneca = require('seneca')

function math(options) {
  // An action for a pattern: any message with role:math and cmd:sum
  this.add('role:math,cmd:sum', function (msg, reply) {
    reply({ answer: msg.left + msg.right })
  })

  // A more specific pattern handles a special case
  this.add('role:math,cmd:sum,integer:true', function (msg, reply) {
    reply({ answer: Math.floor(msg.left) + Math.floor(msg.right) })
  })
}

const seneca = Seneca({ log: 'warn' }).use(math)

seneca.act('role:math,cmd:sum,left:1.5,right:2.5', Seneca.util.print)
// { answer: 4 }

seneca.act('role:math,cmd:sum,left:1.5,right:2.5,integer:true', Seneca.util.print)
// { answer: 3 }

Promises are built in (seneca.message and seneca.post), and the same plugin can be served over the network with a transport plugin:

// service process
Seneca().use(math).use('seneca-transport').listen({ port: 8260, pin: 'role:math,cmd:*' })

// client process
const client = Seneca().use('seneca-transport').client({ port: 8260, pin: 'role:math,cmd:*' })
const result = await client.post('role:math,cmd:sum,left:1,right:2')

Documentation

The documentation lives in docs/ and is organized in four sections:

• Tutorials: start with Getting started, then Microservices with transports and Writing a plugin.
• How-to guides: configuring options and logging, handling errors, testing, priors, transports, plugins, debugging, graceful shutdown, running in production, migrating from Seneca 3.
• Reference: the instance API, options, patterns, message directives, plugin definition, logging, error codes, transport and more, with a feature index.
• Explanation: why Seneca, pattern matching, message lifecycle, plugins and composition, transport independence and the error model.

Changes between versions are listed in CHANGES.md; Migrate from Seneca 3 covers upgrading.

Running

node service.js                   # JSON logs at level info, for log collectors
node service.js --seneca.test     # readable logs with full detail, for development
node service.js --seneca.log=warn # quieter

See Command line and environment.

Support

If you're using this module and need help, you can:

• Post a github issue
• Tweet to @senecajs
• Ask on the Gitter

Contributing

The Senecajs org encourages participation. If you feel you can help in any way, be it with bug reporting, documentation, examples, extra testing, or new features feel free to create an issue, or better yet, submit a Pull Request. For more information on contribution please see our Contributing guide.

Test

The tests use the Node.js built-in test runner (node:test) and need Node.js 22 or later (24 is the default). To run them locally, with a coverage summary:

npm test

To run only the tests whose names match a pattern:

npm run test-some -- close

To write an lcov coverage report to coverage/lcov.info:

npm run coverage

Maintainers: see Create a release.

Background

Seneca is sponsored and supported by Voxgig.

Copyright (c) 2010-2026 Richard Rodger and other contributors; Licensed under MIT.