Environment Variables

Create T3 App uses Zod↗ for validating your environment variables at runtime and buildtime by providing some additional logic in src/env.mjs.

env.mjs

TLDR; If you want to add a new environment variable, you must add it to both your .env as well as define the validator in src/env.mjs.

This file is split into two parts - the schema and object destructuring as well as the validation logic. The validation logic should not need to be touched.

const server = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
});

const client = z.object({
  // NEXT_PUBLIC_CLIENTVAR: z.string(),
});

const processEnv = {
  NODE_ENV: process.env.NODE_ENV,
  // NEXT_PUBLIC_CLIENTVAR: process.env.NEXT_PUBLIC_CLIENTVAR,
};

Server Schema

Define your server-side environment variables schema here.

Make sure you do not prefix keys here with NEXT_PUBLIC in order not to leak important secrets to the client.

Client Schema

Define your client-side environment variables schema here.

To expose them to the client you need to prefix them with NEXT_PUBLIC. Validation will fail if you don’t to help you detect invalid configuration.

processEnv Object

Destruct the process.env here.

We need a JavaScript object that we can parse our Zod-schemas with and due to the way Next.js handles environment variables, you can’t destruct process.env like a regular object, so we need to do it manually.

TypeScript will help you make sure that you have destructed all the keys from both schemas.

// ❌ This doesn't work, we need to destruct it manually
const schema = z.object({
  NEXT_PUBLIC_WS_KEY: z.string(),
});

const validated = schema.parse(process.env);

Validation Logic

For the interested reader:

const isServer = typeof window === "undefined";

const merged = server.merge(client);
const parsed = isServer
  ? merged.safeParse(processEnv)  // <-- on server, validate all
  : client.safeParse(processEnv); // <-- on client, validate only client

if (parsed.success === false) {
  console.error(
    "❌ Invalid environment variables:\n",
    ...formatErrors(parsed.error.format()),
  );
  throw new Error("Invalid environment variables");
}

// proxy allows us to remap the getters
export const env = new Proxy(parsed.data, {
  get(target, prop) {
    if (typeof prop !== "string") return undefined;
    // on the client we only allow NEXT_PUBLIC_ variables
    if (!isServer && !prop.startsWith("NEXT_PUBLIC_"))
      throw new Error(
        "❌ Attempted to access serverside environment variable on the client",
      );
    return target[prop]; // <-- otherwise, return the value
  },
});

Using Environment Variables

When you want to use your environment variables, you can import them from env.mjs and use them as you would normally do. If you import this on the client and try accessing a server-side environment variable, you will get a runtime error.

import { env } from "../../env.mjs";

// `env` is fully typesafe and provides autocompletion
const dbUrl = env.DATABASE_URL;

import { env } from "../env.mjs";

// ❌ This will throw a runtime error
const dbUrl = env.DATABASE_URL;

// ✅ This is fine
const wsKey = env.NEXT_PUBLIC_WS_KEY;

.env.example

Since the default .env file is not committed to version control, we have also included a .env.example file, in which you can optionally keep a copy of your .env file with any secrets removed. This is not required, but we recommend keeping the example up to date to make it as easy as possible for contributors to get started with their environment.

Some frameworks and build tools, like Next.js, suggest that you store secrets in a .env.local file and commit .env files to your project. This is not recommended, as it could make it easy to accidentally commit secrets to your project. Instead, we recommend that you store secrets in .env, keep your .env file in your .gitignore and only commit .env.example files to your project.

Adding Environment Variables

To ensure your build never completes without the environment variables the project needs, you will need to add new environment variables in two locations:

📄 .env: Enter your environment variable like you would normally do in a .env file, i.e. KEY=VALUE

📄 env.mjs: Add the appropriate validation logic for the environment variable by defining a Zod schema, e.g. KEY: z.string(), and destruct the environment variable from process.env in the processEnv object, e.g. KEY: process.env.KEY.

Optionally, you can also keep .env.example updated:

📄 .env.example: Enter your environment variable, but be sure to not include the value if it is secret, i.e. KEY=VALUE or KEY=

Example

I want to add my Twitter API Token as a server-side environment variable

1. Add the environment variable to .env:

TWITTER_API_TOKEN=1234567890

2. Add the environment variable to env.mjs:

export const server = z.object({
  // ...
  TWITTER_API_TOKEN: z.string(),
});

export const processEnv = {
  // ...
  TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
};

NOTE: An empty string is still a string, so z.string() will accept an empty string as a valid value. If you want to make sure that the environment variable is not empty, you can use z.string().min(1).

3. Optional: Add the environment variable to .env.example, but don’t include the token

TWITTER_API_TOKEN=