Skip to main content

Configuration Reference

Complete configuration reference for NatsPubsub (JavaScript/TypeScript and Ruby).

Table of Contents


JavaScript/TypeScript Configuration

NatsPubsubConfig Interface

Complete configuration interface for JavaScript/TypeScript.

interface NatsPubsubConfig {
// Core Settings
natsUrls: string | string[];
env: string;
appName: string;

// Consumer Settings
concurrency?: number;
maxDeliver?: number;
ackWait?: number;
backoff?: number[];
perMessageConcurrency?: number;
subscriberTimeoutMs?: number;

// Pattern Toggles
useOutbox?: boolean;
useInbox?: boolean;
useDlq?: boolean;

// Stream Settings
streamName?: string;
dlqSubject?: string;
dlqMaxAttempts?: number;

// Monitoring
metrics?: {
recordDlqMessage(subject: string, reason: string): void;
};

// Logging
logger?: Logger;
}

Configuration Options

Core Settings

natsUrls

NATS server URL(s).

Type: string | string[] Required: Yes Default: 'nats://localhost:4222'

Examples:

// Single server
natsUrls: "nats://localhost:4222";

// Multiple servers (cluster)
natsUrls: [
"nats://nats1.example.com:4222",
"nats://nats2.example.com:4222",
"nats://nats3.example.com:4222",
];

// With authentication
natsUrls: "nats://user:password@nats.example.com:4222";

// TLS connection
natsUrls: "tls://nats.example.com:4222";
env

Environment name (used in subject naming).

Type: string Required: Yes Default: process.env.NODE_ENV || 'development'

Examples:

env: "development";
env: "staging";
env: "production";
env: "test";
appName

Application name (used in subject naming and consumer groups).

Type: string Required: Yes Default: process.env.APP_NAME || 'app'

Examples:

appName: "order-service";
appName: "notification-service";
appName: "analytics-worker";

Consumer Settings

concurrency

Number of concurrent message processors.

Type: number Required: No Default: 5 Range: 1-1000

Description: Controls how many messages can be processed concurrently. Higher values increase throughput but consume more resources.

Examples:

// Low concurrency for CPU-intensive tasks
concurrency: 2;

// Moderate concurrency (default)
concurrency: 5;

// High concurrency for I/O-bound tasks
concurrency: 50;

// Maximum concurrency
concurrency: 1000;
maxDeliver

Maximum delivery attempts before sending to DLQ.

Type: number Required: No Default: 5

Description: Number of times NATS will attempt to deliver a message before considering it failed.

Examples:

// Retry once
maxDeliver: 2;

// Default retries
maxDeliver: 5;

// Aggressive retries
maxDeliver: 10;
ackWait

Acknowledgment wait time in milliseconds.

Type: number Required: No Default: 30000 (30 seconds)

Description: How long NATS waits for an acknowledgment before redelivering the message.

Examples:

// Quick operations
ackWait: 10000; // 10 seconds

// Default
ackWait: 30000; // 30 seconds

// Long-running operations
ackWait: 300000; // 5 minutes
backoff

Exponential backoff delays in milliseconds.

Type: number[] Required: No Default: [1000, 5000, 15000, 30000, 60000]

Description: Array of delays between retry attempts. Each index represents the delay for that retry attempt.

Examples:

// Fast retries
backoff: [500, 1000, 2000, 5000];

// Default backoff
backoff: [1000, 5000, 15000, 30000, 60000];

// Aggressive backoff
backoff: [1000, 2000, 4000, 8000, 16000, 32000, 60000];

// Linear backoff
backoff: [5000, 5000, 5000, 5000, 5000];
perMessageConcurrency

Concurrency limit per message type.

Type: number Required: No Default: 5

Description: Limits concurrent processing per message type to prevent resource exhaustion.

Examples:

perMessageConcurrency: 1; // Serial processing
perMessageConcurrency: 5; // Default
perMessageConcurrency: 20; // High concurrency
subscriberTimeoutMs

Timeout for subscriber processing in milliseconds.

Type: number Required: No Default: 60000 (60 seconds)

Description: Maximum time allowed for a subscriber to process a message.

Examples:

