Installation

Install and configure the Redis adapter for Store. Set up Redis connection, create the adapter instance, and register it with Igniter.js.

Prerequisites

Before installing the Store adapter, ensure you have:

  • Node.js 22+ or Bun runtime
  • Redis server running (local or remote)
  • An Igniter.js project initialized

Installation

Install the Redis adapter and its peer dependency:

npm install @igniter-js/adapter-redis ioredis
pnpm add @igniter-js/adapter-redis ioredis
yarn add @igniter-js/adapter-redis ioredis
bun add @igniter-js/adapter-redis ioredis

The ioredis package is a peer dependency. It provides the Redis client that the adapter uses internally.

Redis Setup

Setting up Redis is the first step in using the Store adapter. Redis can run locally for development or use a managed service for production. Understanding your setup options helps you choose the right approach for your environment and ensures your Redis connection is configured correctly.

The Redis setup process varies depending on your development environment and production requirements. For local development, running Redis in Docker is often the fastest way to get started, while production environments benefit from managed services that handle scaling, backups, and high availability.

Configuration

Configuring the Store adapter involves creating a Redis client, setting up environment variables, and registering the adapter with Igniter. This process ensures your application can connect to Redis and use the Store adapter's features. Proper configuration is essential for both development and production environments.

Understanding configuration options helps you optimize your Redis connection for your specific use case, whether you need connection pooling, retry strategies, or TLS encryption for production deployments.

1. Create the Redis Client

Create a dedicated service file for your Redis connection:

// src/services/store.ts
import { createRedisStoreAdapter } from '@igniter-js/adapter-redis';
import { Redis } from 'ioredis';

// Create Redis client
const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD,
  db: parseInt(process.env.REDIS_DB || '0'),
  
  // Connection options
  retryStrategy: (times) => {
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  
  maxRetriesPerRequest: 3,
  
  // Enable offline queue for better resilience
  enableOfflineQueue: true,
});

// Handle connection events
redis.on('connect', () => {
  console.log('✅ Redis connected');
});

redis.on('error', (err) => {
  console.error('❌ Redis connection error:', err);
});

redis.on('close', () => {
  console.log('⚠️ Redis connection closed');
});

// Create the adapter
export const store = createRedisStoreAdapter(redis);

2. Environment Variables

Create a .env file with your Redis configuration:

# .env
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password-here
REDIS_DB=0

# Or use a Redis URL
REDIS_URL=redis://localhost:6379

Using Redis URL:

// src/services/store.ts
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);
export const store = createRedisStoreAdapter(redis);

3. Register with Igniter

Register the store adapter in your main Igniter configuration:

// src/igniter.ts
import { Igniter } from '@igniter-js/core';
import { createIgniterAppContext } from '@/igniter.context';
import { store } from './services/store';

export const igniter = Igniter
  .context(createIgniterAppContext())
  .store(store)
  .create();

Configuration Options

The ioredis client supports extensive configuration options that allow you to customize connection behavior, retry strategies, and connection pooling. Understanding these options helps you optimize your Redis connection for production environments where reliability and performance are critical.

Proper configuration ensures your Redis connection is resilient, performs well under load, and handles network issues gracefully. Each option serves a specific purpose in building a production-ready Redis setup.

Sharing Redis Connection

You can share the same Redis client between the Store adapter and other adapters (like BullMQ for jobs):

// src/services/store.ts
import { createRedisStoreAdapter } from '@igniter-js/adapter-redis';
import { Redis } from 'ioredis';

// Create a single Redis client
export const redis = new Redis(process.env.REDIS_URL);

// Create store adapter
export const store = createRedisStoreAdapter(redis);
// src/services/jobs.ts
import { createBullMQAdapter } from '@igniter-js/adapter-bullmq';
import { store, redis } from './store';

// Share the Redis connection
export const jobs = createBullMQAdapter({
  store, // Uses the same Redis connection
});

Best Practice

Sharing a single Redis client between adapters is more efficient than creating multiple connections. The adapter handles separate clients internally for Pub/Sub operations.

Health Checks

Add health check endpoints to monitor Redis connectivity:

export const healthController = igniter.controller({
  name: 'Health',
  description: 'Monitor application health and service connectivity',
  path: '/health',
  actions: {
    check: igniter.query({
      name: 'Health Check',
      description: 'Check the health status of all services including Redis',
      path: '/',
      handler: async ({ context, response }) => {
        try {
          // Test Redis connection
          await igniter.store.has('health:check');
          
          return response.success({
            status: 'healthy',
            store: 'connected',
          });
        } catch (error) {
          return response.error({
            status: 'unhealthy',
            store: 'disconnected',
            error: error.message,
          });
        }
      },
    }),
  },
});

Troubleshooting

When setting up Redis, you may encounter connection issues, authentication problems, or memory constraints. Understanding common issues and their solutions helps you troubleshoot problems quickly and get your Redis connection working correctly.

These troubleshooting tips cover the most common issues developers face when setting up Redis for the first time or when deploying to production.

Introduction

High-performance caching and Pub/Sub messaging with Redis. Store provides a unified interface for key-value caching, atomic operations, and event-driven communication.

Caching

Learn how to use the Store for high-performance caching. Store and retrieve data, manage TTL, check key existence, and implement cache patterns.

On this page

PrerequisitesInstallationRedis SetupConfiguration1. Create the Redis Client2. Environment Variables3. Register with IgniterConfiguration OptionsSharing Redis ConnectionHealth ChecksTroubleshooting