3. Core Concepts

This section explains how to organize and manage your configuration files when using NestJS Secrets. The library provides flexibility in terms of file formats, directory structures, and handling environment-specific settings.

File Formats (YAML/JSON)

NestJS Secrets supports configuration files written in both YAML** and JSON formats.

• YAML (.yaml or .yml): Often preferred for its readability and support for comments.

  # config/settings.yaml
  application:
      name: My NestJS App
      port: 3000
  database:
      host: localhost
      retries: 3

• JSON (.json): A widely used format, stricter in syntax.

  // config/settings.json
  {
      "application": {
          "name": "My NestJS App",
          "port": 3000
      },
      "database": {
          "host": "localhost",
          "retries": 3
      }
  }

The library typically infers the file type from its extension. If you need to use a non-standard extension or explicitly define the type, you can use the fileType option in SecretsModule.forRoot() (details on module options are typically found in an Advanced Configuration or API Reference section).

You can mix and match file types in the files array if needed, as long as each file is correctly formatted.

Directory Structure and File Paths

You can organize your configuration files however you see fit within your project.

• root Directory: The SecretsModule.forRoot({ root: 'path/to/config/dir', ... }) option allows you to specify a base directory from which your configuration files will be loaded. If not specified, it defaults to your project's root directory.
• files Array: The paths provided in the files: [...] array are relative to this root directory (or the project root).

Common Pattern:

A common practice is to keep all configuration files within a dedicated directory, for example, /config at the root of your project:

my-nestjs-project/
├── config/
│   ├── common.yaml
│   ├── development.yaml
│   ├── production.yaml
│   └── local.yaml  # For local overrides, often added to .gitignore
├── src/
│   └── app.module.ts
├── package.json
...

In your AppModule, you would then configure it like this:

// app.module.ts
SecretsModule.forRoot({
    root: './config', // Or simply 'config'
    files: ['common.yaml', 'development.yaml', 'local.yaml']
    // ... other options
})

Environment-Specific Configuration

NestJS Secrets makes it easy to manage configurations for different environments (e.g., development, staging, production, testing, local). The typical approach is to have:

1. A base/common configuration file with default values shared across all environments.
2. Environment-specific files that override or add to the base configuration.
3. An optional local file (often added to .gitignore) for individual developer overrides that should not be committed.

Example:

Suppose you have the following files in your config/ directory:

• common.yaml: Shared defaults.

• production.yaml: Settings specific to the production environment.

• local.yaml: Local developer overrides.

• You would define the loading order in SecretsModule like this:

// app.module.ts (for a production-like environment)
SecretsModule.forRoot({
    root: './config',
    files: [
        'common.yaml',      // Load base configuration first
        'production.yaml',  // Load production overrides next
        'local.yaml'        // Load local overrides last (if it exists)
    ],
    isGlobal: true
    // ... other options, including cloud provider client if needed
})

When the application runs, these files will be loaded and merged according to the rules described below.

Configuration Merging and Precedence

When multiple configuration files are specified in the files array, NestJS Secrets loads them in the order they appear. A deep merge strategy is applied to combine their contents:

1. Order of Precedence: Files listed later in the files array take higher precedence.
2. Value Overriding: If the same configuration key exists in multiple files, the value from the last file in the sequence (the one with the highest precedence) will be used.
3. Deep Merging for Objects: If the values for a key are objects in multiple files, these objects are deeply merged. This means properties from the higher-precedence object will overwrite properties in the lower-precedence object, and new properties will be added. For non-object values (like strings, numbers, booleans), the value from the highest-precedence file simply replaces the earlier one.
4. Adding New Keys: Keys that exist only in later files are added to the final merged configuration. This merging strategy allows for a clean and powerful way to layer configurations, defining base settings and then selectively overriding or extending them for different environments or local setups.

A Note on Native Secret Formats

Instead of using custom prefixes (like ssm:/ or gsm:/), NestJS Secrets is designed to directly recognize and process the native reference formats (such as ARNs, resource names, or URIs) of secrets as provided by the cloud services themselves.

When a string value in your configuration files matches one of these recognized native formats for a configured provider, the library will attempt to resolve it by fetching the secret from the respective cloud service using the SDK client you've provided.

Always ensure the string in your YAML/JSON configuration value is the exact, complete native identifier that your cloud provider uses for the secret you wish to retrieve. This approach allows you to use identifiers you're already familiar with from your cloud environment.