subscriberTimeoutMs: 30000; // 30 seconds
subscriberTimeoutMs: 60000; // 1 minute (default)
subscriberTimeoutMs: 300000; // 5 minutes

Pattern Toggles

useOutbox

Enable Outbox pattern for reliable publishing.

Type: boolean Required: No Default: false

Description: Enables the Outbox pattern for guaranteed message delivery. Messages are persisted before publishing.

Examples:

useOutbox: false; // Disabled (default)
useOutbox: true; // Enabled - requires database

See Also: Inbox/Outbox Pattern Guide

useInbox

Enable Inbox pattern for idempotent processing.

Type: boolean Required: No Default: false

Description: Enables the Inbox pattern for exactly-once message processing. Prevents duplicate processing.

Examples:

useInbox: false; // Disabled (default)
useInbox: true; // Enabled - requires database

See Also: Inbox/Outbox Pattern Guide

useDlq

Enable Dead Letter Queue.

Type: boolean Required: No Default: true

Description: Sends failed messages to a DLQ for inspection and retry.

Examples:

useDlq: true; // Enabled (default)
useDlq: false; // Disabled - failed messages are dropped

See Also: DLQ Guide

Stream Settings

streamName

JetStream stream name.

Type: string Required: No Default: '{env}-events-stream'

Description: Name of the JetStream stream. Automatically includes environment.

Examples:

// Automatic naming (default)
streamName: undefined; // Results in 'production-events-stream'

// Custom stream name
streamName: "my-custom-stream";

// Environment-specific
streamName: `${env}-application-events`;
dlqSubject

Dead Letter Queue subject pattern.

Type: string Required: No Default: '{env}.{appName}.dlq'

Description: NATS subject for dead letter messages.

Examples:

// Default
dlqSubject: undefined; // Results in 'production.myapp.dlq'

// Custom DLQ subject
dlqSubject: "failures.myapp";
dlqSubject: "production.errors";
dlqMaxAttempts

Maximum DLQ processing attempts.

Type: number Required: No Default: 3

Description: How many times to attempt processing messages from the DLQ.

Examples:

dlqMaxAttempts: 1; // Process once
dlqMaxAttempts: 3; // Default
dlqMaxAttempts: 5; // Multiple retries

Monitoring

metrics

Metrics recording hook.

Type: { recordDlqMessage(subject: string, reason: string): void } Required: No Default: undefined

Description: Optional callback for recording DLQ metrics.

Examples:

// Prometheus integration
import { dlqCounter } from './metrics';

metrics: {
recordDlqMessage(subject, reason) {
dlqCounter.inc({ subject, reason });
}
}

// StatsD integration
metrics: {
recordDlqMessage(subject, reason) {
statsd.increment('nats.dlq', { subject, reason });
}
}

// Custom logging
metrics: {
recordDlqMessage(subject, reason) {
console.log(`DLQ: ${subject} - ${reason}`);
}
}

Logging

logger

Custom logger instance.

Type: Logger Required: No Default: Console logger

Interface:

interface Logger {
debug(message: string, meta?: Record<string, unknown>): void;
info(message: string, meta?: Record<string, unknown>): void;
warn(message: string, meta?: Record<string, unknown>): void;
error(message: string, meta?: Record<string, unknown>): void;
}

Examples:

// Winston logger
import winston from "winston";

const logger = winston.createLogger({
level: "info",
format: winston.format.json(),
transports: [new winston.transports.File({ filename: "nats.log" })],
});

config.configure({ logger });

// Pino logger
import pino from "pino";

const logger = pino({
level: "info",
transport: {
target: "pino-pretty",
},
});

config.configure({ logger });

// Custom logger
const logger = {
debug: (msg, meta) => console.debug(msg, meta),
info: (msg, meta) => console.log(msg, meta),
warn: (msg, meta) => console.warn(msg, meta),
error: (msg, meta) => console.error(msg, meta),
};

config.configure({ logger });

Ruby Configuration

Config Class

Complete configuration class for Ruby.

class Config
attr_accessor :nats_urls, :env, :app_name, :destination_app,
:max_deliver, :ack_wait, :backoff,
:use_outbox, :use_inbox, :inbox_model, :outbox_model,
:use_dlq, :dlq_max_attempts, :dlq_stream_suffix,
:logger, :concurrency,
:connection_pool_size, :connection_pool_timeout
end

