xConfig Plugin

A Fastify plugin that provides core configuration, middleware setup, and foundational services for Fastify applications.

Overview

xConfig is a lightweight configuration and middleware orchestration plugin for Fastify. It handles:

• Middleware Setup: CORS, rate limiting, multipart handling, error handling
• Health Checks: Disk space monitoring and application uptime tracking
• Error Tracking: Bugsnag integration for production error monitoring
• Prisma Integration: Database connectivity through @prisma/client
• Back Pressure Handling: Automatic shutdown management for overloaded servers

Installation

npm install @xenterprises/fastify-xconfig

Usage

Basic Configuration

import Fastify from 'fastify';
import xConfig from '@xenterprises/fastify-xconfig';

const fastify = Fastify();

await fastify.register(xConfig, {
  prisma: {},  // Prisma client configuration
  cors: {
    active: true,
    origin: ['http://localhost:3000'],
    credentials: true
  },
  rateLimit: {
    max: 100,
    timeWindow: '1 minute'
  },
  bugsnag: {
    apiKey: process.env.BUGSNAG_API_KEY  // Optional
  }
});

await fastify.listen({ port: 3000 });

Configuration Options

Core Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | prisma | Object | No | Prisma client configuration. If empty, plugin uses default connection pool. | | professional | Boolean | No | Enable professional mode features (default: false) | | fancyErrors | Boolean | No | Enable formatted error responses (default: true) |

Middleware Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | cors | Object | No | CORS configuration with active, origin, and credentials | | rateLimit | Object | No | Rate limiting with max requests and timeWindow | | multipart | Object | No | Multipart form handling configuration | | underPressure | Object | No | Back pressure monitoring configuration |

Observability Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | bugsnag | Object | No | Bugsnag error tracking with apiKey |

Available Decorators

After registration, the following are available on the fastify instance:

// Health check function
fastify.health.check()  // Returns { status, diskSpace, uptime }

// Prisma client (if configured)
fastify.prisma

Environment Variables

The plugin reads these environment variables:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname?sslmode=require

# Server
NODE_ENV=development
PORT=3002
FASTIFY_ADDRESS=0.0.0.0

# Observability
BUGSNAG_API_KEY=your-bugsnag-api-key

# CORS
CORS_ORIGIN=http://localhost:3000,https://example.com
RATE_LIMIT_MAX=100
RATE_LIMIT_TIME_WINDOW=1 minute

Service Separation

The following services have been extracted to separate, dedicated plugins:

| Service | Plugin | Package | |---------|--------|---------| | Authentication/JWKS | xAuthJWSK | @xenterprises/fastify-xauth-jwks | | Geocoding | xGeocode | @xenterprises/fastify-xgeocode | | SMS/Email | xTwilio | @xenterprises/fastify-xtwilio (separate module) | | File Storage | xStorage | @xenterprises/fastify-xstorage (separate module) | | Payment Processing | xStripe | @xenterprises/fastify-xstripe (separate module) |

Development

Running Tests

npm test

Starting Development Server

npm run dev

The development server watches for file changes and auto-restarts.

Starting Production Server

npm start

Architecture

fastify app
    ↓
    └─→ xConfig (core middleware & config)
            ├─→ @fastify/cors
            ├─→ @fastify/rate-limit
            ├─→ @fastify/multipart
            ├─→ @fastify/under-pressure
            ├─→ @fastify/sensible
            ├─→ fastify-bugsnag (optional)
            └─→ Prisma client

Dependencies

• fastify (^5.0.0) - Web framework
• @fastify/cors - CORS middleware
• @fastify/rate-limit - Rate limiting
• @fastify/multipart - Multipart form handling
• @fastify/sensible - HTTP utilities
• @fastify/under-pressure - Back pressure handling
• @prisma/client - ORM for database access
• fastify-bugsnag - Error tracking (optional)
• fastify-plugin - Plugin wrapper
• uncrypto - Crypto utilities
• check-disk-space - Disk space monitoring

License

ISC