TypeScript icon, indicating that this package has built-in type declarations

    1.0.9 • Public • Published

    Reshuffle Integration Framework

    Reshuffle is a lightweight and open source integration framework. With Reshuffle, you can build integrations, workflows, and connect systems.

    Here is a simple workflow that sends a Text message when an urgent Email arrives:

    const { Reshuffle } = require('reshuffle')
    const { IMAPConnector } = require('reshuffle-imap-connector')
    const { TwilioConnector } = require('reshuffle-twilio-connector')
    const app = new Reshuffle()
    const imap = new IMAPConnector(app, emailServerOptions)
    const twilioConnector = new TwilioConnector(app, twilioOptions)
    imap.on({ mailbox: 'INBOX' }, (event, app) => {
      if (event.mail.headers.get('subject').startsWith('URGENT ALERT:')) {
        twilioConnector.sendSMS('We got urgent alert', '+16502224533')


    $ npm install reshuffle

    For a full step by step tutorial on how to install and use Reshuffle please visit this page

    Reshuffle Core Features

    • Simple Express-style event handling model
    • Separation of configuration and execution
    • Connectors to many SaaS services
    • Highly extensible
    • Focus on high performance

    Basic concepts

    Event Based System

    At its core Reshuffle is an event-based engine, very similar to programming with a web server. You only need to define a function that will be called when an event is triggered.

    Events can be anything from a file change, S3 bucket update, a cron job timer, your own custom event, or even an HTTP call.

    Here is an example of listening to an HTTP GET event on /test, using the HTTP connector:

    const { Reshuffle, HttpConnector } = require('reshuffle')
    const app = new Reshuffle()
    const httpConnector = new HttpConnector(app)
    httpConnector.on({ method: 'GET', path: '/test' }, (event, app) => {
      event.res.end('Hello World!')

    Connectors act like node eventEmitter, so when the event is emitted the function is called. We will discuss Connectors in the next section.

    More examples are found here

    Reshuffle Connectors

    A critical aspect of building integrations is configuring how to connect to different services we need to integrate with. With Reshuffle, you can configure Connector objects and inject them into your code.

    Let's expand the example above and send a message to a Slack ‘reports’ channel every time someone triggers the 'HTTP/GET/test' event:

    const { Reshuffle, HttpConnector, SlackConnector } = require('reshuffle')
    const app = new Reshuffle()
    // the httpConnector does not require any config
    const httpConnector = new HttpConnector(app)
    // Slack connection configuration
    const slackConnectionOptions = {
      APIToken: process.env.SLACK_AUTH_KEY,
      team: 'ourTeam',
    // the 3rd parameter is used to identify the connector later on
    new SlackConnector(app, slackConnectionOptions, 'connectors/Slack')
    httpConnector.on({ method: 'GET', path: '/test' }, (event, app) => {
      app.getConnector('connectors/Slack').send('Somebody triggered this event!', '#reports')

    Connector objects expose the API and Events that the external connector (connecting to anything from a DB to an ERP) provides. You can specify a connector id by providing an identifier in the connector constructor, and then access that connector using the app.getConnector(connectorId) method.

    You noticed in the code sample above important information on how to connect to the 3rd party system (Slack in this case). Connectors are a way to separate the connection configuration from your code, configure a connection to a connector once and use it anywhere.

    You can use the Connector object to take action on a remote service (such as adding a row to a CRM) and configure events that trigger when something happens in that system. We will show you how to do that in the next section.

    You can read more about the connector class here

    A full list of Connectors, and how to create your own Connector can be found here


    As we saw, connectors are basically adapters that connect external systems, such as Slack, Database, CRM, or any other system. Connectors can be configured to emit a Reshuffle event, when a preconfigured thing happens in these systems. To configure an event, use the on(eventOptions, handler) method of the relevant connector.

    Here is how you would configure a SlackConnector to listen to a message from Slack:

    const { Reshuffle, SlackConnector } = require('reshuffle')
    const app = new Reshuffle()
    const connectionOptions = {
      APIToken: process.env.SLACK_AUTH_KEY,
      team: 'ourTeam',
    const slackConnector = new SlackConnector(app, connectionOptions, 'connectors/Slack')
    const eventOptions = {
      event_type: 'new_message',
      channel: 'C6646754636',
      type: 'new_message',
    slackConnector.on(eventOptions, (event, app) => {
      app.getConnector('connectors/Slack').reply('Thank you for your message!')

    It is the responsibility of the SlackConnector to listen to the messages in Slack and emit corresponding events in Reshuffle. Your code can listen to these events and run business logic.

    As you can see, both the event creation and the business logic, use the same Connector configuration. This makes configuration easier to manage.

    You can read more about the Event class here

    Custom Events

    Sometimes you just want to emit an event in your script without any relation to an external system, for this purpose you can use the Custom Event Connector. You can read more about the Custom Event Connector here

    Health check

    Reshuffle can expose a health check path. This can be used to let automated tools check the availability of the system. To make use of this functionality, set the RESHUFFLE_HEALTH_PATH environment variable with your desired health check path (e.g. /reshuffle-healthcheck). Note that there is not default path for this capability, and therefore no automatic health check will be provisioned if the environment variable isn't configured.

    The health check call returns a 200 Response with:

      ok: boolean
      uptime: Number //sec


    Examples can be found in the /examples folder

    Connectors in this npm package

    Tip: Click on a version number to view a previous version's package page

    Current Tags

    • Version
      Downloads (Last 7 Days)
      • Tag
    • 1.0.9
      • latest

    Version History


    npm i reshuffle

    DownloadsWeekly Downloads






    Unpacked Size

    399 kB

    Total Files


    Last publish


    • spacebug
    • duckranger
    • ashevat
    • lagache