Environment Variables

Learning objectives#

• Read configuration from process.env
• Load .env files with node --env-file or dotenv
• Validate and type configuration at startup
• Keep secrets out of Git and logs

Explanation#

process.env holds environment variables as strings: process.env.PORT is "3000", not 3000. Convert and validate.

For local development, put values in a .env file. Node 20.6+ can load it directly: node --env-file=.env server.js. The dotenv package does the same for older setups.

Commit a .env.example with every variable name and safe sample values; add .env to .gitignore.

Centralise configuration in one config.js module that reads, validates and exports a typed object. Fail fast at startup if something required is missing — better than a crash at 3 a.m. on the first payment.

In production, set variables through the platform (Docker, Kubernetes secrets, Azure App Service settings, AWS Secrets Manager), never in files committed to Git. Never log secrets.

Syntax#

1# .env  (never committed)
2PORT=4000
3DATABASE_URL=mysql://shop:secret@localhost:3306/shop
4JWT_SECRET=change-me
5

6node --env-file=.env server.js

Code example: A validated config module#

1// In a real project, start with: node --env-file=.env server.js
2// Here we set the variables in code so the example runs anywhere.
3process.env.PORT = '4000';
4process.env.NODE_ENV = 'production';
5process.env.DATABASE_URL = 'mysql://shop:secret@db.internal:3306/shop';
6process.env.CORS_ORIGINS = 'https://shop.example.com,https://admin.example.com';
7delete process.env.JWT_SECRET;                 // pretend we forgot it
8

9function loadConfig(env = process.env) {
10  const errors = [];
11  const required = name => {
12    const value = env[name];
13    if (!value) errors.push(`${name} is required`);
14    return value;
15  };
16

17  const config = {
18    port: Number(env.PORT ?? 3000),
19    isProduction: env.NODE_ENV === 'production',
20    databaseUrl: required('DATABASE_URL'),
21    jwtSecret: required('JWT_SECRET'),
22    corsOrigins: (env.CORS_ORIGINS ?? '').split(',').filter(Boolean),
23  };
24

25  if (!Number.isInteger(config.port)) errors.push('PORT must be a number');
26  if (errors.length) throw new Error('Invalid configuration:\n- ' + errors.join('\n- '));
27  return Object.freeze(config);
28}
29

30try {
31  loadConfig();
32} catch (err) {
33  console.log(err.message);
34}
35

36process.env.JWT_SECRET = 'a-long-random-secret';
37const config = loadConfig();
38console.log('port:', config.port, typeof config.port);
39console.log('production:', config.isProduction);
40console.log('origins:', config.corsOrigins.length);
41console.log('db host:', new URL(config.databaseUrl).hostname);   // log the host, never the password

Invalid configuration:
- JWT_SECRET is required
port: 4000 number
production: true
origins: 2
db host: db.internal

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. All environment variables are strings; PORT is converted with Number.
2. required() collects missing values instead of failing on the first one.
3. The first call throws a clear message listing what is wrong.
4. After setting JWT_SECRET, the config loads and is frozen so nobody can change it at runtime.
5. Only the database host is logged — never the URL with its password.

Real-world use case#

Common mistakes#

Best practices#

• One validated config module
• .env for local, platform secrets in production
• Commit .env.example, never .env
• Fail fast on missing configuration

Remember this#

Practice exercise#

1function bool(name, defaultValue) {
2  const raw = process.env[name];
3  if (raw === undefined) return defaultValue;
4  const v = raw.toLowerCase();
5  if (v === 'true' || v === '1') return true;
6  if (v === 'false' || v === '0') return false;
7  throw new Error(`${name} must be true/false, got "${raw}"`);
8}
9

10process.env.FEATURE_NEW_CHECKOUT = 'false';
11console.log(bool('FEATURE_NEW_CHECKOUT', true));   // false
12console.log(bool('FEATURE_MISSING', true));        // true

Mini quiz#

Want more? Practise all Node.js MCQs · Node.js interview questions

Related topics#

My notes#

Saved in this browser.