API needed: an immutable expression to detect production/dev

[Yvem]

Hi, new contributor here, trying to be help.

As of now, some tools/libs do production<->dev detection for various reasons:

• example: bundlers removing dead code in prod by evaluating process.env.NODE_ENV
• example: an assertion lib dropping the assertion error message in production: https://github.com/alexreardon/tiny-invariant?tab=readme-ov-file#dropping-your-message-for-kb-savings by putting an optimized branch behind process.env.NODE_ENV
• example: automatically enabling/disabling a "strict mode" in dev, such as React "StrictMode"

However this process.env.NODE_ENV expression is not available by default in all runtimes, for ex. Cloudflare Workers: alexreardon/tiny-invariant#205 (without node compat)

There are already existing ideas to standardize this feature, for ex into a boolean __DEV__: https://github.com/jaredpalmer/tsdx?tab=readme-ov-file#__dev__

I suggest this feature to be considered in minimum common API. This expression should be easily detected by bundlers but also be working in production, being immutable and set from the outside.

Thanks!

edit: added an example

[jasnell]

FWIW, Cloudflare Workers now implements process.env so you can fairly trivially define the process.env.NODE_ENV manually if you want. That said, there are a number of reasons why use of it is not the best (https://www.platformatichq.com/node-principles) and it's not something I personally think would make a good work item here. I'm open to other opinions on it tho since I do know it is broadly used.

[mk-pmb]

I'd love if the solution would be more open than just "dev"/"prod". People might have other stages like "staging" or "demo". I'd be ok with starting with just "dev"/"prod", to address the most urgent needs, as long as we can extend it later, so ideally not a boolean.

[Yvem]

Hi @mk-pmb thanks for bringing this up. This is a bit complicated as different concepts are often conflated, and the example given above process.env.NODE_ENV is also mixing concepts.

Not all architectures have dev/staging/prod. There are also "release channels" considerations such as stable/beta/nightly. There are also different environment in the same category for ex. prod, prod-cn, prod-fedramp (China, USA federal)

In general, the code should be unaware of those considerations and rely on injected environment variables.

In this case, we're really looking for a very simple, easily matchable boolean "dev/prod" mode, ex. __DEV__. This will control extended assertions, verbose error messages that should not make it in the final code for perf reasons.

But we could totally imagine another __ENV__ variable to mirror NODE_ENV, which could be used to derive other implementation details if injecting ENV vars is inconvenient.

[mk-pmb]

If we want a boolean flag specifically to control debug messages, let's name it __DEBUG__ instead. The concepts "developer" and "someone who wants to debug the app" will often have huge overlap, but won't always be identical.

[Yvem]

Also @jasnell thanks for responding 👋

Cloudflare Workers now implements process.env

AFAIU that's only when enabling "compatibility_flags": [ "nodejs_compat" ] which is not on by default.

[Yvem]

@mk-pmb I'd say __DEV__ is slightly more generic than __DEBUG__.

IMO debug implies a deliberate effort to find a specific bug while dev is more generic.

For ex. one can be building a feature and the extra "dev" code may be showcasing missing parts. A real life example would be React's StrictMode which runs useEffect 2x times to surface potential bugs and also warn about missing keys. Those dev features are not targeted at a specific bug.

[ekwoka]

would be nice to have one that isn't "branded" as NODE at least. Not a fan of __THING__ though either. This isn't Python.

[mk-pmb]

Yeah, probably should be somewhere on navigator or similar.

[thescientist13]

Yeah, instead of using environment as a reference / naming point, as this is often used / attributed to where code runs (e.g. dev / demo / test / stage / pre-prod / prod / etc), it may be better to approach the naming here on how code is built. How code is built doesn't necessarily have to influence where it is run.

I think the where question is better left to userland to define on a per project / organizational basis, and the how is crafted specifically for tooling which often has just two "modes" effectively, and so maybe calling it something like BUILD_MODE might help avoid the footgun that eventually become NODE_ENV (as also cited by @jasnell) ?

So putting it all together, a project may mix and match as needed

Local Development

• BUILD_MODE=development
• MY_COMPANY_ENV=local

Testing

• BUILD_MODE=development
• MY_COMPANY_ENV=test

Stage

• BUILD_MODE=production
• MY_COMPANY_ENV=stage

Production

• BUILD_MODE=production
• MY_COMPANY_ENV=prod

[sm17p]

Not sure if this helps but I too agree with what @thescientist13 suggested. Overall, as a developer I want to do two things -

1. First, to specify what kind of build I want DEV, DEBUG or PROD. I think having a specific boolean for each would suffice coming from what popular budlers do. This is something what an runtime environment should implement .
2. Secondly, I want to be able to describe the corresponding ENVIRONMENT or MODE to tag it with. It couble now be development, staging, release, testing, stable, beta, nightly, canary, prod, prod-cn or whatever I want to name it. This is something what an environment should allow developers to set of configure with a few standard defaults?

The one downside to the above approach I see is a divide in my env configuration which could possibly look like

// In these three build modes files below I'd define my build specific configuration? Like what happens in cargo

• .env.dev
• .env.debug
• .env.prod
  and then my mode specific metadata in
• .env.development
• .env.staging
• .env.nightly
• .env.canary
• .env.production
• .env.prod-cn
• etc...

witth the example approach taken above I now have two files which could mean the same thing? .env.dev and .env.development? This looks kinda messy to me. Maybe all of this need to reside inside package.json instead?

[mk-pmb]

It should definitely not be in package.json because the entire point of having those indicators be provided by the runtime is to allow using the exactly same files with exactly same content.

[mk-pmb]

Would it be useful to specify that whatever indicator we come up with can be used only as the only condition to a top-level unindented "if" (with very restrictiv rules on where the curly braces must go) or a top-level unindented const declaration? That would simplify preprocessing code with pattern matching tools like sed.
Such tools would fail if people use said constructs in a template string or a multi-line comment, but that may be an acceptable bug for the tools.