T3 Env

https://github.com/t3-oss/t3-env
Admin
T3 Env provides a typesafe way to manage environment variables in your application, ensuring...
Tokens:12,757
Snippets:133
Trust Score:8.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install @t3-oss/env-nextjs with npm, pnpm, bun, or deno

Source: https://github.com/t3-oss/t3-env/blob/main/packages/nextjs/README.md

Install the package using your preferred package manager. The commands are equivalent alternatives; choose one based on your project setup.

```bash
# npm
npm i @t3-oss/env-nextjs

# pnpm
pnpm add @t3-oss/env-nextjs

# bun
bun add @t3-oss/env-nextjs

# deno
deno add jsr:@t3-oss/env-nextjs
```

--------------------------------

### Install project dependencies

Source: https://github.com/t3-oss/t3-env/blob/main/README.md

Navigate into the cloned directory and install project dependencies using Bun.

```sh
cd t3-env
bun i
```

--------------------------------

### Install Bun

Source: https://github.com/t3-oss/t3-env/blob/main/README.md

Install Bun on Linux/macOS or Windows. The first command is for Linux and macOS, the second for Windows.

```sh
curl -fsSL https://bun.sh/install | bash
```

```sh
powershell -c "irm bun.sh/install.ps1 | iex"
```

--------------------------------

### Install Valibot

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Installs the Valibot validation library.

```bash
npm install valibot
```

--------------------------------

### Install Zod

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Installs the Zod validation library.

```bash
npm install zod
```

--------------------------------

### Install ArkType

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Installs the ArkType validation library.

```bash
npm install arktype
```

--------------------------------

### Install @t3-oss/env-core with npm, pnpm, bun, or deno

Source: https://github.com/t3-oss/t3-env/blob/main/packages/core/README.md

Install the package using your preferred package manager. The deno command uses the JSR registry.

```bash
# npm
npm i @t3-oss/env-core

# pnpm
pnpm add @t3-oss/env-core

# bun
bun add @t3-oss/env-core

# deno
deno add jsr:@t3-oss/env-core
```

--------------------------------

### Using Valibot preset

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Example showing how to use a deployment platform preset with Valibot.

```ts
import { createEnv } from "@t3-oss/env-core";
import { vercel } from "@t3-oss/env-core/presets-valibot";
import * as v from "valibot";

export const env = createEnv({
  server: {
    DATABASE_URL: v.pipe(v.string(), v.url()),
  },
  extends: [vercel()],
  runtimeEnv: process.env,
});
```

--------------------------------

### Install @t3-oss/env-core and zod

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/core/page.mdx

Install the core package and zod. Also shows the JSR alternative for Deno. Requires TypeScript 5.0.0+ and ESM-only package.

```bash
npm install @t3-oss/env-core zod

# or using JSR
deno add jsr:@t3-oss/env-core
```

--------------------------------

### Install dependencies with pnpm or JSR

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

Install @t3-oss/env-nuxt and zod. Use pnpm or JSR (deno). Note that @t3-oss/env-core requires TypeScript 5 and is ESM-only, so use a module resolution that reads package.json#exports (Bundler recommended).

```bash
pnpm add @t3-oss/env-nuxt zod

# or using JSR
deno add jsr:@t3-oss/env-nuxt
```

--------------------------------

### Install @t3-oss/env-nuxt with npm, pnpm, bun, or deno

Source: https://github.com/t3-oss/t3-env/blob/main/packages/nuxt/README.md

Install the Nuxt package using your preferred package manager. The deno command uses the JSR registry.

```bash
# npm
npm i @t3-oss/env-nuxt
```

```bash
# pnpm
pnpm add @t3-oss/env-nuxt
```

```bash
# bun
bun add @t3-oss/env-nuxt
```

```bash
# deno
deno add jsr:@t3-oss/env-nuxt
```

--------------------------------

### Install @t3-oss/env-nextjs with pnpm or Deno

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

