Environment variables

[blittle]

Motivation

Platforms are not consistent in how they provide access to environment variables. We'd like to define a consistent API for environment variable access.

Environment variables on existing platforms

Cloudflare

Environment variables are injected into a scoped variable. For example, an API_TOKEN environment variable would be available within the env param:

export default {
  fetch(request, env, context) {
    // env.API_TOKEN
  },
};

Reference: https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker

Vercel

Environment variables are defined on process.env object. For example, an API_TOKEN environment variable would be available by process.env.API_TOKEN.

Reference: https://vercel.com/docs/concepts/functions/serverless-functions#environment-variables

Deno

Environment variables are retrieved through a global Deno.env object. For example, an API_TOKEN environment variable would be available by Deno.env.get('API_TOKEN')

Reference: https://doc.deno.land/deno/stable/~/Deno.env

NodeJS

Environment variables are defined on a global process.env object. For example, an API_TOKEN environment variable would be available by process.env.API_TOKEN.

Reference: https://nodejs.org/docs/latest/api/process.html#processenv

Shopify Oxygen

Environment variables are defined on a global Oxygen.env object. For example, an API_TOKEN environment variable would be available by Oxygen.env.API_TOKEN.

Reference: https://shopify.dev/custom-storefronts/oxygen/environment-variables

Options

Unify on one of the existing platform implementations

Which one?

import.meta

The import.meta object exposes context-specific metadata to a JavaScript module. We could utilize that container for environment variables, import.meta.env.API_TOKEN.

There is precedent to import.meta.env with Vite's implementation. The downside to this is that import.meta is only available in ES Modules.

[XadillaX]

Hourai.js (Winter @bytedance)

Environment variables are retrived through a global Hourai.process.env object, it like process.env in Node.js but mount in Hourai namespace.

Maybe not every platform supports import since Hourai.js is a single file runtime.

[SegaraRai]

FWIW Cloudflare Workers has another syntax called module workers, in which environment variables are passed as an argument to the handler function instead of being placed globally.

Reference: https://developers.cloudflare.com/workers/platform/environment-variables/#environmental-variables-with-module-workers, https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker

[jimmywarting]

Something that scare me a little bit is that any sub dependency can get access to the enviorment variable that i'm using myself.
I'm not really sure why we even need .env file that needs to be parsed in a specific way and having to depend on some dotenv package to parse it, when we can just simply have a .env.js that exports a default object and simply import it like import config from './.env.js'? it dose not have to be more complicated than that...

any how you should not put secrets in process.env... here is why: https://diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/

heck why don't we even have a way to import secrets with á.la http import style:
import secrets from 'https://example.com/secrets.json' { cookie: xyz }

any way... i think putting things in import.meta could save some security issues. only my files would have this secret meta data and the lodash dependency wouldn't know anything about my own secrets.

they need to be sandboxed somehow. more secure & possible encrypted.

[blittle]

@jimmywarting the concern makes sense. Though switching to a code import has downsides. An entirely new code deploy is necessary to change the vars (at least for single-file and bundled runtimes). That isn't desirable for all situations, where you want the same code artifact to behave differently depending on the "environment".

But maybe whether or not secrets defined in environment variables isn't to be solved here? They are needed, and the goal here is to have a standard way to access them.

[xtuc]

@blittle do you mind editing the Cloudflare example in the issue? The syntax you used is deprecated and https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker (env.VAR_NAME) should be used instead.

[amadsen]

From the perspective of a developer who just wants to have a consistent place to read environment variables, a module similar to hono/adapter's env() is almost what I want. std-env is even closer, but isn't quite working in a Cloudflare worker dev environment for me.

The Cloudflare API is the most challenging one to wrap in this way because its env parameter of the fetch handler is scoped to the handler. While this makes some sense in the context of a Function-as-a-Service environment because the developer's environment is deliberately limited to the fetch handler, it's also frustrating. I toyed around with using AsyncLocalStorage and a few other ideas to simplify it. The import { env } from "cloudflare:workers"; mechanism - which neither of the aforementioned modules are using - might allow for a consistent wrapper module though.

Has any progress been made on a standardized way of accessing environment variables and other metadata that I wouldn't see here?