Nighttime Peanut Migrations


    5.1.23 • Public • Published


    @sealsystems/consul provides service discovery based on Consul.


    npm install @sealsystems/consul

    Quick start

    First you need to add a reference to @sealsystems/consul within your application.

    const consul = require('@sealsystems/consul');

    Then call connect to register your service with Consul.

    await consul.connect({
      id: 'my-service-id',
      name: 'my-service-name',
      serviceUrl: 'http://localhost:3000', // URL of my service
      consulUrl: 'http://localhost:8500' // URL of a Consul server
    // Your service is now registered

    You may omit the hostname of your service in serviceUrl (e.g. by setting it to http://:3000). In this case, your service is assumed to run on the same host as the Consul agent.

    For the service, a new health check with a TTL of 10 seconds will be created. A heartbeat request will be sent every 5 seconds to Consul in order to prevent the TTL to expire.

    By default, the status of a service is warn. Consul also recognizes the states passand fail. Call the appropriate function, to change the state of your service. To set it to e.g. pass, use:

    await consul.pass();

    To get all nodes providing a specific service, call getNodes. It uses the same interface as node-consul's consul.catalog.service.nodes function.

    Watching a service

    Use the watch function to receive notifications when the group of nodes that provide a service has been changed:

    const watch ={
      serviceName: 'my-service-name', // Name of the service to watch
      consulUrl: 'http://localhost:8500' // URL of a Consul server
    watch.on('change', (nodes) => {
      // The 'nodes' array contains data about all nodes that provide the watched service
    watch.on('error', (err) => {
      // ...

    The change event is raised whenever a new node provides the service or a node is no longer available. Only nodes with passing health checks are regarded as available. At the start of the watch, the event is also immediately raised with an array of all currently active nodes.

    A node object contains the following properties:

    • host: The address of the node
    • node: Consul's node name
    • port: The port used by the service

    Custom Consul domain

    By default the domain consul will be used to resolve a service. E.g. the service checkout will be expanded to checkout.service.consul. If another domain is given in Consul's configuration, you must set the environment variable CONSUL_DOMAIN accordingly.

    If you configure Consul to use e.g. as the domain, you must also define this domain via the environment variable:

    This will change the expanded service name given above to:

    Using in cloud environment

    To enable cloud environment set the environment variable SERVICE_DISCOVERY to the value cloud. To disable cloud environment unset the variable or set it to the value consul. Additionally the environment variable SERVICE_DISCOVERY_PORT defines the https port all services are available. Default is 3000.

    Initializing without connecting first

    It is assumed that you call consul.connect first. This will establish the connection to the local Consul agent. The other functions (e.g. consul.getHostname) will throw an error if this connection has not been initialized.

    If you do not want to register a service check via consul.connect, just call consul.initialize instead. This will only connect to the Consul agent. Now, you can use most of the other functions.

    Please note: consul.heartbeat, consul.lookup, consul.resolveService require consul.connect to be called. They will not work properly if you only call consul.initialize.

    Running the build

    To build this module use roboter.





    npm i @sealsystems/consul

    DownloadsWeekly Downloads






    Unpacked Size

    22.2 kB

    Total Files


    Last publish


    • seal-mt
    • michaelscherer-seal
    • comgit
    • gel