Configuration Options

Core Settings

nats_urls

NATS server URL(s).

Type: String | Array<String> Required: Yes Default: ENV['NATS_URLS'] or ENV['NATS_URL'] or 'nats://localhost:4222'

Examples:

# Single server
config.nats_urls = 'nats://localhost:4222'

# Multiple servers (cluster)
config.nats_urls = [
'nats://nats1.example.com:4222',
'nats://nats2.example.com:4222',
'nats://nats3.example.com:4222'
]

# Environment variable
config.nats_urls = ENV['NATS_URLS']
env

Environment name.

Type: String Required: Yes Default: ENV['NATS_ENV'] or 'development'

Examples:

config.env = 'development'
config.env = 'staging'
config.env = 'production'
config.env = ENV['RAILS_ENV']
app_name

Application name.

Type: String Required: Yes Default: ENV['APP_NAME'] or 'app'

Examples:

config.app_name = 'order-service'
config.app_name = 'notification-service'
config.app_name = ENV['APP_NAME']
destination_app

Destination application name for cross-app messaging.

Type: String Required: No Default: ENV['DESTINATION_APP'] or nil

Examples:

config.destination_app = 'analytics-service'
config.destination_app = ENV['DESTINATION_APP']

Consumer Settings

concurrency

Number of concurrent workers.

Type: Integer Required: No Default: 5 Range: 1-1000

Examples:

config.concurrency = 2   # Low concurrency
config.concurrency = 5 # Default
config.concurrency = 50 # High concurrency
max_deliver

Maximum delivery attempts.

Type: Integer Required: No Default: 5

Examples:

config.max_deliver = 2   # Retry once
config.max_deliver = 5 # Default
config.max_deliver = 10 # Aggressive retries
ack_wait

Acknowledgment wait time.

Type: String Required: No Default: '30s'

Format: Duration string (e.g., '30s', '5m', '1h')

Examples:

config.ack_wait = '10s'   # 10 seconds
config.ack_wait = '30s' # 30 seconds (default)
config.ack_wait = '5m' # 5 minutes
config.ack_wait = '1h' # 1 hour
backoff

Exponential backoff delays.

Type: Array<String> Required: No Default: ['1000ms', '5000ms', '15000ms', '30000ms', '60000ms']

Examples:

# Fast retries
config.backoff = ['500ms', '1s', '2s', '5s']

# Default backoff
config.backoff = ['1s', '5s', '15s', '30s', '60s']

# Aggressive backoff
config.backoff = ['1s', '2s', '4s', '8s', '16s', '32s', '60s']

Pattern Toggles

use_outbox

Enable Outbox pattern.

Type: Boolean Required: No Default: false

Examples:

config.use_outbox = false  # Disabled (default)
config.use_outbox = true # Enabled
outbox_model

Outbox model class name.

Type: String Required: No Default: 'NatsPubsub::OutboxEvent'

Examples:

config.outbox_model = 'NatsPubsub::OutboxEvent'  # Default
config.outbox_model = 'MyApp::CustomOutboxEvent' # Custom
use_inbox

Enable Inbox pattern.

Type: Boolean Required: No Default: false

Examples:

config.use_inbox = false  # Disabled (default)
config.use_inbox = true # Enabled
inbox_model

Inbox model class name.

Type: String Required: No Default: 'NatsPubsub::InboxEvent'

Examples:

config.inbox_model = 'NatsPubsub::InboxEvent'  # Default
config.inbox_model = 'MyApp::CustomInboxEvent' # Custom
use_dlq

Enable Dead Letter Queue.

Type: Boolean Required: No Default: true

Examples:

config.use_dlq = true   # Enabled (default)
config.use_dlq = false # Disabled
dlq_max_attempts

Maximum DLQ processing attempts.

Type: Integer Required: No Default: 3

Examples:

config.dlq_max_attempts = 1  # Process once
config.dlq_max_attempts = 3 # Default
config.dlq_max_attempts = 5 # Multiple retries
dlq_stream_suffix

DLQ stream name suffix.

Type: String Required: No Default: '-dlq'

Examples:

