Feature Request: Type-Safe Environment Variables with Built-in Validation and Parsing

[orafaelfragoso]

Goals

1. Improve Developer Experience: Provide type safety and autocompletion for environment variables, reducing common errors.
2. Early Error Detection: Fail fast during startup/build if required environment variables are missing or have incorrect types, preventing runtime surprises.
3. Clearer Env Structure: Introduce a dedicated env.ts (or src/env.ts) file to centralize environment variable definition, parsing, and validation.
4. Enhanced Code Reliability: Reduce bugs caused by typos in process.env access or incorrect assumptions about variable types or presence.
5. Explicit Client/Server/Edge Scoping: Make it clearer which variables are intended for which environment and help prevent accidental exposure of server-side variables to the client.

Non-Goals

1. Replacing .env files: This feature would work alongside existing .env file loading mechanisms, providing a typed layer on top.
2. Introducing external runtime validation libraries (e.g., Zod) into Next.js core: The aim is to achieve validation using TypeScript's type system and custom parsing/validation logic within the env.ts file itself, processed by SWC.
3. Altering the NEXT_PUBLIC_ prefix requirement for client-side variables: This convention will still be respected and enforced.

Background

Currently, Next.js loads environment variables from .env files and differentiates client-side variables using the NEXT_PUBLIC_ prefix. While functional, this approach has a few pain points for developers:

• Lack of Type Safety: Accessing process.env.MY_VAR offers no type information, leading to potential type errors at runtime (e.g., expecting a number but getting a string or undefined). Autocompletion is also unavailable.
• No Built-in Validation: Next.js doesn't inherently validate if required environment variables are present or if their values conform to expected types (e.g., a string being a valid URL, or a string representing a boolean being 'true' or 'false'). This often leads to runtime errors that could be caught earlier.
• Silent Failures for Missing Variables: If a non-NEXT_PUBLIC_ variable is missing, the application might start but then fail unexpectedly when the variable is accessed.
• Manual Parsing: Developers often write boilerplate code to parse environment variables (e.g., parseInt(process.env.PORT), process.env.FEATURE_FLAG === 'true') and handle potential errors.

Many developers address these issues by integrating third-party libraries like Zod, T3 Env, or by writing custom scripts. However, having a built-in, optional mechanism within Next.js would streamline this process, improve the out-of-the-box developer experience, and encourage best practices for environment variable management.

This proposal aims to provide a first-class, albeit experimental, solution within Next.js itself, leveraging its existing SWC infrastructure for transpilation.

Proposal

I propose introducing an experimental flag in next.config.js, for example, experimental: { typedEnvs: true }. When enabled, Next.js would look for an env.ts (or src/env.ts) file.

1. env.ts File Structure:
This file would export a typed object, potentially after performing parsing and validation:

// env.ts
import { type NextEnv } from 'next'; // A new type provided by Next.js

interface AppEnv extends NextEnv {
  client: {
    NEXT_PUBLIC_API_URL: string
    NEXT_PUBLIC_ENABLE_FEATURE_X: boolean
  }
  server: {
    DATABASE_URL: string
    API_KEY: string
    WORKER_COUNT: number
  }
  edge?: {
    KV_NAMESPACE_ID?: string
  }
}

export {
    client: {
      NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
      NEXT_PUBLIC_ENABLE_FEATURE_X: process.env.NEXT_PUBLIC_ENABLE_FEATURE_X,
    },
    server: {
      DATABASE_URL: process.env.DATABASE_URL,
      API_KEY: process.env.API_KEY,
      WORKER_COUNT: process.env.WORKER_COUNT,
    },
} satisfies AppEnv

2. Next.js Integration:

• Type Definition: Next.js would provide a base NextEnv type:

  export interface NextEnvVars { [key: string]: string | number | boolean | undefined; }
  export interface NextEnv { client: NextEnvVars; server: NextEnvVars; edge?: NextEnvVars; }

• Loading & Validation: On startup/build (if typedEnvs is true), Next.js would:
  • Locate env.ts and parse it.
  • If the type check fails or some value is missing, Next.js will halt with a clear error message.
• Variable Exposure:
  • Client: Only properties from the validated env.client object (and only those prefixed with NEXT_PUBLIC_) would be inlined into the client bundle, accessible via process.env or the imported env.client.
  • Server/Edge: The validated env.server and env.edge objects would be available for import in their respective runtimes.
• Developer Usage: Developers can import the typed env object:

  import { env, Env } from './env'; // or from a path alias
  const apiUrl = env.client.NEXT_PUBLIC_API_URL;
  if (typeof window === 'undefined') { // Server-side
    const dbUrl = env.server.DATABASE_URL;
  }

3. Error Handling:

• Missing/Invalid Variables: Throw errors and stop the build/dev server if env.ts validation fails.
• Incorrect Usage:
  • Server variables will not be bundled for the client. Accessing env.server.SOME_KEY on the client would result in env.server being undefined (or the access proxied to throw an error).

Benefits of this approach:

• Leverages existing infrastructure.
• Provides immediate feedback on environment variable issues.
• Centralizes environment variable logic.
• Improves type safety significantly.
• Not relying on third-party libs and their support for the rapidly evolving NextJS ecosystem

---

Yes, I am interested in contributing to the implementation of this feature if it's well-received by the community and maintainers. I'm happy to discuss the technical details further and refine the proposal based on feedback.