Install the Next.js integration package and Zod. The JSR alternative uses Deno. Requires TypeScript 5.0.0 or higher and an ESM-compatible module resolution (Bundler recommended).

```bash
pnpm add @t3-oss/env-nextjs zod

# or using JSR
deno add jsr:@t3-oss/env-nextjs
```

--------------------------------

### Zod usage with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Example environment configuration using Zod as the validation library.

```ts
import { createEnv } from "@t3-oss/env-core";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    PORT: z.coerce.number().default(3000),
  },
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: process.env,
});
```

--------------------------------

### ArkType usage with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Example environment configuration using ArkType as the validation library.

```ts
import { createEnv } from "@t3-oss/env-core";
import { type } from "arktype";

export const env = createEnv({
  server: {
    DATABASE_URL: type("string.url"),
    PORT: type("string.numeric.parse"),
  },
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_API_URL: type("string.url"),
  },
  runtimeEnv: process.env,
});
```

--------------------------------

### Valibot usage with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/standard-schema/page.mdx

Example environment configuration using Valibot as the validation library.

```ts
import { createEnv } from "@t3-oss/env-core";
import * as v from "valibot";

export const env = createEnv({
  server: {
    DATABASE_URL: v.pipe(v.string(), v.url()),
    PORT: v.optional(v.pipe(v.string(), v.transform(Number)), "3000"),
  },
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_API_URL: v.pipe(v.string(), v.url()),
  },
  runtimeEnv: process.env,
});
```

--------------------------------

### Extend presets with extends property

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

Use the extends property to include environment variables from presets like Vercel. The example shows extending the Vercel preset and accessing env.VERCEL_URL.

```ts
import { createEnv } from "@t3-oss/env-core";
import { vercel } from "@t3-oss/env-core/presets-zod";

export const env = createEnv({
  // ...
  // Extend the Vercel preset.
  extends: [vercel()],
});

env.VERCEL_URL; // string
```

--------------------------------

### Set isServer to detect server context

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

Use the isServer option to tell T3 Env when running in a server context. The example checks if window is undefined, which is true in Node.js environments.

```ts
import { createEnv } from "@t3-oss/env-core";

export const env = createEnv({
  // ...
  // Tell the library when we're in a server context.
  isServer: typeof window === "undefined",
});
```

--------------------------------

### Basic Zod environment validation with process.env

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/introduction/page.mdx

A basic Zod-based environment variable validation approach that parses process.env and augments the ProcessEnv interface for type safety. This example is used to illustrate the drawbacks that T3 Env solves, such as lack of transform and default value support, and issues with multiple environments.

```ts
import * as z from "zod";

const envVariables = z.object({
  DATABASE_URL: z.string(),
  CUSTOM_STUFF: z.string(),
});

envVariables.parse(process.env);

declare global {
  namespace NodeJS {
    interface ProcessEnv extends z.infer<typeof envVariables> {}
  }
}
```

--------------------------------

### Use env object in API endpoint

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/core/page.mdx

Import the env object in your application to access environment variables with type-safety and auto-completion. This example shows using env.OPEN_AI_API_KEY in a server-side API endpoint.

```ts
import { env } from "~/env"; // On server

export const GET = async () => {
  // do fancy ai stuff
  const magic = await fetch("...", {
    headers: { Authorization: env.OPEN_AI_API_KEY },
  });
  // ...
};
```

--------------------------------

### Coerce numbers from strings with Zod transforms and z.coerce.number()

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/recipes/page.mdx

Provides two ways to coerce numbers: a transform using parseInt piped through z.number() to validate the result, and Zod's built-in z.coerce.number() as an alternative. All environment variables are strings, so start with a string validator before applying transforms.

```ts
export const env = createEnv({
  server: {
    SOME_NUMBER: z
      .string()
      // transform to number
      .transform((s) => parseInt(s, 10))
      // make sure transform worked
      .pipe(z.number()),

    // Alternatively, use Zod's default primitives coercion
    // https://zod.dev/?id=coercion-for-primitives
    ZOD_NUMBER_COERCION: z.coerce.number(),
  },
  // ...
});
```

