Typed ENV in Nx monorepo — workaround and asking for guidance

[DrewLandgraveCbsi]

Hi — I'm using varlock in an Nx monorepo and ran into an issue getting the typed ENV from varlock/env to work across all apps and libs. Here's what was going on and what I did to fix it. I'd welcome any guidance on whether this is a reasonable approach or if there's a better way.

My setup

• Nx monorepo with many apps and libs
• TypeScript with project references; each app/lib has its own tsconfig that extends a root tsconfig.base.json
• I'm using @generateTypes in .env.schema so varlock generates an env.d.ts at the repo root with the module augmentation for varlock/env (e.g. TypedEnvSchema extends Readonly<CoercedEnvSchema>)

The problem

That generated env.d.ts wasn't being picked up when building or type-checking individual apps/libs. So in code that did import { ENV } from 'varlock/env', TypeScript was only seeing the package's own types (with an empty TypedEnvSchema) and I got errors like Property 'APP_ENV' does not exist on type 'TypedEnvSchema'.

From what I could tell, it came down to how Nx/TypeScript are set up: each project's tsconfig has its own include/files, and those override the base rather than merging. So putting env.d.ts in the base config didn't pull it into the individual project builds. I also didn't want to add a triple-slash reference in every file that uses ENV, or manually add the same include to every app and lib tsconfig.

What I did to fix it

I ended up using a path mapping so that, for type-checking only, varlock/env resolves to a small shim at the repo root:

1. In tsconfig.base.json I added the following to compilerOptions.paths:

   "varlock/env": ["./varlock-env.d.ts"]

2. I added a shim file varlock-env.d.ts at the repo root that:

   • Has /// <reference path="./env.d.ts" /> so the generated types (and the augmentation) are included
   • Re-declares the varlock/env module with the same exports as the package (e.g. ENV, initVarlockEnv, redactSensitiveConfig, etc.) so the module declaration is complete when TypeScript resolves to this file

With that, every app and lib that extends the base gets the typed ENV automatically. Runtime still uses the real varlock package from node_modules; only type resolution goes through the shim.

Where I'm unsure

• I had to copy the list of exports from varlock's env.d.ts into the shim. If the package adds or changes exports in a future version, I'll need to update the shim to stay in sync. I'm not sure if there's a more maintainable way to do this.
• I'm also not sure if there's an intended or recommended pattern for using varlock's typed env in Nx (or other monorepos) that would avoid this kind of workaround.

If you have any guidance—e.g. a recommended approach for monorepos, or a better way to wire in the generated types without maintaining a shim—I'd really appreciate it. Thanks for varlock and for any pointers you can share.

[theoephraim]

I haven't done much exploration with Nx although it has been on my to-do list - so thanks for digging in!

In our own monorepos, each app usually has its own .env.schema which can import any common items from the root (or other siblings), and define its own config that only it cares about or should be in charge of. In this case each gets its own @generateTypes call and ends up with its own types file within that package.

# @import(../../, KEY1, KEY2)  # imports keys from root
# @import(../other-package/, KEY3)  # imports from another sibling child package
# @generateTypes(lang="ts", path="env.d.ts")
# ---

Some of those sub packages could just import everything from the root, but at least it becomes explicit and gives you a chance to add more config if needed.

# @import(../../)  # imports everything
# @generateTypes(lang="ts", path="env.d.ts")
# ---

(above assuming you have a root .env.schema and packages in packages/package-a)

I know Nx is a whole world with special ways of doing things so I'll have to dig in a little to test some things out.

[DrewLandgraveCbsi]

Thanks man! I'll try adding .env.schema's to each app. Each one does have it's own set of env vars. I'll let you know how it goes.

Saw you guys on the Syntax podcast the other day and thought, This is exactly what I need 😄

[theoephraim]

How did this go? Run into any more hurdles? I'd love to make sure we have good Nx support - happy to pair with you and work through any other issues you may encounter.