config.dlq_stream_suffix = '-dlq'      # Default
config.dlq_stream_suffix = '-failed' # Custom

Connection Pool Settings

connection_pool_size

NATS connection pool size.

Type: Integer Required: No Default: ENV['NATS_POOL_SIZE'] or 5

Examples:

config.connection_pool_size = 5   # Default
config.connection_pool_size = 10 # Larger pool
config.connection_pool_size = 20 # High concurrency
connection_pool_timeout

Connection pool timeout in seconds.

Type: Integer Required: No Default: ENV['NATS_POOL_TIMEOUT'] or 5

Examples:

config.connection_pool_timeout = 5   # Default (5 seconds)
config.connection_pool_timeout = 10 # 10 seconds
config.connection_pool_timeout = 30 # 30 seconds

Logging

logger

Custom logger instance.

Type: Logger Required: No Default: nil (uses Rails.logger if available)

Examples:

# Rails logger
config.logger = Rails.logger

# Custom logger
require 'logger'
config.logger = Logger.new(STDOUT)

# File logger
config.logger = Logger.new('log/nats_pubsub.log')

# Structured logger
require 'semantic_logger'
config.logger = SemanticLogger[NatsPubsub]

Connection Settings

JavaScript/TypeScript

import { NatsPubsub } from "nats-pubsub";

NatsPubsub.configure({
// Single server
natsUrls: "nats://localhost:4222",

// Cluster with failover
natsUrls: [
"nats://nats1.example.com:4222",
"nats://nats2.example.com:4222",
"nats://nats3.example.com:4222",
],

// With authentication
natsUrls: "nats://user:password@nats.example.com:4222",

// TLS connection
natsUrls: "tls://nats.example.com:4222",
});

Ruby

NatsPubsub.configure do |config|
# Single server
config.nats_urls = 'nats://localhost:4222'

# Cluster with failover
config.nats_urls = [
'nats://nats1.example.com:4222',
'nats://nats2.example.com:4222',
'nats://nats3.example.com:4222'
]

# Connection pool
config.connection_pool_size = 10
config.connection_pool_timeout = 5
end

Stream Settings

JavaScript/TypeScript

NatsPubsub.configure({
// Stream naming
streamName: "production-events-stream",

// DLQ configuration
useDlq: true,
dlqSubject: "production.myapp.dlq",
dlqMaxAttempts: 3,
});

Ruby

NatsPubsub.configure do |config|
# DLQ configuration
config.use_dlq = true
config.dlq_max_attempts = 3
config.dlq_stream_suffix = '-dlq'
end

Consumer Settings

JavaScript/TypeScript

NatsPubsub.configure({
// Concurrency
concurrency: 10,
perMessageConcurrency: 5,

// Retry configuration
maxDeliver: 5,
ackWait: 30000,
backoff: [1000, 5000, 15000, 30000, 60000],

// Timeouts
subscriberTimeoutMs: 60000,
});

Ruby

NatsPubsub.configure do |config|
# Concurrency
config.concurrency = 10

# Retry configuration
config.max_deliver = 5
config.ack_wait = '30s'
config.backoff = ['1s', '5s', '15s', '30s', '60s']
end

Inbox/Outbox Settings

JavaScript/TypeScript

NatsPubsub.configure({
// Enable patterns
useOutbox: true,
useInbox: true,

// Database required for these features
// See Outbox/Inbox pattern guides for setup
});

Ruby

NatsPubsub.configure do |config|
# Enable patterns
config.use_outbox = true
config.use_inbox = true

# Custom models (optional)
config.outbox_model = 'MyApp::OutboxEvent'
config.inbox_model = 'MyApp::InboxEvent'
end

Logging Configuration

JavaScript/TypeScript

Winston Logger

import winston from "winston";
import { NatsPubsub } from "nats-pubsub";

const logger = winston.createLogger({
level: "info",
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json(),
),
transports: [
new winston.transports.Console(),
new winston.transports.File({ filename: "nats-pubsub.log" }),
],
});

NatsPubsub.configure({ logger });

Pino Logger

import pino from "pino";
import { NatsPubsub } from "nats-pubsub";

const logger = pino({
level: "info",
transport: {
target: "pino-pretty",
options: {
colorize: true,
},
},
});