--------------------------------

### Import and use the env object in server and client code

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

Import the `env` object from `~/env` to access validated environment variables with type-safety and auto-completion. The first example shows server-side usage in an API route, accessing `env.OPEN_AI_API_KEY`. The second shows client-side usage in a React component, accessing `env.PUBLIC_PUBLISHABLE_KEY`; the import path is the same on both sides.

```ts
import { env } from "~/env"; // On server

export const GET = async () => {
  // do fancy ai stuff
  const magic = await fetch("...", {
    headers: { Authorization: env.OPEN_AI_API_KEY },
  });
  // ...
};
```

```tsx
import { env } from "~/env"; // On client - same import!

export const SomeComponent = () => {
  return (
    <SomeProvider publishableKey={env.PUBLIC_PUBLISHABLE_KEY}>
      {/* ... */}
    </SomeProvider>
  );
};
```

--------------------------------

### Overriding the default error handler

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

Override onValidationError to handle schema validation failures and onInvalidAccess to handle server variable access on the client. The example logs validation issues and throws errors for both cases.

```TypeScript
import { createEnv } from "@t3-oss/env-core";

export const env = createEnv({
  // ...
  // Called when the schema validation fails.
  onValidationError: (issues: StandardSchemaV1.Issue[]) => {
    console.error(
      "❌ Invalid environment variables:",
      issues
    );
    throw new Error("Invalid environment variables");
  },
  // Called when server variables are accessed on the client.
  onInvalidAccess: (variable: string) => {
    throw new Error(
      "❌ Attempted to access a server-side environment variable on the client"
    );
  },
});
```

--------------------------------

### Use env schema in a Next.js route handler

Source: https://github.com/t3-oss/t3-env/blob/main/README.md

Use the env object in your application to access environment variables with autocompletion and type inference. This example shows a Next.js route handler importing env from the schema file.

```ts
// src/app/hello/route.ts
import { env } from "../env.mjs";

export const GET = (req: Request) => {
  const DATABASE_URL = env.DATABASE_URL;
  // use it...
};
```

--------------------------------

### Create custom preset

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

A preset is just an env object. Create your own preset in a shared package and extend it in your app.

```ts
// packages/auth/env.ts
import { createEnv } from "@t3-oss/env-core";
export const env = createEnv({
  // ...
});

// apps/web/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { env as authEnv } from "@repo/auth/env";

export const env = createEnv({
  // ...
  extends: [authEnv],
});
```

--------------------------------

### Checkout a feature branch

Source: https://github.com/t3-oss/t3-env/blob/main/README.md

Create and switch to a feature branch for your changes.

```sh
git checkout <branch_name>
```

--------------------------------

### Use env in server endpoint

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

Import env from '~~/env' on the server and use type-safe variables like env.OPEN_AI_API_KEY.

```ts
import { env } from "~~/env"; // On server

export default defineEventHandler(() => {
  // do fancy ai stuff
  const magic = await fetch("...", {
    headers: { Authorization: env.OPEN_AI_API_KEY },
  });
  // ...
});
```

--------------------------------

### Configure next.config.ts for standalone output with transpilePackages

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

Required in next.config.ts when using the standalone output. Add @t3-oss/env-nextjs and @t3-oss/env-core to transpilePackages.

```ts
import type { NextConfig } from "next"

const nextConfig: NextConfig = {
  output: "standalone",
  // Add the packages in transpilePackages
  transpilePackages: ["@t3-oss/env-nextjs", "@t3-oss/env-core"],
}

export default nextConfig
```

--------------------------------

### Create env schema with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/core/page.mdx

Defines server and client schemas with a clientPrefix. Uses runtimeEnv and emptyStringAsUndefined. Remove client properties for server-only.

