fastify-xconfig

Opinionated Fastify plugin that bootstraps a complete API server in one register call: CORS, rate limiting, multipart body parsing, back-pressure monitoring, opt-in Bugsnag error tracking and Prisma, fancy error responses, a /health endpoint with system metrics, and utility decorators under a single fastify.xConfig namespace. Register it once at app startup before route plugins.

Installation

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

Quick Start

Bare registration works — Prisma and Bugsnag are opt-in and simply stay disabled when their options are omitted:

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

const fastify = Fastify({ logger: true });

await fastify.register(xConfig, {
  environment: process.env.NODE_ENV, // the plugin never reads env itself
});

fastify.xConfig.slugify("Hello World");   // "hello-world"
fastify.xConfig.randomUUID();             // "a1b2c3d4-..."
fastify.xConfig.formatBytes(1048576);     // "1 MB"

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

A full registration with integrations and middleware tuned:

import { PrismaClient } from "@prisma/client";

await fastify.register(xConfig, {
  environment: process.env.NODE_ENV,
  prisma: { client: PrismaClient },                 // enables fastify.prisma
  bugsnag: { apiKey: process.env.BUGSNAG_API_KEY }, // enables fastify.bugsnag
  cors: { origin: ["https://app.example.com"], credentials: true },
  rateLimit: { max: 100, timeWindow: "1 minute" },
  multipart: { limits: { fileSize: 52428800 } },
  fancyErrors: true,
});

Options

All configuration is passed at registration. The plugin never reads process.env — the consumer owns env access and passes values in.

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

prisma Options

bugsnag Options

cors Options

Methods

Utility decorators live under a single fastify.xConfig namespace:

• xConfig.echo() — Returns "Hello from X Enterprises!"
• xConfig.slugify(string) — Converts a string to a URL-safe slug
• xConfig.randomUUID() — Generates a UUID v4 string; xConfig.generateUUID() is an alias
• xConfig.formatBytes(bytes, decimals?) — Formats a byte count to a human-readable string

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

Routes registered by the plugin:

• GET /health — System health check with memory, CPU, disk, and dependency metrics

fastify.prisma

When Prisma is enabled (prisma.client provided), fastify.prisma holds the connected PrismaClient instance. It is disconnected automatically via an onClose hook.

const user = await fastify.prisma.user.findUnique({ where: { id: userId } });

Error Reference

Registration fails fast. Every error is an Error whose message names the plugin, the option, and a correct usage example:

At runtime, 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.

Environment Variables

The plugin never reads process.env. The consumer sets env vars and passes the values into app.register(xConfig, { ... }) — none of these are inputs the plugin reads itself:

How It Works

xConfig is a fastify-plugin-wrapped orchestrator that registers sub-plugins in dependency order: Prisma (opt-in; decorates fastify.prisma + onClose disconnect), CORS/under-pressure/rate-limit/multipart middleware (each skippable via active: false), opt-in Bugsnag integration (decorates fastify.bugsnag), a custom errorHandler for fancy error formatting, @fastify/sensible HTTP utilities, the fastify.xConfig utility namespace (echo, slugify, generateUUID, randomUUID, formatBytes), a GET /health route with memory/CPU/disk and database health checks, and finally a lifecycle hook that logs all registered routes on startup unless professional: true. All decorators and routes are hoisted to the parent scope via fastify-plugin.

AI Context

package: "@xenterprises/fastify-xconfig"
type: fastify-plugin
use-when: Bootstrap a Fastify app with CORS, rate limiting, multipart, opt-in Prisma/Bugsnag, health check, and utility decorators in one registration
decorators: fastify.xConfig (echo, slugify, generateUUID, randomUUID, formatBytes), fastify.prisma (opt-in), fastify.bugsnag (opt-in)
routes: GET /health (memory, CPU, disk, DB metrics)
env: plugin never reads process.env — consumer passes values via options (environment, cors.origin, rateLimit.*, bugsnag.apiKey, prisma.client)
register-before: route plugins — xConfig must be registered first