\n\n# configify\n\n**configify** is a NestJS configuration module that simplifies loading, validating, and injecting configuration from environment variables, config files, and remote secret managers.\n\n## Installation\n\n```bash\nnpm install --save @itgorillaz/configify\n```\n\n---\n\n## Quick Start\n\nImport `ConfigifyModule` into your root module using `forRootAsync()`:\n\n```typescript\nimport { ConfigifyModule } from '@itgorillaz/configify';\n\n@Module({\n imports: [ConfigifyModule.forRootAsync()],\n controllers: [AppController],\n providers: [AppService],\n})\nexport class AppModule {}\n```\n\n> **TypeScript strict mode:** If you have `\"strict\": true` in your `tsconfig.json` and you are not using [constructor configuration injection](#mapping-configuration-classes-with-constructor-injection), you must also set `\"strictPropertyInitialization\": false`. This is required because configify initializes configuration properties at runtime.\n>\n> ```json\n> {\n> \"compilerOptions\": {\n> \"strict\": true,\n> \"strictPropertyInitialization\": false\n> }\n> }\n> ```\n\n---\n\n## Configuration File Discovery\n\nBy default, configify looks for the following files in the **root of your project**:\n\n```\nmy-app/\n├── .env\n├── application.yml\n└── application.json\n```\n\nAll three formats are supported and can be used together. You can also [customize the file paths](#overriding-default-options).\n\n---\n\n## Mapping Configuration Classes\n\nDecorate any class with `@Configuration()` and configify will automatically discover it, populate its properties, and make the instance available for dependency injection throughout your application.\n\n### From a `.env` file\n\n```bash\n# .env\nAPPLICATION_CLIENT_ID=ABC\nAPPLICATION_CLIENT_TOKEN=TEST\n```\n\n```typescript\nimport { Configuration, Value } from '@itgorillaz/configify';\n\n@Configuration()\nexport class ApplicationClientConfig {\n @Value('APPLICATION_CLIENT_ID')\n appClientId: string;\n\n @Value('APPLICATION_CLIENT_TOKEN')\n appClientToken: string;\n}\n```\n\n### From a `.yml` file\n\n```yaml\n# application.yml\ndatabase:\n host: localhost\n port: 3306\n username: test\n password: test\n metadata: |\n {\n \"label\": \"staging\"\n }\n```\n\n```typescript\nimport { Configuration, Value } from '@itgorillaz/configify';\n\ninterface DatabaseMetadata {\n label: string;\n}\n\n@Configuration()\nexport class DatabaseConfiguration {\n @Value('database.host')\n host: string;\n\n @Value('database.port', { parse: parseInt })\n port: number;\n\n @Value('database.metadata', { parse: JSON.parse })\n metadata: DatabaseMetadata;\n}\n```\n\n### Splitting one file into multiple configuration classes\n\nA single config file can be split across multiple configuration classes to keep concerns separated:\n\n```bash\n# .env\nDATABASE_HOST=localhost\nDATABASE_USER=test\nDATABASE_PASSWORD=test\n\nOKTA_API_TOKEN=test\nOKTA_CLIENT_ID=test\n```\n\n```typescript\n@Configuration()\nexport class DatabaseConfiguration {\n @Value('DATABASE_HOST')\n host: string;\n\n @Value('DATABASE_USER')\n user: string;\n\n @Value('DATABASE_PASSWORD')\n password: string;\n}\n\n@Configuration()\nexport class OktaConfiguration {\n @Value('OKTA_API_TOKEN')\n apiToken: string;\n\n @Value('OKTA_CLIENT_ID')\n clientId: string;\n}\n```\n\n### Mapping Configuration Classes with Constructor Injection\n\nDecorate your configuration class with `@RequiredArgsConstructor()` and configify will automatically create the instance of the configuration class passing the configuration values as an object to the constructor.\n\n```bash\n# .env\nDATABASE_HOST=localhost\nDATABASE_USER=test\nDATABASE_PASSWORD=test\n```\n\n```typescript\n@Configuration()\n@RequiredArgsConstructor()\nexport class DatabaseConfiguration {\n @Value('DATABASE_HOST')\n host: string;\n\n @Value('DATABASE_USER')\n user: string;\n\n @Value('DATABASE_PASSWORD')\n password: string;\n\n constructor(config: Required) {\n this.host = config.host;\n this.user = config.user;\n this.password = config.password;\n }\n}\n```\n\n---\n\n## Dependency Injection\n\nAll `@Configuration()` classes are registered globally. Inject them into any provider via the constructor:\n\n```typescript\nimport { Injectable, Logger } from '@nestjs/common';\nimport { DatabaseConfiguration } from './database.configuration';\n\n@Injectable()\nexport class AppService {\n private readonly logger = new Logger(AppService.name);\n\n constructor(private readonly dbConfig: DatabaseConfiguration) {\n this.logger.log(\n `Connecting to database at ${dbConfig.host}:${dbConfig.port}`,\n );\n }\n}\n```\n\n---\n\n## Default Values\n\nYou can provide fallback values in two ways:\n\n**Option 1 — Variable expansion syntax (in the config file):**\n\n```bash\n# .env\nAPP_CLIENT_ID=${NON_EXISTING_VAR:-DEFAULT_ID} # resolves to DEFAULT_ID\n```\n\n**Option 2 — `@Value()` decorator option:**\n\n```typescript\n@Configuration()\nexport class DatabaseConfiguration {\n @Value('DB_HOST', { default: 'localhost' })\n host: string;\n\n @Value('DB_PORT', { parse: parseInt, default: 3306 })\n port: number;\n}\n```\n\n---\n\n## Variable Expansion\n\nconfigify supports variable expansion in config files, including cross-variable references and default fallbacks:\n\n```bash\n# .env\nMY_SECRET=TEST\nMY_API_KEY=${MY_SECRET} # resolves to: TEST\nAPP_CLIENT_ID=${NON_EXISTING:-DEFAULT_ID} # resolves to: DEFAULT_ID\n```\n\n---\n\n## Parsing Configuration Values\n\nUse the `parse` option to transform raw string values into the types your application needs:\n\n```yaml\n# application.yml\ndb-json-config: |\n {\n \"host\": \"localhost\",\n \"user\": \"test\",\n \"password\": \"test\"\n }\n```\n\n```typescript\ninterface DbConfig {\n host: string;\n user: string;\n password: string;\n}\n\n@Configuration()\nexport class DatabaseConfiguration {\n @Value('db-json-config', { parse: JSON.parse })\n dbConfig: DbConfig;\n}\n```\n\nThe `parse` option accepts any function with the signature `(value: string) => T`, so you can use built-ins like `parseInt`, `JSON.parse`, or your own custom parser.\n\n---\n\n## Validating Configuration\n\nUse [`class-validator`](https://github.com/typestack/class-validator) decorators alongside `@Value()` to validate configuration at startup — before your application begins serving requests:\n\n```bash\nnpm install --save class-validator\n```\n\n```typescript\nimport { IsEmail, IsNotEmpty, IsUrl } from 'class-validator';\nimport { Configuration, Value } from '@itgorillaz/configify';\n\n@Configuration()\nexport class NotificationConfiguration {\n @IsEmail()\n @Value('SENDER_EMAIL')\n senderEmail: string;\n\n @IsNotEmpty()\n @Value('API_TOKEN')\n apiToken: string;\n\n @IsUrl()\n @Value('WEBHOOK_URL')\n webhookUrl: string;\n}\n```\n\nIf validation fails, the application will throw an error on startup with a clear message describing which values are missing or invalid.\n\n---\n\n## Secrets Management\n\nconfigify has built-in support for resolving secrets from external providers:\n\n| Provider | Notes |\n| --------------------------- | ------------------------------------------ |\n| AWS Secrets Manager | |\n| AWS Parameter Store | |\n| Azure Key Vault | |\n| Bitwarden Secrets Manager | |\n| Google Cloud Secret Manager | |\n| Custom resolver | Implement your own `ConfigurationResolver` |\n\nSee the [examples directory](/examples/) for provider-specific setup instructions.\n\n---\n\n## Overriding Default Options\n\nPass an options object to `forRootAsync()` to customize module behavior:\n\n```typescript\nConfigifyModule.forRootAsync({\n // Ignore all config files (.env, application.yml, application.json)\n // Default: false\n ignoreConfigFile: false,\n\n // Ignore environment variables\n // Default: false\n ignoreEnvVars: false,\n\n // Path(s) to configuration files (overrides default discovery)\n configFilePath: './config/app.yml',\n // or multiple files:\n // configFilePath: ['./config/database.yml', './config/app.env'],\n\n // Enable/disable variable expansion\n // Default: true\n expandConfig: true,\n\n // Custom secrets resolver strategies\n secretsResolverStrategies: [],\n});\n```\n\n## License\n\nThis code is licensed under the [MIT License](./LICENSE.txt).\n\nAll files located in the node_modules and external directories are externally maintained libraries used by this software which have their own licenses; we recommend you read them, as their terms may differ from the terms in the MIT License.\n","readmeFilename":"README.md"}
![\"Nest](\"https://nestjs.com/img/logo-small.svg\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/@itgorillaz/configify?logo=npm&label=npm\")
![\"npm](\"https://img.shields.io/npm/dm/@itgorillaz/configify?logo=npm&label=downloads\")
![\"License\"](\"https://img.shields.io/github/license/it-gorillaz/configify\")
![\"GitHub](\"https://img.shields.io/github/v/release/it-gorillaz/configify?sort=semver\")
![\"Open](\"https://img.shields.io/github/issues/it-gorillaz/configify\")
![\"Last](\"https://img.shields.io/github/last-commit/it-gorillaz/configify\")
![\"Buy](\"https://cdn.buymeacoffee.com/buttons/default-orange.png\")
\n