Переменные среды

Create T3 App использует собственный пакет @t3-oss/env-nextjs↗ вместе с Zod↗ для валидации переменных среды во время выполнения и во время сборки, предоставляя простую логику в файле src/env.js:

env.js

TLDR; Если вы хотите добавить новую переменную среды, вам следует добавить валидатор в src/env.js, а затем пару ключ-значение в .env.

env.js

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

export const env = createEnv({
  server: {
    NODE_ENV: z.enum(["development", "test", "production"]),
  },
  client: {
    // NEXT_PUBLIC_CLIENTVAR: z.string(),
  },
  runtimeEnv: {
    NODE_ENV: process.env.NODE_ENV,
  },
});

T3 Env использует createEnv, который отвечает за создание схемы и будет включать главную логику валидации для клиентских и серверных переменных среды.

ℹ️

Для получения дополнительной информации о том, как createEnv работает изнутри, посмотрите документацию T3 Env↗ (EN)

Использование переменных среды

Когда вы хотите использовать переменные среды, вы можете импортировать их из env.js и использовать их как вы обычно использовали бы. Если вы импортируете этот файл на стороне клиента и попробуете получить серверную переменную, вы получите ошибку выполнения:

pages/api/hello.ts

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

// `env` полностью типобезопасно и предоставляет автокомплит
const dbUrl = env.DATABASE_URL;

pages/index.tsx

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

// ❌ Это даст ошибку
const dbUrl = env.DATABASE_URL;

// ✅ Тут все ОК
const wsKey = env.NEXT_PUBLIC_WS_KEY;

.env.example

Из-за того, что файл .env по умолчанию не добавляется в систему контроля версий, мы также добавили файл .env.example, в котором вы можете по желанию сохранить копию вашего файла .env с удаленными секретами. Это необязательно, но мы рекомендуем держать пример в актуальном состоянии, чтобы сделать процесс настройки среды для новых участников проекта как можно проще.

Некоторые фреймворки и инструменты сборки, такие как Next.js, предлагают хранить секреты в файле .env.local и коммитить файлы .env в ваш проект. Это не рекомендуется, поскольку это может облегчить случайный коммит секретов в ваш проект. Вместо этого мы рекомендуем хранить секреты в .env, держать ваш файл .env в .gitignore и коммитить только файлы .env.example в ваш проект.

Добавление переменных среды

Для того, чтобы убедиться, что ваша сборка никогда не завершится без переменных среды, которые проект требует, вам нужно добавить новые переменные среды в двух местах:

📄 .env: Введите переменную среды, как обычно делаете в файле .env, т.е. KEY=VALUE

📄 env.js: Добавьте соответствующую логику валидации для переменных среды, определив для каждой из них Zod схему внутри createEnv, например KEY: z.string(). Кроме этого, убедитесь в том, что вы деструкткрировали их в опции runtimeEnv, например KEY: process.env.KEY.

ℹ️

Зачем нужно деструктурировать переменные среды внутри runtimeEnv? Это связано с тем, как Next.js собирает переменные среды в некоторых рантаймах. Деструктурируя их вручную, мы гарантируем, что эти переменные не будут убраны из финальной сборки.

Опционально, вы также можете обновлять файл .env.example:

📄 .env.example: Введите вашу переменную среды, но убедитесь, что не включаете значение, если оно является секретным, т.е. KEY=VALUE или KEY=

Пример

Я хочу добавить мой Twitter API токен в качестве переменной среды на стороне сервера

Добавьте переменную среды в .env:

TWITTER_API_TOKEN=1234567890

Добавьте переменную среды в env.js:

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

export const env = createEnv({
  server: {
    TWITTER_API_TOKEN: z.string(),
  },
  // ...
  runtimeEnv: {
    // ...
    TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
  },
});

Опционально: Добавьте переменную среды в .env.example, но не включайте токен в runtimeEnv

TWITTER_API_TOKEN=