@simpleworkjs/conf

Features

Installation

npm install --save @simpleworkjs/conf

Quick Start

Create a conf directory in your project root:

your-project/
├── node_modules/
├── conf/
│   ├── base.js           # Required - base configuration
│   ├── development.js    # Optional - development environment config
│   ├── production.js     # Optional - production environment config
│   └── secrets.js        # Optional - sensitive data (add to .gitignore!)
└── package.json

Example: conf/base.js

module.exports = {
  app: {
    name: 'My Application',
    port: 3000
  },
  database: {
    host: 'localhost',
    name: 'myapp'
  }
};

Example: conf/production.js

module.exports = {
  app: {
    port: 8080
  },
  database: {
    host: 'prod-db.example.com'
  }
};

Example: conf/secrets.js

module.exports = {
  database: {
    password: 'super-secret-password',
    username: 'dbuser'
  },
  apiKeys: {
    stripe: 'sk_live_...'
  }
};

Custom Secrets File

Point to a secrets file outside the default conf/ directory with CONF_SECRETS, for example when secrets are stored in /etc/:

CONF_SECRETS=/etc/appName.js node app.js

Relative paths are resolved from process.cwd().

Usage in your application:

const conf = require('@simpleworkjs/conf');

console.log(conf.app.name);        // 'My Application'
console.log(conf.database.host);   // 'localhost' in dev, 'prod-db.example.com' in prod
console.log(conf.database.password); // 'super-secret-password' (from secrets.js)
console.log(conf.environment);     // 'development' or 'production'

Configuration Structure

Load Order

Configuration files are loaded and merged in the following order:

1. base.js - Loaded first (required)
2. <environment>.js - Loaded second, overrides base settings
3. secrets.js (or the file pointed to by CONF_SECRETS) - Loaded last, overrides all previous settings

Each subsequent file deeply merges with the previous configuration.

Environment Variables

API Reference

The package exports a single configuration object that includes all merged settings plus:

• environment - The current environment name (from NODE_ENV)

TypeScript

Extend the Config interface for typed access:

declare module '@simpleworkjs/conf' {
  interface Config {
    app: {
      name: string;
      port: number;
    };
    database: {
      host: string;
      name: string;
      password?: string;
    };
  }
}

import conf = require('@simpleworkjs/conf');
const port: number = conf.app.port;

Examples

Using with Express

const conf = require('@simpleworkjs/conf');
const express = require('express');

const app = express();

app.listen(conf.app.port, () => {
  console.log(`Server running on port ${conf.app.port}`);
});

Different Environments

# Development (default)
npm start

# Production
NODE_ENV=production npm start

# Custom environment
NODE_ENV=staging npm start  # Loads conf/staging.js

Custom Config Directory

CONF_DIR=/path/to/config node app.js

Best Practices

• Always commit base.js and environment-specific files to version control
• Never commit secrets.js - add it to .gitignore, and never commit files referenced by CONF_SECRETS that contain real values
• Use environment files for environment-specific URLs, ports, and settings
• Use secrets.js or CONF_SECRETS for API keys, passwords, tokens, and other sensitive data
• Keep base.js minimal - only include shared configuration
• Document your config - add comments explaining what each setting does

Contributing

Contributions are welcome! Please see our GitHub repository for guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run tests: npm test
5. Commit your changes
6. Push to the branch
7. Submit a pull request