README.md

ReScript envsafe 🔒

Validate access to environment variables and parse them to the right type. Makes sure you don't accidentally deploy apps with missing or invalid environment variables.

========================================
❌ Invalid environment variables:
    API_URL ("http//example.com/graphql"): Invalid url
💨 Missing environment variables:
    MY_VAR: Disallowed empty string
    PORT: Missing value
========================================

Heavily inspired by the great project envsafe, but designed with care for ReScript users:

• Always strict - only access the variables you have defined
• Built for node.js and the browser
• Composable parsers with rescript-schema

How to use

Install

npm install rescript-envsafe rescript-schema

Then add rescript-envsafe and rescript-schema to bs-dependencies in your rescript.json:

{
  ...
+ "bs-dependencies": ["rescript-envsafe", "rescript-schema"],
+ "bsc-flags": ["-open RescriptSchema"],
}

Basic usage

%%private(let envSafe = EnvSafe.make())

let nodeEnv = envSafe->EnvSafe.get(
  "NODE_ENV",
  S.union([
    S.literal(#production),
    S.literal(#development),
    S.literal(#test),
  ]),
  ~devFallback=#development,
)
let port = envSafe->EnvSafe.get("PORT", S.int->S.Int.port, ~fallback=3000)
let apiUrl = envSafe->EnvSafe.get("API_URL", S.string->S.String.url, ~devFallback="https://example.com/graphql")
let auth0ClientId = envSafe->EnvSafe.get("AUTH0_CLIENT_ID", S.string)
let auth0Domain = envSafe->EnvSafe.get("AUTH0_DOMAIN", S.string)

// 🧠 If you forget to close `envSafe` then invalid vars end up being `undefined` leading to an expected runtime error.
envSafe->EnvSafe.close

API Reference

EnvSafe.make

(~env: EnvSafe.env=?) => EnvSafe.t

%%private(let envSafe = EnvSafe.make(~env=%raw("window.__ENVIRONMENT__")))

Creates envSafe to start working with environment variables. By default it uses process.env as a base for plucking the vars, but it can be overridden using the env argument.

EnvSafe.get

(EnvSafe.t, string, S.t<'value>, ~allowEmpty: bool=?, ~fallback: 'value=?, ~devFallback: 'value=?, ~input: option<string>=?) => 'value

let port = envSafe->EnvSafe.get("PORT", S.int->S.Int.port, ~fallback=3000)

Gets an environment variable from envSafe applying coercion and parsing logic of schema.

Possible options

Name	Type	Description
name	string	Name of the environment variable
schema	S.t<'value>	A schema created with rescript-schema. It's used for coercion and parsing. For bool schemas coerces "0", "1", "true", "false", "t", "f" to boolean values. For int and float schemas coerces string to number. For other non-string schemas the value is coerced using JSON.parse before being validated.
fallback	'value=?	A fallback value when the environment variable is missing.
devFallback	'value=?	A fallback value to use only when NODE_ENV is not production. This is handy for env vars that are required for production environments, but optional for development and testing.
input	string=?	As some environments don't allow you to dynamically read env vars, we can manually put it in as well. Example: input=%raw("process.env.NEXT_PUBLIC_API_URL").
allowEmpty	bool=false	Default behavior is false which treats empty strings as the value is missing. if explicit empty strings are OK, pass in true.

EnvSafe.close

(EnvSafe.t) => unit

envSafe->EnvSafe.close

It makes a readable summary of your issues, console.error-log an error, window.alert() with information about the missing envrionment variable if you're in the browser, throws an error (will exit the process with a code 1 in node).

🧠 If you forget to close envSafe then invalid vars end up being undefined leading to an expected runtime error.