How to validate environment in dev/build/start?

[rovo89]

Summary

I thought it would be a good idea to ensure that environment variables are properly set. I'm using zod for validation and put the logic into a separate module, so I can use that instead of accessing process.env directly.

So far, so good, but now I'd like to get feedback about missing or invalid variables as early possible, in all three commands: next dev, next build and next start. For startup code, instrumentation seems to be the expected choice:

export async function register() {
    throw new Error('Instrumentation was executed');
}

But it doesn't work very well for my case. It's not executed at all during next build, and next start just catches the error and then says "Ready" instead of existing. Sure, I could use process.exit(1) instead, but still the build wouldn't have validation (and it needs some API keys from the environment to build static pages).

Including the check (or the import of the checking module) in a page doesn't work either, it's only checked on demand in next dev and executed very late in next build.

That last option seems to be integrating the check in next.config.ts. Here I can either throw or exit and that prevents all three commands from running. But I'm a bit afraid that it might run before the framework has fully set up the environment.

So - is it safe to use next.config.ts for validation? Or is there a better way?

Additional information

No response

Example

No response

[x3noku]

If it is still actual question, I saw several times and personally do it myself. Using jiti in next.config.js to validate env file where all validation business stored.

import { createJiti } from 'jiti';

/**
 * Import env files to validate at build time. Use jiti so we can load .ts files in here.
 *
 * @type {import('./env.ts')}
 */
const { env } = await createJiti(import.meta.url).import('./env');

And for env validation personally prefer using @t3-oss/env-core or @t3-oss/env-nextjs

[theoephraim]

Unfortunately, using instrumentation is not reliable for this kind of thing - as you discovered it does not always execute and things just get more complicated in all the permutations of static/dynamic/output/runtimes/etc... There really should be a general hooks system but alas there is not.

Next also does not give us any hooks related to env var loading, so the only option I have discovered is to override the internal @next/env module.

This is precisely what I've done to build the Next.js integration for a general env var management tool - https://varlock.dev

It gives you the validation logic you are looking for, and a whole lot more :) It also is trying to be a universal system applicable to every project :)