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.json
에typeRoots
옵션 추가:
{
"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와 동일하게 다양한 도구를 활용할 수 있습니다.
- dotenv-safe: 환경 변수 타입을 엄격하게 관리할 수 있어 TypeScript 프로젝트에 더욱 적합합니다.
import "dotenv-safe/config";
- 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-safe
나ts-dotenv
와 같은 도구를 활용하여 애플리케이션 실행 시 모든 필수 변수가 설정되었는지 확인합니다. - 환경별 설정 파일 분리:
config.development.ts
,config.production.ts
처럼 환경별로 다른 설정 파일을 작성하고,NODE_ENV
값에 따라 로드합니다.
결론
TypeScript를 사용하는 Node.js 프로젝트에서 환경 변수를 관리할 때는 타입 안전성을 보장하는 것이 중요합니다. dotenv
를 통해 환경 변수를 로드하는 기본 방법부터 타입 선언을 통한 안정성 확보, ts-dotenv
와 같은 도구를 활용한 고급 관리 방법까지 다뤘습니다. 이러한 방법들을 활용하여 프로젝트의 환경 변수 관리 전략을 구축하면, 더욱 안전하고 유지보수하기 쉬운 애플리케이션을 만들 수 있습니다.
'JavaScript & TypeScript' 카테고리의 다른 글
TypeScript에서 Interface와 Type Alias의 차이점과 적절한 사용법 (0) | 2024.12.30 |
---|---|
Node.js와 Express에서 JSON 처리하기 (1) | 2024.12.10 |
Express.js에서 CORS 처리 방법 (0) | 2024.12.03 |
Express.js HandlerInterceptor: 개념 소개 (0) | 2024.11.26 |
CI 환경에서 `npm ci` 명령어를 사용해야 하는 이유 (1) | 2024.11.25 |