NatsPubsub.configure({ logger });

Ruby

Rails Logger

# config/initializers/nats_pubsub.rb
NatsPubsub.configure do |config|
config.logger = Rails.logger
end

Custom Logger

require 'logger'

NatsPubsub.configure do |config|
config.logger = Logger.new(STDOUT)
config.logger.level = Logger::INFO
end

Semantic Logger

require 'semantic_logger'

NatsPubsub.configure do |config|
config.logger = SemanticLogger[NatsPubsub]
end

Security Settings

TLS Configuration

JavaScript/TypeScript

import { connect } from "nats";

// Configure NATS with TLS
const nc = await connect({
servers: "tls://nats.example.com:4222",
tls: {
caFile: "./ca.pem",
certFile: "./cert.pem",
keyFile: "./key.pem",
},
});

Ruby

# Configure NATS with TLS
NatsPubsub.configure do |config|
config.nats_urls = 'tls://nats.example.com:4222'
# TLS configuration handled by NATS client
end

Authentication

Token Authentication

// JavaScript/TypeScript
natsUrls: "nats://token@nats.example.com:4222";
# Ruby
config.nats_urls = 'nats://token@nats.example.com:4222'

Username/Password

// JavaScript/TypeScript
natsUrls: "nats://user:password@nats.example.com:4222";
# Ruby
config.nats_urls = 'nats://user:password@nats.example.com:4222'

Environment Variables

Supported Environment Variables

VariableDescriptionDefault
NATS_URL / NATS_URLSNATS server URL(s)nats://localhost:4222
NATS_ENVEnvironment namedevelopment
APP_NAMEApplication nameapp
DESTINATION_APPDestination app (Ruby only)-
NODE_ENVNode environment (JS only)development
RAILS_ENVRails environment (Ruby only)development
NATS_POOL_SIZEConnection pool size (Ruby)5
NATS_POOL_TIMEOUTPool timeout in seconds (Ruby)5

Example .env File

# NATS Connection
NATS_URL=nats://nats.example.com:4222
NATS_ENV=production
APP_NAME=my-service

# Ruby-specific
NATS_POOL_SIZE=10
NATS_POOL_TIMEOUT=5

# Optional
DESTINATION_APP=analytics-service

Configuration Presets

JavaScript/TypeScript Presets

Development Preset

import { config } from "nats-pubsub";

config.configureWithPreset("development", {
natsUrls: "nats://localhost:4222",
appName: "my-app",
});

// Preset includes:
// - concurrency: 2
// - maxDeliver: 3
// - useDlq: true
// - Debug logging enabled

Production Preset

config.configureWithPreset("production", {
natsUrls: "nats://nats.example.com:4222",
appName: "my-app",
});

// Preset includes:
// - concurrency: 10
// - maxDeliver: 5
// - useDlq: true
// - useOutbox: true (recommended)
// - Optimized for reliability

Testing Preset

config.configureWithPreset("testing", {
natsUrls: "nats://localhost:4222",
appName: "test-app",
});

// Preset includes:
// - concurrency: 1
// - maxDeliver: 1
// - useDlq: false
// - Fast timeouts

Ruby Presets

Development Preset

NatsPubsub::Config.new(preset: :development)

# Preset includes:
# - concurrency: 2
# - max_deliver: 3
# - use_dlq: true
# - ack_wait: '30s'

Production Preset

NatsPubsub::Config.new(preset: :production)

# Preset includes:
# - concurrency: 10
# - max_deliver: 5
# - use_dlq: true
# - ack_wait: '60s'
# - connection_pool_size: 10

Testing Preset

NatsPubsub::Config.new(preset: :testing)

# Preset includes:
# - concurrency: 1
# - max_deliver: 1
# - use_dlq: false
# - ack_wait: '5s'

Configuration Examples

Development Configuration

JavaScript/TypeScript

import { NatsPubsub } from "nats-pubsub";

NatsPubsub.configure({
env: "development",
appName: "my-service",
natsUrls: "nats://localhost:4222",
concurrency: 2,
maxDeliver: 3,
ackWait: 30000,
useDlq: true,
useOutbox: false,
useInbox: false,
logger: console,
});

