T3 Env

https://env.t3.gg/docs
Admin
T3 Env is a library that provides a simple and robust way to define and validate environment...
Tokens:7,363
Snippets:91
Trust Score:8.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Zod

Source: https://env.t3.gg/docs/standard-schema

Install the Zod library to use it with T3 Env.

```bash
npm install zod
```

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

### Install Valibot

Source: https://env.t3.gg/docs/standard-schema

Install the Valibot library to use it with T3 Env.

```bash
npm install valibot
```

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

### Install ArkType

Source: https://env.t3.gg/docs/standard-schema

Install the ArkType library to use it with T3 Env.

```bash
npm install arktype
```

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

### Install Nuxt T3 Env Dependencies

Source: https://env.t3.gg/docs/nuxt

Install the necessary packages for T3 Env integration with Nuxt using pnpm or deno.

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

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

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

### Install T3 Env Core Package

Source: https://env.t3.gg/docs/core

Install the core package and Zod using npm or deno. This is the first step to using the T3 Env core package in your project.

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

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

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

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

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

### Advanced Schema Transformation with createFinalSchema

Source: https://env.t3.gg/docs/customization

Refine and transform environment variables using `createFinalSchema`. This example validates `EMAIL` and `PASSWORD` based on `SKIP_AUTH` status, adding custom validation logic.

```typescript
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,
      };
    }),
});
```

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

### Defining Environment Variables with Schema Validation

Source: https://env.t3.gg/docs/core

Configure environment variables using `createEnv` from `@t3-oss/env-core`. This example demonstrates defining server and client variables, along with strict runtime checking.

```typescript
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,
  },
});
```

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

### Install Next.js Dependencies

Source: https://env.t3.gg/docs/nextjs

Install the required dependencies for Next.js environment variable management. Ensure your TypeScript version is 5.0.0 or higher and your tsconfig uses a module resolution that can read package.json#exports (Bundler is recommended).

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

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

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

### Creating Custom Environment Variable Schemas

Source: https://env.t3.gg/docs/customization

Define custom environment variable schemas by extending existing configurations. This example shows how to import and use environment variables from an authentication package within a web application.

```typescript
// 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],
});
```

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

### Create Nuxt Environment Schema

Source: https://env.t3.gg/docs/nuxt

Define your environment variable schemas for both server and client using Zod. This example shows a combined schema.

```typescript
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),
  },
});
```

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

### Basic Zod Environment Variable Validation

Source: https://env.t3.gg/docs/introduction

Define and parse environment variables using Zod for type safety and autocompletion. This basic setup validates against a predefined schema.

```typescript
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> {}
  }
}
```

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

### Create Unified Server and Client Environment Schema

Source: https://env.t3.gg/docs/core

Define environment variables for both server and client in a single file. Ensure client variables are prefixed with `PUBLIC_`. Set `emptyStringAsUndefined` to true to handle empty strings correctly.

```typescript
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 Combined Server and Client Environment Schema

Source: https://env.t3.gg/docs/nextjs

Define both server and client environment variables with Zod schemas in a single file. Ensure all keys are explicitly defined in runtimeEnv for Next.js versions prior to 13.4.4.

```typescript
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,
  // }
});
```

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

### Configure T3 Env with Zod

Source: https://env.t3.gg/docs/standard-schema

Set up environment variables using T3 Env with Zod for validation. Includes server and client variables.

```typescript
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,
});
```

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

### Next.js < 16 next.config.js

Source: https://env.t3.gg/docs/nextjs

For versions older than Next.js 16, use jiti to import environment variables in next.config.js during the build process.

```javascript
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 {
  /** ... */
};
```

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

### Configure T3 Env with Valibot Presets

Source: https://env.t3.gg/docs/standard-schema

Use T3 Env with Valibot presets, like Vercel, for simplified environment variable configuration.

```typescript
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,
});
```

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

### Create Client-Only Environment Schema

Source: https://env.t3.gg/docs/core

Define environment variables intended for client-side use. These variables must be prefixed according to `clientPrefix` and will be validated at runtime.

```typescript
import { createEnv } from "@t3-oss/env-core";
import * as z from "zod";
 
