Configuration Guide
Overview
NitroStack provides a type-safe, centralized configuration module (ConfigModule) and service (ConfigService) for managing environment variables, API secrets, and server parameters.
Using ConfigModule eliminates raw process.env calls scattered across your code, enables fail-fast validation on startup, and supports environment-specific .env overrides.
Setting Up ConfigModule
Import ConfigModule.forRoot() into your root AppModule:
// src/app.module.ts
import { McpApp, Module, ConfigModule } from '@nitrostack/core';
import { LibraryModule } from './modules/library/library.module.js';
@McpApp({ module: AppModule })
@Module({
imports: [
ConfigModule.forRoot({
envFilePath: process.env.NODE_ENV === 'production' ? '.env.production' : '.env',
ignoreEnvFile: false, // Set true in container environments like Docker/Cloud Run
defaults: {
LOG_LEVEL: 'info',
PORT: '3000',
LIBRARY_NAME: 'Community Library',
},
validate: (config) => {
// Fail-fast assertion during bootstrap
if (!config.DATABASE_URL && process.env.NODE_ENV === 'production') {
throw new Error('Missing mandatory environment variable: DATABASE_URL');
}
return true;
},
}),
LibraryModule,
],
})
export class AppModule {}
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
envFilePath | string | '.env' | Path to the local environment file. |
ignoreEnvFile | boolean | false | When true, relies solely on OS/container environment variables. |
defaults | Record<string, string> | {} | Fallback key-value string pairs used if not present in environment. |
validate | (config: Record<string, any>) => boolean | undefined | Startup callback to validate configuration before server launches. |
Injecting and Using ConfigService
ConfigService is automatically made available to the dependency injection container:
// src/modules/library/library.service.ts
import { Injectable, ConfigService } from '@nitrostack/core';
@Injectable({ deps: [ConfigService] })
export class LibraryService {
private readonly libraryName: string;
private readonly apiKey: string;
constructor(private configService: ConfigService) {
// 1. get with fallback
this.libraryName = this.configService.get('LIBRARY_NAME', 'Default Library');
// 2. getOrThrow for critical secrets — fails fast if missing
this.apiKey = this.configService.getOrThrow<string>('LIBRARY_API_KEY');
}
getDetails() {
return {
name: this.libraryName,
hasKey: Boolean(this.apiKey),
};
}
}
ConfigService API Reference
export class ConfigService {
/**
* Retrieve an environment variable, returning undefined if not found.
*/
get<T = string>(key: string): T | undefined;
/**
* Retrieve an environment variable with a default fallback value.
*/
get<T = string>(key: string, defaultValue: T): T;
/**
* Retrieve a mandatory environment variable.
* Throws an error immediately if the variable is missing or empty.
*/
getOrThrow<T = string>(key: string): T;
/**
* Retrieve all loaded configuration as a key-value dictionary.
*/
getAll(): Record<string, string>;
}
Secrets Management & Security
-
Use
getOrThrowfor Required Secrets: Instead of checking forundefinedinside runtime handlers, callconfigService.getOrThrow('STRIPE_KEY')in service constructors. This ensures your server fails to start immediately if critical secrets are absent. -
Never Log Raw Secrets: Ensure secrets, auth tokens, and private keys are never passed into
ctx.logger.info()or serialized into tool error responses. -
Container Environment Priority: Container-injected environment variables (e.g. from Kubernetes Secrets or Google Cloud Run env vars) automatically take precedence over values declared in
.envfiles.
CLI Flags & package.json vs. In-Code ConfigModule
It is important to understand the role of CLI settings and runtime application configuration:
┌──────────────────────────────┬──────────────────────────────┐
│ CLI Flags & package.json │ In-Code ConfigModule (.env) │
├──────────────────────────────┼──────────────────────────────┤
│ Configures build tooling │ Configures application logic │
│ Transpilation targets │ Database connection strings │
│ Dev server port & reload │ Third-party API credentials │
│ Widget build paths │ Feature flags & auth tokens │
└──────────────────────────────┴──────────────────────────────┘
Related Documentation
- Server Concepts — Application bootstrapping and modules
- Dependency Injection — Service providers and injection
- Production Checklist — Environment verification for deployment