Skip to content

πŸ”’ Makes sure you don't accidentally deploy apps with missing or invalid environment variables

License

Notifications You must be signed in to change notification settings

DZakh/rescript-envsafe

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

35 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

npm

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.