https://github.com/mpetuska/application.env
.env file loader for node and browser
https://github.com/mpetuska/application.env
browser library nodejs
Last synced: 4 months ago
JSON representation
.env file loader for node and browser
- Host: GitHub
- URL: https://github.com/mpetuska/application.env
- Owner: mpetuska
- License: apache-2.0
- Created: 2020-12-27T10:15:14.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-10T18:21:59.000Z (almost 3 years ago)
- Last Synced: 2025-10-28T00:25:29.498Z (8 months ago)
- Topics: browser, library, nodejs
- Language: TypeScript
- Homepage:
- Size: 49 MB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://gitpod.io/#https://github.com/mpetuska/application.env)
[](https://www.npmjs.com/package/application.env)
# application.env
Small utility to load environment configurations that works for both, node and the browser, including a react context helper for react apps.
## Usage
In most cases, all you need to do is invoke load function:
```javascript
import { load } from 'application.env';
load().then((env) => console.log('Env ready', env));
```
The above will load `application.env` file and append it to global object (`proccess.env` for Node and `window.env`
for Browser).
> For Node you also get sync option:
> ```javascript
> import { loadSync } from 'application.env/node';
>
> const env = loadSync();
> console.log(env === proccess.env); // true
> ```
All load variants takes an optional options argument. Here's how its fields look with their default values:
```typescript
function load(
options: LoadOptions = {
path: 'application.env', // Path to a file
failSilently: false, // Returns/appends an empty object on error instead of throwing it.
validator: ObjectValidator // Environment validator (read bellow)
}): Promise {}
```
## Validation
All `load` functions also provide a way to validate loaded env before appending it to the global objects via the second
`validator` optional argument. It's basically an object describing the shape of your env object with exposed properties to handle missing values.
```typescript
interface Env {
propOne: string;
nonStringProperty: number;
optionalProperty: string;
criticalProperty: string;
}
const validator: ObjectValidator = {
propOne: {
errorMessage: "No default provided, throwing an error",
},
nonStringProperty: {
default: 420,
converter: (value) => Number(value)
},
optionalProperty: {
default: "DEFAULT VALUE",
},
criticalProperty: {
critical: true,
errorMessage: "The application cannot function without this property. Terminating...",
},
};
load({validator})
```
## TypeScript
The module comes with it's own type declarations on both, public API and global scope extensions. It's also possible to declare your own named properties on loaded Env object via TS augmentation on `ApplicationEnv` namespace:
```typescript
declare global {
namespace ApplicationEnv {
interface Env {
MY_PROP_ONE?: string;
ANOTHER_REQUIRED_PROP: string;
ANOTHER_OPTIONAL_PROP: string;
NODE_ENV?: string;
}
}
}
```
## React
This module exposes a React context provider and hook to consume the context in a child component
```typescript
import ApplicationEnvProvider, { useApplicationEnv } from 'application.env/react';
const App: FC = (): JSX.Element => {
return (
);
};
const Child: FC = () : JSX.Element => {
const envVars = useApplicationEnv();
return (
{envVars.MY_PROP_ONE}
)
}
export default App;
```
## Behind the scenes
* Node: the file is loaded from your file system.
* Browser: the file is fetched from the same server that's serving HTML & JS files.
* React: the file is fetched from the same server that's serving HTML & JS files.