Ruby

# config/initializers/nats_pubsub.rb
NatsPubsub.configure do |config|
config.env = 'development'
config.app_name = 'my-service'
config.nats_urls = 'nats://localhost:4222'
config.concurrency = 2
config.max_deliver = 3
config.ack_wait = '30s'
config.use_dlq = true
config.use_outbox = false
config.use_inbox = false
config.logger = Rails.logger
end

Production Configuration

JavaScript/TypeScript

import { NatsPubsub } from "nats-pubsub";
import winston from "winston";

const logger = winston.createLogger({
level: "info",
format: winston.format.json(),
transports: [
new winston.transports.File({ filename: "nats-error.log", level: "error" }),
new winston.transports.File({ filename: "nats-combined.log" }),
],
});

NatsPubsub.configure({
env: "production",
appName: "order-service",
natsUrls: [
"nats://nats1.prod.example.com:4222",
"nats://nats2.prod.example.com:4222",
"nats://nats3.prod.example.com:4222",
],
concurrency: 20,
maxDeliver: 5,
ackWait: 60000,
backoff: [1000, 5000, 15000, 30000, 60000],
useDlq: true,
useOutbox: true,
useInbox: true,
subscriberTimeoutMs: 300000,
logger,
metrics: {
recordDlqMessage(subject, reason) {
// Prometheus metrics
dlqCounter.inc({ subject, reason });
},
},
});

await NatsPubsub.setup();

Ruby

# config/initializers/nats_pubsub.rb
NatsPubsub.configure do |config|
config.env = 'production'
config.app_name = 'order-service'
config.nats_urls = [
'nats://nats1.prod.example.com:4222',
'nats://nats2.prod.example.com:4222',
'nats://nats3.prod.example.com:4222'
]
config.concurrency = 20
config.max_deliver = 5
config.ack_wait = '60s'
config.backoff = ['1s', '5s', '15s', '30s', '60s']
config.use_dlq = true
config.use_outbox = true
config.use_inbox = true
config.connection_pool_size = 20
config.connection_pool_timeout = 10
config.logger = Rails.logger

# Middleware configuration
config.server_middleware do |chain|
chain.add Middleware::StructuredLogging.new
chain.add Middleware::ActiveRecord.new
end
end

NatsPubsub.ensure_topology!

Testing Configuration

JavaScript/TypeScript

import { NatsPubsub, config } from "nats-pubsub";

// In test setup
beforeAll(async () => {
config.configureWithPreset("testing", {
appName: "test-app",
});

await NatsPubsub.setup();
});

// In test teardown
afterAll(async () => {
await NatsPubsub.disconnect();
});

Ruby

# spec/spec_helper.rb or test/test_helper.rb
require 'nats_pubsub/testing'

RSpec.configure do |config|
config.before(:suite) do
NatsPubsub.setup_with_preset!(:testing) do |cfg|
cfg.app_name = 'test-app'
end
end

config.before(:each) do
NatsPubsub::Testing.enable_test_mode!
end

config.after(:each) do
NatsPubsub::Testing.reset!
end
end

Kubernetes Configuration

JavaScript/TypeScript

// In Kubernetes, use environment variables
import { NatsPubsub } from "nats-pubsub";

NatsPubsub.configure({
env: process.env.NODE_ENV || "production",
appName: process.env.APP_NAME || "my-service",
natsUrls: process.env.NATS_URLS?.split(",") || ["nats://nats:4222"],
concurrency: parseInt(process.env.CONCURRENCY || "10"),
maxDeliver: parseInt(process.env.MAX_DELIVER || "5"),
useDlq: process.env.USE_DLQ === "true",
useOutbox: process.env.USE_OUTBOX === "true",
useInbox: process.env.USE_INBOX === "true",
});

await NatsPubsub.setup();

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
name: nats-pubsub-config
data:
NATS_URLS: "nats://nats-1:4222,nats://nats-2:4222,nats://nats-3:4222"
NODE_ENV: "production"
APP_NAME: "order-service"
CONCURRENCY: "20"
MAX_DELIVER: "5"
USE_DLQ: "true"
USE_OUTBOX: "true"
USE_INBOX: "true"

See Also