```ts
import { createEnv } from "@t3-oss/env-core";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },

  /**
   * The prefix that client-side variables must have. This is enforced both at
   * a type-level and at runtime.
   */
  clientPrefix: "PUBLIC_",

  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },

  /**
   * What object holds the environment variables at runtime. This is usually
   * `process.env` or `import.meta.env`.
   */
  runtimeEnv: process.env,

  /**
   * By default, this library will feed the environment variables directly to
   * the Zod validator.
   *
   * This means that if you have an empty string for a value that is supposed
   * to be a number (e.g. `PORT=` in a ".env" file), Zod will incorrectly flag
   * it as a type mismatch violation. Additionally, if you have an empty string
   * for a value that is supposed to be a string with a default value (e.g.
   * `DOMAIN=` in an ".env" file), the default value will never be applied.
   *
   * In order to solve these issues, we recommend that all new projects
   * explicitly specify this option as true.
   */
  emptyStringAsUndefined: true,
});
```

--------------------------------

### Create typed environment with createEnv and Zod

Source: https://github.com/t3-oss/t3-env/blob/main/packages/core/README.md

Defines server and client environment variables with Zod schemas. Client variables must be prefixed with PUBLIC_. Uses process.env as runtimeEnv.

```ts
// src/env.ts
import { createEnv } from "@t3-oss/env-core";
import * as z from "zod";

export const env = createEnv({
  /*
   * Serverside Environment variables, not available on the client.
   * Will throw if you access these variables on the client.
   */
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  /*
   * Environment variables available on the client (and server).
   *
   * 💡 You'll get type errors if these are not prefixed with PUBLIC_.
   */
  clientPrefix: 'PUBLIC_',
  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  /*
   * Specify what values should be validated by your schemas above.
   */
  runtimeEnv: process.env,
});
```

--------------------------------

### Create env schema in src/env.ts with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

Create a single-file schema for server and client environment variables. runtimeEnv is strict by default; missing keys cause a type-error. For Next.js >= 13.4.4, use experimental__runtimeEnv with only client variables.

```ts
import { createEnv } from "@t3-oss/env-nextjs";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
  // If you're using Next.js < 13.4.4, you'll need to specify the runtimeEnv manually
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
    NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
  },
  // For Next.js >= 13.4.4, you only need to destructure client variables:
  // experimental__runtimeEnv: {
  //   NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
  // }
});
```

--------------------------------

### Create env schema with createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

Define server and client schemas in a single env.ts file. Uses Zod, but any Standard Schema validator works. The client schema must use NUXT_PUBLIC_ prefix.

```ts
import { createEnv } from "@t3-oss/env-nuxt";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  client: {
    NUXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
});
```

--------------------------------

### Validate env on build in next.config.js with jiti (Next.js < 16)

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

For Next.js versions before 16, use jiti to import the env file in next.config.js and validate environment variables at build time.

```js
import { createJiti } from 'jiti';

const jiti = createJiti(import.meta.url);

// Import env here to validate during build. Using jiti@^1 we can import .ts files :)
await jiti.import('./app/env');

/** @type {import('next').NextConfig} */
export default {
  /** ... */
};
```

--------------------------------

### Create environment schema with createEnv and Zod

Source: https://github.com/t3-oss/t3-env/blob/main/packages/nextjs/README.md

Defines server and client environment variables with Zod schemas. Server variables are not available on the client and will throw if accessed there. Client variables must be prefixed with NEXT_PUBLIC_ to avoid type errors. For Next.js < 13.4.4, specify runtimeEnv manually; for >= 13.4.4, use experimental__runtimeEnv for client-side variables.

```ts
// src/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import * as z from "zod";

export const env = createEnv({
  /*
   * Serverside Environment variables, not available on the client.
   * Will throw if you access these variables on the client.
   */
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  /*
   * Environment variables available on the client (and server).
   *
   * 💡 You'll get type errors if these are not prefixed with NEXT_PUBLIC_.
   */
  client: {
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  /*
   * Specify what values should be validated by your schemas above.
   *
   * If you're using Next.js < 13.4.4, you'll need to specify the runtimeEnv manually
   * For Next.js >= 13.4.4, you can use the experimental__runtimeEnv option and
   * only specify client-side variables.
   */
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
    NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
  },
  // experimental__runtimeEnv: {
  //   NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
  // }
});
```

