약간의 배경

한동안 코딩을 해보신 분이라면 환경 변수의 중요성과 그 역할이 무엇인지 아실 것입니다. 또한 프로젝트에 환경 변수가 설정되지 않았기 때문에 발생하는 버그를 알아내야 하는 어려움도 아실 것입니다. , ㅋㅋㅋ!

올해 초 저는 제품 기반 스타트업에서 풀스택 개발자 인턴으로 일했습니다. 프로젝트가 성장함에 따라 환경 변수의 수도 늘어났습니다. 그리고 모두가 별도의 브랜치에서 별도의 기능을 작업하고 있었기 때문에 누군가가 나중에 메인 브랜치에 병합된 새로운 환경 변수를 브랜치에 도입했는지 전혀 알 수 없었습니다. 이로 인해 브랜치를 배포하려고 할 때 문제가 발생했습니다. 프로젝트에 새 환경 변수가 추가되었다는 아이디어를 알고 있었습니다.

그런 다음 나중에 T3 스택을 소개받았고 환경 변수에 유형 안전성을 추가하는 훌륭한 솔루션이 있었습니다. 나는 그런 해결책이 존재하는지조차 몰랐습니다. 전혀 기대하지 않았을 때 새로운 것을 배우는 것은 언제나 기분 좋은 일입니다. T3 스택은 zod 및 @t3-oss/env-nextjs 패키지를 사용하여 제가 매우 좋아하는 애플리케이션에 유형 안전성을 추가합니다. 그 후, 나는 무슨 일이 있어도 내 환경 변수를 항상 형식으로부터 안전하게 보호하기로 약속했습니다.

새 프로젝트를 시작하거나 이미 팀으로 작업 중이라면 환경에 유형 안전성을 추가하는 것이 좋습니다. 이것만 추가하면 코드베이스의 문제를 파악하는 데 드는 노력이 줄어듭니다.

프로젝트에 추가하는 방법은 다음과 같습니다. 상당히 간단합니다.

조드란 무엇인가?

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.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 위에 커서를 올리면 해당 값이 문자열로 입력된 것을 볼 수 있습니다. 이는 환경 변수가 이제 입력되었음을 의미합니다.

유형 안전 환경 변수를 추가했지만 빌드할 때마다 실행되지는 않습니다. 새로 생성된 파일을 next.config.js 파일로 가져와야 합니다. 이를 위해 unjs/jiti 패키지를 사용할 수 있습니다.

먼저 npm에서 jiti 패키지를 설치합니다.

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

jiti("./app/env");

import.meta.url로 작업할 때 현재 작업 중인 파일의 URL을 제공합니다. 그러나 여기에는 원하지 않을 수도 있는 file:/// 접두사가 포함되어 있습니다. 해당 접두사를 제거하려면 node:url 모듈에서 fileURLToPath 함수를 사용할 수 있습니다.

예를 들어:

import {fileURLToPath} from 'node:url';

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

이제 필수 환경 변수가 없으면 다음과 같은 오류가 표시됩니다.

Node.js 프로젝트의 env 변수에 유형 안전성을 추가하는 방법은 무엇입니까?

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 프로젝트에서는 모든 env 변수가 설정되었는지 여부를 확인하기 위해 단순히 zod 스키마를 생성하고 이를 process.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();
});

이것이 환경 변수에 유형 안전성을 추가하는 방법입니다. 이 튜토리얼에서 새로운 것을 배웠기를 바랍니다.

즐거운 코딩하세요!! ?