\n\n---\n\n## Table of contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [Public API](#public-api)\n- [Configuration](#configuration)\n- [Presets](#presets)\n- [Advanced guide](#advanced-guide)\n- [TypeScript support](#typescript-support)\n- [Security notes](#security-notes)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- Fast bootstrap with `NestFactory` + `FastifyAdapter`\n- Strongly typed app options (`CreateHttpAppOptions`)\n- Secure defaults with configurable presets\n- Global validation, filters, and interceptors\n- Nest native logging\n- Request ID propagation via request context\n- Optional Swagger docs and health endpoints\n- Minimal configuration, extensible architecture\n\n## Installation\n\n```bash\nnpm install @authuser/nest-fastify-kit\n```\n\nPeer dependencies expected in your app:\n\n- `@nestjs/common` `^11`\n- `@nestjs/core` `^11`\n- `@nestjs/platform-fastify` `^11`\n- `fastify` `^5`\n- `class-transformer` `^0.5`\n- `class-validator` `^0.14`\n- `reflect-metadata`\n- `rxjs`\n\nOptional peer dependencies (for optional features):\n\n- `@nestjs/config`\n- `@nestjs/swagger`\n- `@nestjs/terminus`\n\n## Quick start\n\n```ts\nimport { createHttpApp } from '@authuser/nest-fastify-kit';\nimport { AppModule } from './app.module';\n\nasync function bootstrap() {\n\tconst app = await createHttpApp({\n\t\trootModule: AppModule,\n\t\tappName: 'users-api',\n\t\tpreset: 'secure',\n\t\tapiPrefix: 'api',\n\t\tapiVersioning: true,\n\t\tdocs: process.env.NODE_ENV !== 'production',\n\t});\n\n\tawait app.listen(3000, '0.0.0.0');\n}\n\nvoid bootstrap();\n```\n\n## Public API\n\n```ts\nexport { createHttpApp } from './bootstrap/create-http-app';\nexport { Public } from './security/auth/decorators/public.decorator';\nexport { Roles } from './security/auth/decorators/roles.decorator';\nexport * from './types/create-http-app-options';\n```\n\n### `createHttpApp(options)`\n\nCreates and configures a `NestFastifyApplication` with common production defaults.\n\n```ts\ncreateHttpApp(options: CreateHttpAppOptions): Promise\n```\n\n## Configuration\n\n```ts\ninterface CreateHttpAppOptions {\n\trootModule: unknown;\n\tappName: string;\n\n\tpreset?: 'minimal' | 'secure' | 'full';\n\n\tapiPrefix?: string;\n\tapiVersioning?: boolean;\n\n\tdocs?: boolean;\n\n\tconfig?: {\n\t\tenabled?: boolean;\n\t\tisGlobal?: boolean;\n\t\tignoreEnvFile?: boolean;\n\t\tenvFilePath?: string | string[];\n\t\tvalidate?: (config: Record) => Record;\n\t};\n\n\tcors?: {\n\t\torigin: string[] | boolean;\n\t\tcredentials?: boolean;\n\t};\n\n\tsecurity?: {\n\t\thelmet?: boolean;\n\t\tcsp?: boolean;\n\t\thidePoweredBy?: boolean;\n\t\trateLimit?: {\n\t\t\tmax: number;\n\t\t\ttimeWindow: string;\n\t\t\texcludePaths?: string[];\n\t\t};\n\t};\n\n\tnetwork?: {\n\t\ttrustProxy?: boolean | string | number;\n\t};\n\n\tauth?: {\n\t\tenabled?: boolean;\n\t\tuserProperty?: string;\n\t};\n\n\tlifecycle?: {\n\t\tshutdownHooks?: boolean;\n\t};\n\n\tobservability?: {\n\t\tlogger?: {\n\t\t\tlevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';\n\t\t};\n\t\trequestLogging?: boolean;\n\t\tstartupLog?: boolean;\n\t\tmetrics?: boolean;\n\t\ttracing?: boolean;\n\t};\n}\n```\n\nFull options reference and defaults are documented in:\n\n- [`docs/advanced.md`](docs/advanced.md)\n\n## Presets\n\n### `minimal`\n\n- Fastify adapter\n- Global validation\n- Logging setup\n\n### `secure` (default)\n\n- Everything in `minimal`\n- Helmet\n- Rate limiting\n- Built-in rate-limit exclusions for `/health` and `/docs`\n- Strict CORS default (`origin: false`) if `cors` is not provided\n- `x-powered-by` header removal\n\n### `full`\n\n- Everything in `secure`\n- Swagger enabled by default (`docs: true`)\n- Health module enabled by default\n- Metrics flag enabled by default (`observability.metrics: true`)\n\n## Advanced guide\n\nDetailed runtime behavior and advanced recipes are available in:\n\n- [`docs/advanced.md`](docs/advanced.md)\n\n## TypeScript support\n\nThis package is built with strict TypeScript settings and publishes declaration files (`dist/*.d.ts`).\n\n## Security notes\n\n- Security defaults are opinionated but not universal.\n- Helmet Content Security Policy is enabled by default (`security.csp: true`).\n- Set `security.csp: false` only when a specific integration requires a temporary relaxation.\n- Always validate CORS origins for your environment.\n- Tune rate limiting based on traffic profile and endpoint sensitivity.\n- Keep dependencies updated in consuming services.\n\n## FAQ\n\n### Does this replace NestJS app architecture?\n\nNo. It standardizes HTTP bootstrap concerns but keeps Nest modules, providers, controllers, and DI patterns intact.\n\n### Can I disable built-in features?\n\nYes. Use `preset: 'minimal'` or override specific options (`security.helmet`, `security.rateLimit`, `docs`, etc.).\n\n### Can I still register my own Fastify/Nest plugins?\n\nYes. `createHttpApp` returns a regular `NestFastifyApplication`.\n\n### Can I customize middleware, proxy behavior, and hooks?\n\nYes.\n\n- Configure proxy trust with `network.trustProxy`.\n- Register your own Fastify plugins/hooks after `createHttpApp(...)` and before `app.listen(...)`.\n- Add regular Nest customizations (global interceptors, filters, pipes, guards) on the returned app instance.\n\n```ts\nconst app = await createHttpApp({\n\trootModule: AppModule,\n\tappName: 'users-api',\n\tnetwork: { trustProxy: true },\n});\n\nconst fastify = app.getHttpAdapter().getInstance();\nawait fastify.register(myFastifyPlugin);\nfastify.addHook('onRequest', myOnRequestHook);\n\napp.useGlobalInterceptors(new MyInterceptor());\n\nawait app.listen(3000, '0.0.0.0');\n```\n\n## Contributing\n\n```bash\nnpm install\nnpm run test\nnpm run typecheck\nnpm run build\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}