Table of contents

• Features
• Installation
• Quick start
• Public API
• Configuration
• Presets
• Advanced guide
• TypeScript support
• Security notes
• FAQ
• Contributing
• License

Features

• Fast bootstrap with NestFactory + FastifyAdapter
• Strongly typed app options (CreateHttpAppOptions)
• Secure defaults with configurable presets
• Global validation, filters, and interceptors
• Nest native logging
• Request ID propagation via request context
• Optional Swagger docs and health endpoints
• Minimal configuration, extensible architecture

Installation

npm install @authuser/nest-fastify-kit

Peer dependencies expected in your app:

• @nestjs/common ^11
• @nestjs/core ^11
• @nestjs/platform-fastify ^11
• fastify ^5
• class-transformer ^0.5
• class-validator ^0.14
• reflect-metadata
• rxjs

Optional peer dependencies (for optional features):

• @nestjs/config
• @nestjs/swagger
• @nestjs/terminus

Quick start

import { createHttpApp } from '@authuser/nest-fastify-kit';
import { AppModule } from './app.module';

async function bootstrap() {
	const app = await createHttpApp({
		rootModule: AppModule,
		appName: 'users-api',
		preset: 'secure',
		apiPrefix: 'api',
		apiVersioning: true,
		docs: process.env.NODE_ENV !== 'production',
	});

	await app.listen(3000, '0.0.0.0');
}

void bootstrap();

Public API

export { createHttpApp } from './bootstrap/create-http-app';
export { Public } from './security/auth/decorators/public.decorator';
export { Roles } from './security/auth/decorators/roles.decorator';
export * from './types/create-http-app-options';

createHttpApp(options)

Creates and configures a NestFastifyApplication with common production defaults.

createHttpApp(options: CreateHttpAppOptions): Promise<NestFastifyApplication>

Configuration

interface CreateHttpAppOptions {
	rootModule: unknown;
	appName: string;

	preset?: 'minimal' | 'secure' | 'full';

	apiPrefix?: string;
	apiVersioning?: boolean;

	docs?: boolean;

	config?: {
		enabled?: boolean;
		isGlobal?: boolean;
		ignoreEnvFile?: boolean;
		envFilePath?: string | string[];
		validate?: (config: Record<string, unknown>) => Record<string, unknown>;
	};

	cors?: {
		origin: string[] | boolean;
		credentials?: boolean;
	};

	security?: {
		helmet?: boolean;
		csp?: boolean;
		hidePoweredBy?: boolean;
		rateLimit?: {
			max: number;
			timeWindow: string;
			excludePaths?: string[];
		};
	};

	network?: {
		trustProxy?: boolean | string | number;
	};

	auth?: {
		enabled?: boolean;
		userProperty?: string;
	};

	lifecycle?: {
		shutdownHooks?: boolean;
	};

	observability?: {
		logger?: {
			level?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
		};
		requestLogging?: boolean;
		startupLog?: boolean;
		metrics?: boolean;
		tracing?: boolean;
	};
}

Full options reference and defaults are documented in:

• docs/advanced.md

Presets

minimal

• Fastify adapter
• Global validation
• Logging setup

secure (default)

• Everything in minimal
• Helmet
• Rate limiting
• Built-in rate-limit exclusions for /health and /docs
• Strict CORS default (origin: false) if cors is not provided
• x-powered-by header removal

full

• Everything in secure
• Swagger enabled by default (docs: true)
• Health module enabled by default
• Metrics flag enabled by default (observability.metrics: true)

Advanced guide

Detailed runtime behavior and advanced recipes are available in:

• docs/advanced.md

TypeScript support

This package is built with strict TypeScript settings and publishes declaration files (dist/*.d.ts).

Security notes

• Security defaults are opinionated but not universal.
• Helmet Content Security Policy is enabled by default (security.csp: true).
• Set security.csp: false only when a specific integration requires a temporary relaxation.
• Always validate CORS origins for your environment.
• Tune rate limiting based on traffic profile and endpoint sensitivity.
• Keep dependencies updated in consuming services.

FAQ

Does this replace NestJS app architecture?

No. It standardizes HTTP bootstrap concerns but keeps Nest modules, providers, controllers, and DI patterns intact.

Can I disable built-in features?

Yes. Use preset: 'minimal' or override specific options (security.helmet, security.rateLimit, docs, etc.).

Can I still register my own Fastify/Nest plugins?

Yes. createHttpApp returns a regular NestFastifyApplication.

Can I customize middleware, proxy behavior, and hooks?

Yes.

• Configure proxy trust with network.trustProxy.
• Register your own Fastify plugins/hooks after createHttpApp(...) and before app.listen(...).
• Add regular Nest customizations (global interceptors, filters, pipes, guards) on the returned app instance.

const app = await createHttpApp({
	rootModule: AppModule,
	appName: 'users-api',
	network: { trustProxy: true },
});

const fastify = app.getHttpAdapter().getInstance();
await fastify.register(myFastifyPlugin);
fastify.addHook('onRequest', myOnRequestHook);

app.useGlobalInterceptors(new MyInterceptor());

await app.listen(3000, '0.0.0.0');

Contributing

npm install
npm run test
npm run typecheck
npm run build

License

MIT