본문 바로가기
JavaScript & TypeScript

Node.js와 TypeScript에서 환경 변수 관리

by 대박플머 2024. 12. 17.

TypeScript를 사용하는 Node.js 프로젝트에서 환경 변수를 관리하는 것은 JavaScript와 유사하지만, 타입 안전성을 확보하는 것이 추가적인 고려 사항입니다. 여기서는 TypeScript 환경에서 환경 변수를 어떻게 관리하고, 이를 안전하게 사용하는지에 대해 살펴보겠습니다.

1. TypeScript 프로젝트에서 환경 변수 사용하기

TypeScript에서 process.env를 사용할 때 기본적으로 모든 환경 변수가 string | undefined 타입을 가집니다. 이는 타입 안정성을 보장하지 않으므로, 이를 명시적으로 정의하는 것이 중요합니다.

// app.ts
require("dotenv").config();

const port: number = parseInt(process.env.PORT || "3000", 10);
console.log(`Server is running on port ${port}`);

위 코드에서는 process.env.PORT가 문자열로 반환되기 때문에 parseInt를 사용하여 숫자로 변환합니다.

2. 환경 변수 타입 정의하기

환경 변수를 사용할 때 TypeScript의 장점을 최대한 활용하려면, 필요한 환경 변수를 정의하고 타입을 지정해주는 것이 좋습니다. 이를 위해 env.d.ts 파일을 생성하고 인터페이스를 정의할 수 있습니다.

1. 프로젝트 루트에 env.d.ts 파일 생성

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    PORT?: string;
    DB_HOST: string;
    DB_USER: string;
    DB_PASS: string;
  }
}

2. TypeScript 환경에서 위 파일을 인식할 수 있도록 설정

  • tsconfig.jsontypeRoots 옵션 추가:
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./env.d.ts"]
  }
}

이렇게 하면 TypeScript가 process.env를 참조할 때 타입을 검사하여 누락된 변수나 잘못된 타입을 경고해 줍니다.

3. 환경 변수의 안전한 사용 방법 (TypeScript 버전)

환경 변수를 TypeScript로 안전하게 사용하려면 아래 방법을 따릅니다.

필수 환경 변수 확인

// config.ts
import "dotenv/config";

const requiredEnv = ["DB_HOST", "DB_USER", "DB_PASS"] as const;

requiredEnv.forEach((variable) => {
  if (!process.env[variable]) {
    throw new Error(`Missing required environment variable: ${variable}`);
  }
});

export const config = {
  dbHost: process.env.DB_HOST as string,
  dbUser: process.env.DB_USER as string,
  dbPass: process.env.DB_PASS as string,
  port: parseInt(process.env.PORT || "3000", 10),
};

여기서 as string을 사용하여 process.env의 값이 존재한다는 것을 명시적으로 알릴 수 있습니다. 이렇게 하면 null이나 undefined로 인한 타입 오류를 방지할 수 있습니다.

4. .env 파일과 dotenv의 활용

.env 파일을 사용하여 환경 변수를 로드하는 방식은 JavaScript와 동일합니다. 다만, TypeScript의 import를 활용하여 조금 더 깔끔하게 관리할 수 있습니다.

// app.ts
import "dotenv/config";
import { config } from "./config";

console.log(`Database Host: ${config.dbHost}`);
console.log(`Server is running on port ${config.port}`);

5. cross-env를 통한 환경 변수 설정 (TypeScript)

TypeScript 프로젝트에서도 환경 변수를 설정할 때는 cross-env를 사용하여 다양한 플랫폼에서 호환성을 유지할 수 있습니다.

npx cross-env NODE_ENV=production ts-node app.ts

이렇게 하면 개발, 테스트, 프로덕션 환경별로 다양한 환경 변수를 설정하고 사용할 수 있습니다.

6. 환경 변수 관리 도구

TypeScript 환경에서도 JavaScript와 동일하게 다양한 도구를 활용할 수 있습니다.

  1. dotenv-safe: 환경 변수 타입을 엄격하게 관리할 수 있어 TypeScript 프로젝트에 더욱 적합합니다.
  2. import "dotenv-safe/config";
  3. ts-dotenv: TypeScript에 특화된 환경 변수 관리 라이브러리로, 환경 변수에 대한 타입 안전성을 자동으로 제공합니다.
npm install ts-dotenv

사용 예:

import { load } from "ts-dotenv";

const env = load({
  path: ".env",
  required: {
    PORT: "number",
    DB_HOST: "string",
    DB_USER: "string",
    DB_PASS: "string",
  },
});

console.log(`Database User: ${env.DB_USER}`);

ts-dotenv를 사용하면 .env 파일의 변수에 대한 타입을 강제할 수 있어 더욱 안전한 코드를 작성할 수 있습니다.

7. 환경 변수와 CI/CD에서의 사용

TypeScript 프로젝트의 환경 변수 관리도 CI/CD 파이프라인에서 중요한 역할을 합니다. 배포 환경에 따라 적절한 환경 변수를 로드하고 설정하려면 아래와 같은 방법을 사용합니다.

  • GitHub Actions:
name: Node.js CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: "14"

      - name: Install dependencies
        run: npm ci

      - name: Set environment variables
        run: echo "DB_HOST=$DB_HOST" >> $GITHUB_ENV
        env:
          DB_HOST: ${{ secrets.DB_HOST }}

8. 타입 안전성을 강화하는 방법

환경 변수를 타입 안전하게 관리하는 것은 TypeScript의 핵심 이점 중 하나입니다. as string이나 as number를 남발하지 않고, 환경 변수에 대한 명시적인 타입 체크를 통해 안전성을 강화하는 것이 좋습니다.

9. 환경 변수의 모범 사례 (TypeScript 버전)

  • 타입 선언을 통해 안전성 확보: env.d.ts와 같은 타입 선언 파일을 활용하여 환경 변수에 대한 타입을 정의합니다.
  • 필수 환경 변수 확인: dotenv-safets-dotenv와 같은 도구를 활용하여 애플리케이션 실행 시 모든 필수 변수가 설정되었는지 확인합니다.
  • 환경별 설정 파일 분리: config.development.ts, config.production.ts처럼 환경별로 다른 설정 파일을 작성하고, NODE_ENV 값에 따라 로드합니다.

결론

TypeScript를 사용하는 Node.js 프로젝트에서 환경 변수를 관리할 때는 타입 안전성을 보장하는 것이 중요합니다. dotenv를 통해 환경 변수를 로드하는 기본 방법부터 타입 선언을 통한 안정성 확보, ts-dotenv와 같은 도구를 활용한 고급 관리 방법까지 다뤘습니다. 이러한 방법들을 활용하여 프로젝트의 환경 변수 관리 전략을 구축하면, 더욱 안전하고 유지보수하기 쉬운 애플리케이션을 만들 수 있습니다.