export const env = createEnv({
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  runtimeEnv: process.env,
});
```

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

### Configure T3 Env with Valibot

Source: https://env.t3.gg/docs/standard-schema

Set up environment variables using T3 Env with Valibot for validation. Handles URL and number coercion.

```typescript
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,
});
```

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

### Define Server Context

Source: https://env.t3.gg/docs/customization

Set `isServer` to `true` when running in a server environment. This is typically determined by checking for the absence of `window`.

```typescript
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",
});
```

```typescript
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",
});
```

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

### Configure T3 Env with ArkType

Source: https://env.t3.gg/docs/standard-schema

Set up environment variables using T3 Env with ArkType for validation. Uses type strings for schema definition.

```typescript
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,
});
```

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

### Configure Next.js Standalone Output

Source: https://env.t3.gg/docs/nextjs

When using the `standalone` output in `next.config.ts`, ensure that `@t3-oss/env-nextjs` and `@t3-oss/env-core` are included in the `transpilePackages` option.

```typescript
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
```

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

### Using Environment Variables in Client Component

Source: https://env.t3.gg/docs/nextjs

Import and use public environment variables in client-side components, leveraging the same import path for consistency.

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

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

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

### Next.js 16+ next.config.ts

Source: https://env.t3.gg/docs/nextjs

Configure environment variables for Next.js version 16 and above by importing them in next.config.ts.

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

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

export default nextConfig;
```

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

### Create Separate Server Environment Schema

Source: https://env.t3.gg/docs/nextjs

Define only server environment variables in a dedicated file. For Next.js versions 13.4.4 and above, you can reference `process.env` directly using `experimental__runtimeEnv`.

```typescript
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
});
```

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

### Split Nuxt Environment Schemas

Source: https://env.t3.gg/docs/nuxt

Separate server and client environment variable schemas into different files to prevent sensitive server variables from being exposed to the client.

```typescript
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),
  },
});
```

```typescript
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),
  },
});
```

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

### Create Separate Client Environment Schema

Source: https://env.t3.gg/docs/nextjs

Define only client environment variables in a dedicated file. This ensures that server-side validation schemas are not exposed to the client.

```typescript
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,
  },
});
```

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

### Extend Environment Presets

Source: https://env.t3.gg/docs/customization

Use the `extends` property to include environment variables from presets, such as system variables for deployment providers or shared variables in a monorepo.

```typescript
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
```

```typescript
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
```

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

### Integrate t3-env with Storybook

Source: https://env.t3.gg/docs/recipes

Configure Storybook's `main.ts` to include environment variables from `t3-env` by merging them into the Storybook config's `env` property.

```typescript
// .storybook/main.ts
 
import { env as t3Env } from "~/env/client.mjs";
 
const config: StorybookConfig = {
  // other Storybook config...
  env: (config1) => ({
    ...config1,
    ...t3Env,
  })
};
 
export default config;
```

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

### Create Server-Only Environment Schema

Source: https://env.t3.gg/docs/core

Define environment variables exclusively for the server. This is useful for sensitive variables that should never be exposed to the client.

```typescript
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),
  },
  runtimeEnv: process.env,
});
```

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

### Using Environment Variables in Server API Endpoint

Source: https://env.t3.gg/docs/nextjs

Import and utilize environment variables within server-side API endpoints for secure access to sensitive information like API keys.

```typescript
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 },
  });
  // ...
};
```

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

### Use Environment Variables on Nuxt Client

Source: https://env.t3.gg/docs/nuxt

Import the `env` object in your client-side components to access validated public environment variables, enabling type-safe access to frontend configurations.

```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>
```

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

### Validate Schema on Nuxt Build

Source: https://env.t3.gg/docs/nuxt

Import your environment schema file into `nuxt.config.ts` to ensure environment variables are validated at build time.

```typescript
import "./env";

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

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

### Use Environment Variables on Nuxt Server

Source: https://env.t3.gg/docs/nuxt

Import the `env` object in your server-side files to access validated environment variables, such as API keys for external services.

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

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

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

### Skip Environment Variable Validation

Source: https://env.t3.gg/docs/customization

Set `skipValidation` to `true` to opt out of validation. This is not recommended for production use.

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

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

```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 with t3-env and Zod

Source: https://env.t3.gg/docs/recipes

Use Zod's `transform` to coerce strings to booleans, handling custom logic for 'false' and '0'. Alternatively, use `refine` to strictly allow 'true' or 'false' before transforming.

```typescript
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"),
  },
  // ...
});
```

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

### Treat Empty Strings as Undefined

Source: https://env.t3.gg/docs/customization

Set `emptyStringAsUndefined` to `true` to ensure empty strings are treated as `undefined`. This prevents Zod type mismatches and ensures default values are applied.

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

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

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

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

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

### Override Default Error Handler

Source: https://env.t3.gg/docs/customization

Customize `onValidationError` and `onInvalidAccess` to handle schema validation failures and invalid server-side variable access.

```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"
    );
  },
});
```

```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"
    );
  },
});
```

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

### Coerce Numbers with t3-env and Zod

Source: https://env.t3.gg/docs/recipes

Transform strings to numbers using `parseInt` and then validate with `z.number()`. Zod's `z.coerce.number()` provides a more direct coercion method.

```typescript
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(),
  },
  // ...
});
```
Tokens:
Raw