An intuitive, strongly typed, and scalable way to retrieve environment variables.
# Via npm
npm install @americanairlines/simple-env
# Via Yarn
yarn add @americanairlines/simple-envCreate a file to manage your environment variables (either added via arguments or a .env file loaded with dotenv):
// src/env.ts
import setEnv from '@americanairlines/simple-env';
export const env = setEnv({
required: {
nodeEnv: 'NODE_ENV',
someRequiredSecret: 'SOME_REQUIRED_SECRET',
},
optional: {
anOptionalSecret: 'AN_OPTIONAL_SECRET',
},
});Import env (or whatever you named your export) from your configuration file:
// src/index.ts
import env from './env';
const someRequiredSecret = env.someRequiredSecret;| Env Var Type | State of Variable | Return Value/Behavior |
|---|---|---|
| optional | set | ✅ Associated value returned as string |
| optional | unset | ✅ undefined returned |
| required | set | ✅ Associated value returned as string |
| required | unset | 💥 Runtime error |
| N/A - Unknown | ??? | 💥 Compilation error |
⚠️ Retrieving an unset andrequiredenv variable at the root of a file will throw an error and the app will fail to start.
Autocomplete and Strongly Typed Keys are your new best friend! Using simple-env makes it easier for devs to utilize environment variables via autocomplete and requiring defined keys prevents typos and makes refactoring incredibly simple.
| Feature | simple-env |
dotenv |
env-var |
|---|---|---|---|
| Zero Dependencies | ✅ | ✅ | ✅ |
| JS/TS Support | ✅ | ✅ | ✅ |
| Required vs Optional Specification | ✅ | ❌ | ✅ |
| Autocomplete | ✅ | ❌ | ❌ |
| Strongly Typed Keys | ✅ | ❌ | ❌ |
| Single Location Refactor | ✅ | ❌ | ❌ |
| Return Type Helpers | 🔜 | ❌ | ✅ |
| Loads .env | 🔜 | ✅ | ❌ |
Let's see how some of the features above look in code:
// fileA.ts
const secret = process.env.SECRET;
// fileB.ts
const secret = process.env.SECRE;
// 👆 Brittle, susceptible to typos, weak types, and painful to refactor 😓
const env = setEnv({
required: { secret: 'SOMETHING_SECRET' },
});
const secret = env.secret;
const secret = env.secre; // Property 'secre' does not exist on type '{ readonly secret: string; }'. Did you mean 'secret'? ts(2551)
// 👆 Compilation errors on typos, autocompletes as you type, and env var key can be modified without needing to refactor everywhere 👌
const env = setEnv({
required: { requiredSecret: 'SOME_REQUIRED_SECRET' },
optional: { optionalSecret: 'SOME_OPTIONAL_SECRET' },
});
env.requiredSecret.valueOf(); // No error
env.optionalSecret.valueOf(); // Object is possibly 'undefined'. ts(2532)
// 👆 Extremely strong typing - it knows what's required vs optional, which helps you catch bugs faster 🐞setEnv accepts multiple optional arguments:
// src/env.ts
import setEnv from '@americanairlines/simple-env';
export const env = setEnv({
required: {
nodeEnv: 'NODE_ENV',
someRequiredSecret: 'SOME_REQUIRED_SECRET',
},
});You can choose to only include optional env vars by passing in a single object:
// src/env.ts
import setEnv from '@americanairlines/simple-env';
export const env = setEnv({
optional: {
anOptionalSecret: 'AN_OPTIONAL_SECRET',
},
});If you want to set your env vars in multiple groups, make sure to destructure the optional env vars properly.
// src/env.ts
import setEnv from '@americanairlines/simple-env';
setEnv({
required: {
nodeEnv: 'NODE_ENV',
someRequiredSecret: 'SOME_REQUIRED_SECRET',
},
});
export const env = setEnv({
optional: {
anOptionalSecret: 'AN_OPTIONAL_SECRET',
},
});NOTE: if you choose to assign
optionalandrequiredenv vars individually,setEnvshould only be done once for each or you will overwrite your previously defined values.
Interested in contributing to the project? Check out our Contributing Guidelines.
- Install dependencies with
npm i - Run
npm run devto compile and re-compile on change - Run
npm link - Navigate to another Node.js project and run
npm link @americanairlines/simple-env
You can now use simple-env functionality within your project. On changing/adding functionality, the @americanairlines/simple-env package will update within your other project so you can test changes immediately.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent