# @rocketmakers/environment

> This package is used to describe the contract your application has to its running environment, and make this contract available to other downstream consumers of your package.

Latest version **0.5.7** (published 2026-06-10) · ISC license · 0 weekly downloads

## Install

```sh
npm install @rocketmakers/environment
pnpm add @rocketmakers/environment
yarn add @rocketmakers/environment
bun add @rocketmakers/environment
```

Provides the command `environment-resolve`.

## Health

**Score 50/100 (C)** — status: active.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.7 |
| Published | 2026-06-10 |
| First published | 2021-03-24 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 107.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | rocketmakers-admin, adamrocketmakers, rocketsoper, harry-rocketmakers, dave-rocketmakers |

## Links

- npm: https://www.npmjs.com/package/@rocketmakers/environment
- Repository: https://github.com/Rocketmakers/rocketmakers-packages
- Homepage: https://github.com/Rocketmakers/rocketmakers-packages#readme
- Issues: https://github.com/Rocketmakers/rocketmakers-packages/issues
- npm.io page: https://npm.io/package/@rocketmakers/environment

## Dependencies (3)

- [ajv](https://npm.io/package/ajv.md) 8.20.0
- [yaml](https://npm.io/package/yaml.md) 2.9.0
- [tslib](https://npm.io/package/tslib.md) 2.8.1

## Recent versions

- 0.5.7 (latest) — 2026-06-10
- 0.5.6 — 2026-04-22
- 0.5.5 — 2026-01-08
- 0.5.4 — 2025-12-11
- 0.5.3 — 2024-12-03
- 0.5.2 — 2024-11-14
- 0.5.1 — 2023-11-22
- 0.4.0 — 2022-12-16
- 0.3.10 — 2022-04-01
- 0.3.9 — 2022-04-01
- 0.3.8 — 2022-03-30
- 0.3.7 — 2022-03-30
- 0.3.2 — 2022-03-25
- 0.1.4 — 2021-03-24
- 0.1.3 — 2021-03-24
- … 2 more at https://npm.io/package/@rocketmakers/environment/versions

## README

# Rocketmakers Environment

## Introduction

This package is used to describe the contract your application has to its running environment, and make this contract available to other downstream consumers of your package.

## Code Generation

You can define a (machine readable) JSON/YAML file, that will be used to generate a TypeScript Environment class for consumption in your application

```JSON
{
  "$schema": "./node_modules/@rocketmakers/environment/schema/environment-schema.json",
  "version": 1,
  "name": "Authentication",
  "prefix": "AUTH",
  "variables": [
    { "kind": "string", "name": "TOKEN", "secret": true },
    { "kind": "string", "name": "NAME", "optional": true },
    { "kind": "string", "name": "CONTACTS", "optional": true, "array": true },
    { "kind": "number", "name": "RATE" },
    { "kind": "integer", "name": "PORT" },
    { "kind": "file-path", "name": "RSA_FILE", "secret": true }
  ]
}
```

> Note: `secret` is purely advisory for any consumers, and not directly used within this package!

Will generate `environment.generated.ts`...

```TypeScript
/*
This file is generated via the "@rocketmakers/environment" package
!!!DO NOT MODIFY THE CODE DIRECTLY INSIDE THIS FILE!!!
To make changes, modify the environment json file and run the "environment-generate" command
*/
import { environmentVariable } from '@rocketmakers/environment';
/* Generated Environment Configuration */
export class AuthenticationEnvironment {
    /* contacts :: AUTH_CONTACTS_0, AUTH_CONTACTS_1, ..., AUTH_CONTACTS_<n> */
    @environmentVariable.string('AUTH_CONTACTS', { optional: true, array: true })
    contacts?: string[];
    /* name :: AUTH_NAME */
    @environmentVariable.string('AUTH_NAME', { optional: true })
    name?: string;
    /* port :: AUTH_PORT */
    @environmentVariable.integer('AUTH_PORT')
    port!: number;
    /* rate :: AUTH_RATE */
    @environmentVariable.number('AUTH_RATE')
    rate!: number;
    /* rsaFile :: AUTH_RSA_FILE */
    @environmentVariable.filePath('AUTH_RSA_FILE')
    rsaFile!: string;
    /* token :: AUTH_TOKEN */
    @environmentVariable.string('AUTH_TOKEN')
    token!: string;
}
```

> Note: Array properties will append the index onto the Key at runtime, e.g. To build the array from "XYZ", we will search for "XYZ_0" then "XYZ_1"... until an undefined value is found to terminate the read

If you place the json file in the root of your project (`environment.json`) - you can add a script to your `package.json` to turn the json into the typescript Environment class!

If your project is TypeScript 4

```json
{
  "scripts": {
    "env-generate": "environment-generate ./environment.json ./source/environment.generated.ts"
  }
```

If your project is TypeScript 3

```json
{
  "scripts": {
    "env-generate": "environment-generate-v3 ./environment.json ./source/environment.generated.ts"
  }
```

`environment-generate` takes 2 parameters

- input file (.json/.yaml)
- output file (.ts)

## Do It Yourself

Alternatively, you can just author your own Environment class (as per the example above)!

## Consuming in your Application

To resolve your configuration from the environment...

```TypeScript
import { readFromEnvironment } from '@rocketmakers/environment';

import { AuthenticationEnvironment } from './environment.generated';

export function getConfig(): Promise<AuthenticationEnvironment> {
  return readFromEnvironment(AuthenticationEnvironment);
}

```

There is a further helper method to allow you to supply the overriding optional values (making the properties mandatory - `Required<T>`)

```TypeScript
import { ensureEnvironmentRequired, readFromEnvironment } from '@rocketmakers/environment';

import { AuthenticationEnvironment } from './environment.generated';

export async function getConfig(): Promise<Required<AuthenticationEnvironment>> {
  const withOptional = await readFromEnvironment(AuthenticationEnvironment);

  return ensureEnvironmentRequired(withOptional, {
    name: 'Only used if not supplied by the environment',
    contacts: [],
  });
}

```

---
_Source: https://npm.io/package/@rocketmakers/environment · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._