Немного предыстории

Если вы какое-то время занимаетесь программированием, вы знаете важность переменных среды и роль, которую они играют, а также боль, связанную с выяснением ошибки, которая возникла только потому, что чертова переменная env не была установлена ​​в вашем проекте , ржу не могу!

Ранее в этом году я работал в продуктовом стартапе в качестве стажера Full stack-разработчика. По мере роста проекта росло и количество переменных env. И все работали над отдельными функциями в разных ветках, поэтому мы понятия не имели, ввел ли кто-то в свою ветку какую-то новую переменную env, которая позже была объединена с основной веткой. Это создавало проблемы, когда я пытался развернуть свои ветки, я знал, что в проект была добавлена ​​новая переменная окружения.

Затем я познакомился со стеком T3, и у него было блестящее решение для добавления безопасности типов в переменные env. Я даже не знал, что такое решение вообще существует. Всегда приятно узнавать что-то новое, когда меньше всего этого ожидаешь. Стек T3 использует пакет zod и @t3-oss/env-nextjs для обеспечения безопасности типов в ваших приложениях, что мне очень понравилось. После этого я взял на себя обязательство всегда обеспечивать типобезопасность переменных env, несмотря ни на что.

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

Вот как вы можете добавить его в свой проект. Это довольно просто.

Что такое зод?

Zod — это легкая, быстрая библиотека объявления и проверки схемы. Схема может быть чем угодно: от простой строки и числа до сложного типа объекта.

Основное использование

import {z} from 'zod';

const myBoolean = z.boolean();

myBoolean.parse('true'); // throws error
myBoolean.parse(true) // valid

Создание схемы вложенных объектов

import { z } from 'zod';

const userSchema = z.object({
    name: z.string(),
    age: z.number(),
    address: z.object({
        house_no: z.string(),
        locality: z.string(),
        city: z.string(),
        state: z.string(),
    })
});

Вы можете создать простую схему объекта или создать схему вложенных объектов.

Что такое t3-oss/env-nextjs?

Это просто пакет, который поможет нам добавить безопасность типов в переменные окружения

Давайте создадим типобезопасные переменные env.

Создайте файл env.js в корне вашего проекта.

import {createEnv} from "@t3-oss/env-nextjs"; import {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: {
    DB_URI: z.string().url(),
  },
  /*
   * 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),
  },
  /*
   * Due to how Next.js bundles environment variables on Edge and Client,
   * we need to manually destructure them to make sure all are included in bundle.
   *
   * You'll get type errors if not all variables from `server` & `client` are included here.
   */
  runtimeEnv: {
    DB_URI: process.env.DATABASE_URL,
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:
      process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
  },
});

Использование

import {env} from '@/env';

const CLERK_PUBLISHABLE_KEY = env.NEXT_PUBLISHABLE_KEY;

Если вы наведете курсор на NEXT_PUBLISHABLE_KEY, вы увидите, что это значение напечатано как строка, это означает, что наши переменные env теперь набраны.

Мы добавили типобезопасные переменные окружения, но они не будут выполняться при каждой сборке. нам нужно импортировать наш вновь созданный файл в наш файл next.config.js. Для этого вы можете использовать пакет unjs/jiti.

Сначала установите пакет jiti из npm.

import { fileURLToPath } from "node:url";
import createJiti from "jiti";
const jiti = createJiti(fileURLToPath(import.meta.url));

jiti("./app/env");

При работе с import.meta.url он предоставляет URL-адрес файла, с которым вы сейчас работаете. Однако он включает префикс file:///, который может вам не понадобиться. Чтобы удалить этот префикс, вы можете использовать функцию fileURLToPath из модуля node:url.

Например:

import {fileURLToPath} from 'node:url';

// Convert the file URL to a path
const filename = fileURLToPath(import.meta.url);

Теперь, если у вас нет необходимых переменных env, вы увидите такую ​​ошибку -

Как добавить безопасность типов к переменным env в проектах Node.js?

import dotenv from "dotenv";
import { z } from "zod";

dotenv.config();

const schema = z.object({
  MONGO_URI: z.string(),
  PORT: z.coerce.number(),
  JWT_SECRET: z.string(),
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
});

const parsed = schema.safeParse(process.env);

if (!parsed.success) {
  console.error(
    "❌ Invalid environment variables:",
    JSON.stringify(parsed.error.format(), null, 4)
  );
  process.exit(1);
}

export default parsed.data;

В проектах Node.js мы будем просто создавать схему zod и анализировать ее с помощью нашего процесса.env, чтобы проверить, установлены ли все переменные env или нет.

Использование

import express from "express";
import env from "./env";

const app = express();
const PORT = env.PORT || 5000; // PORT is type safe here....

app.listen(PORT, () => {
console.log("Connected to server on PORT ${PORT}");
connectDB();
});

Вот как вы добавляете безопасность типов в переменные env. Надеюсь, вы узнали что-то новое из этого урока.

Удачного программирования!! ?