xConfig

Core infrastructure plugin for Fastify. Composes CORS, rate limiting, multipart, under-pressure monitoring, Bugsnag error tracking, Prisma, a /health route, formatted error handling, and small utility decorators into a single registration.

Install

npm install @xenterprises/fastify-xconfig fastify@5
# if using Prisma:
npm install @prisma/client

Minimal example

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

const fastify = Fastify();

// Bare registration works — Prisma and Bugsnag are opt-in
await fastify.register(xConfig, {
  environment: process.env.NODE_ENV, // plugin never reads env itself
});

Options

All configuration is passed at registration. The plugin never reads process.env.

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | environment | string | no | "development" | Drives stack traces in error responses and the /health payload | | professional | boolean | no | false | Suppress the startup route listing | | fancyErrors | boolean | no | true | Enable the formatted error handler | | prisma | object | no | {} (disabled) | Omit to leave Prisma disabled; { client } enables it (class or instance); active: false also disables | | prisma.client | PrismaClient class or instance | when prisma.active: true | — | Your generated client. Pass the class and the plugin instantiates it with the remaining prisma.* options, or pass an instance you created | | bugsnag | object | no | {} (disabled) | Omit to leave Bugsnag disabled; { apiKey } enables it; active: false also disables | | bugsnag.apiKey | string | when bugsnag.active: true | — | Bugsnag API key | | cors | object | no | localhost origins | @fastify/cors options plus active: false to disable | | rateLimit | object | no | @fastify/rate-limit defaults | Same, pass max/timeWindow to configure | | multipart | object | no | @fastify/multipart defaults | Same | | underPressure | object | no | @fastify/under-pressure defaults | Same |

Every middleware option bag accepts active: false to skip that middleware entirely.

CORS defaults are localhost-only (http://localhost:3000, http://localhost:3001, credentials on). Deployed apps MUST pass cors.origin explicitly.

Decorators

Utilities live under a single fastify.xConfig namespace:

| Decorator | Description | |-----------|-------------| | fastify.xConfig.echo() | Returns "Hello from X Enterprises!" | | fastify.xConfig.slugify(string) | URL-safe slug | | fastify.xConfig.randomUUID() | Random UUID | | fastify.xConfig.generateUUID() | Random UUID (alias of randomUUID) | | fastify.xConfig.formatBytes(bytes, decimals?) | Human-readable byte sizes |

Integration decorators (only when that integration is enabled):

| Decorator | Description | |-----------|-------------| | fastify.prisma | PrismaClient (only when prisma.client is provided) | | fastify.bugsnag | Bugsnag client (only when bugsnag.apiKey is provided) |

Also registers @fastify/sensible, so its decorators (reply.notFound(), fastify.httpErrors, …) are available.

Routes

| Method | Path | Description | |--------|------|-------------| | GET | /health | Health check: status, uptime, environment, DB/Redis connectivity (when decorated), memory/CPU/disk usage. Returns 200 when healthy, 503 when degraded |

Error behavior

Registration fails fast — messages name the plugin, the option, and show a correct example:

• prisma: { active: true } without prisma.client, or prisma.client is neither a class nor an instance
• bugsnag: { active: true } without bugsnag.apiKey, or bugsnag.apiKey is not a string
• environment, professional, or fancyErrors have the wrong type

With fancyErrors enabled (default), route errors are returned as { status, message, stack? }; stack is included only when environment is not "production". With fancyErrors: false, Fastify's default error handler is used.

Requirements

• Node.js >= 20
• Fastify ^5.0.0 (peer dependency)
• When Prisma is active: your own generated @prisma/client (the plugin never imports it — you pass the client in)

License

Proprietary — All Rights Reserved X Enterprises. See LICENSE.