--------------------------------

### Use env in Vue component

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

Import env from '~~/env' on the client with the same import. Use env.NUXT_PUBLIC_GREETING in the template.

```vue
<script setup lang="ts">
import { env } from "~~/env"; // On client - same import!
</script>
<template>
  <div>Client says {{ env.NUXT_PUBLIC_GREETING }}!</div>
  <a href="/api/hello">See what the server has to say!</a>
</template>
```

--------------------------------

### Split env schemas into src/env/server.ts and src/env/client.ts

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

Split server and client schemas into separate files to avoid shipping server variable names to the client. The server file uses experimental__runtimeEnv: process.env for Next.js >= 13.4.4; the client file uses runtimeEnv with the client key.

```ts
import { createEnv } from "@t3-oss/env-nextjs";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  // If you're using Next.js < 13.4.4, you'll need to specify the runtimeEnv manually
  // runtimeEnv: {
  //   DATABASE_URL: process.env.DATABASE_URL,
  //   OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
  // },
  // For Next.js >= 13.4.4, you can just reference process.env:
  experimental__runtimeEnv: process.env
});
```

```ts
import { createEnv } from "@t3-oss/env-nextjs";
import * as z from "zod";

export const env = createEnv({
  client: {
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  runtimeEnv: {
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
  },
});
```

--------------------------------

### Use createFinalSchema to refine or transform environment variables

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

Use the createFinalSchema option to further refine or transform environment variables. The function receives the shape and isServer flag, and can return a transformed object or add a custom issue and return z.NEVER to fail validation.

```ts
import { createEnv } from "@t3-oss/env-core";
import * as z from "zod";

export const env = createEnv({
  server: {
    SKIP_AUTH: z.boolean().optional(),
    EMAIL: z.string().email().optional(),
    PASSWORD: z.string().min(1).optional(),
  },
  // ...
  createFinalSchema: (shape, isServer) =>
    z.object(shape).transform((env, ctx) => {
      if (env.SKIP_AUTH || !isServer) return { SKIP_AUTH: true } as const;
      if (!env.EMAIL || !env.PASSWORD) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: "EMAIL and PASSWORD are required if SKIP_AUTH is false",
        });
        return z.NEVER;
      }
      return {
        EMAIL: env.EMAIL,
        PASSWORD: env.PASSWORD,
      };
    }),
});
```

--------------------------------

### Import env in nuxt.config.ts for build-time validation

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

Import the env file in nuxt.config.ts to validate environment variables at build time. The import is on line 1.

```ts
import "./env";

export default defineNuxtConfig({
  // ...
});
```

--------------------------------

### Configure Storybook env with t3-env client env

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/recipes/page.mdx

In .storybook/main.ts, spread the t3-env client environment into Storybook's env configuration so that Storybook's bundler is aware of the environment variables. This ensures all environment variables are available for Storybook.

```ts
// .storybook/main.ts

import { env as t3Env } from "~/env/client.mjs";

const config: StorybookConfig = {
  // other Storybook config...
  env: (config1) => ({
    ...config1,
    ...t3Env,
  })
};

export default config;
```

--------------------------------

### Define environment schemas with createEnv in src/env.ts

Source: https://github.com/t3-oss/t3-env/blob/main/packages/nuxt/README.md

Create a typed environment object using createEnv from @t3-oss/env-nuxt. Server variables are not available on the client and will throw if accessed there. Client variables must be prefixed with NUXT_PUBLIC_ to avoid type errors.

```ts
// src/env.ts
import { createEnv } from "@t3-oss/env-nuxt";
import * as z from "zod";

export const env = createEnv({
  /*
   * Serverside Environment variables, not available on the client.
   * Will throw if you access these variables on the client.
   */
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  /*
   * Environment variables available on the client (and server).
   *
   * 💡 You'll get type errors if these are not prefixed with NUXT_PUBLIC_.
   */
  client: {
    NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
});
```

--------------------------------

### Clone the t3-env repository

Source: https://github.com/t3-oss/t3-env/blob/main/README.md

Clone the t3-env repository from GitHub.

```sh
git clone https://github.com/t3-oss/t3-env.git
```

--------------------------------

### Split schemas into server and client files

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nuxt/page.mdx

If variable names are sensitive, split schemas into separate files to avoid shipping server schema names to the client. This warning is from the callout.

```ts
import { createEnv } from "@t3-oss/env-nuxt";
import * as z from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
});
```

```ts
import { createEnv } from "@t3-oss/env-nuxt";
import * as z from "zod";

export const env = createEnv({
  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
});
```

--------------------------------

### Validate env on build in next.config.ts (Next.js 16+)

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/nextjs/page.mdx

For Next.js 16+, import the env file directly in next.config.ts to validate environment variables at build time.

```ts
import "./app/env";

/** @type {import('next').NextConfig} */
const nextConfig: NextConfig = {
  /** ... */
};

export default nextConfig;
```

--------------------------------

### Use runtimeEnvStrict in createEnv

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/core/page.mdx

Use runtimeEnvStrict to ensure all environment variables are explicitly accessed in the runtime. Missing any variable in runtimeEnvStrict results in a type error.

```ts
import { createEnv } from "@t3-oss/env-core";

export const env = createEnv({
  clientPrefix: "PUBLIC_",
  server: {
    DATABASE_URL: z.url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  client: {
    PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
  /**
   * Makes sure you explicitly access **all** environment variables
   * from `server` and `client` in your `runtimeEnv`.
   */
  runtimeEnvStrict: {
    DATABASE_URL: process.env.DATABASE_URL,
    OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
    PUBLIC_PUBLISHABLE_KEY: process.env.PUBLIC_PUBLISHABLE_KEY,
  },
});
```

--------------------------------

### Skipping validation with skipValidation

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

Set skipValidation to true to skip validation for environment variables and extended presets. Skipping validation is not encouraged and will lead to types and runtime values being out of sync. It is useful during linting or when building with Docker without all environment variables present.

```TypeScript
import { createEnv } from "@t3-oss/env-core";

export const env = createEnv({
  // ...
  // Tell the library to skip validation if condition is true.
  skipValidation: false,
});
```

--------------------------------

### Coerce booleans from strings with Zod transforms

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/recipes/page.mdx

Shows two approaches for boolean coercion: a transform that treats any string other than 'false' or '0' as true, and a refine+transform that only accepts 'true' or 'false'. Avoid Zod's default primitives coercion for booleans because every string coerces to true; consider z.stringbool() in Zod v4.

```ts
export const env = createEnv({
  server: {
    COERCED_BOOLEAN: z
      .string()
      // transform to boolean using preferred coercion logic
      .transform((s) => s !== "false" && s !== "0"),

    ONLY_BOOLEAN: z
      .string()
      // only allow "true" or "false"
      .refine((s) => s === "true" || s === "false")
      // transform to boolean
      .transform((s) => s === "true"),
  },
  // ...
});
```

--------------------------------

### Set emptyStringAsUndefined to treat empty strings as undefined

Source: https://github.com/t3-oss/t3-env/blob/main/docs/src/app/docs/customization/page.mdx

By default, empty strings are passed directly to Zod, causing type mismatches or preventing defaults. Set emptyStringAsUndefined to true to treat them as undefined.

```ts
import { createEnv } from "@t3-oss/env-core";

export const env = createEnv({
  // ...
  // Treat empty strings as undefined.
  emptyStringAsUndefined: false,
});
```
Tokens:
Raw