환경변수
Akan.js는 baseEnv와 baseClientEnv를 통해 중앙화된 환경 설정 시스템을 제공합니다. 이 객체들은 애플리케이션이 다양한 환경(local, debug, develop, main)과 컨텍스트(server, client)에서 어떻게 동작하는지 결정하는 필수 런타임 정보를 포함합니다.
🔧baseEnv
서버와 클라이언트 전반에서 공유되는 핵심 환경 변수. 앱 식별정보, 환경 타입, 운영 모드, 네트워크 설정을 포함합니다.
🌐baseClientEnv
클라이언트 측 작업을 위한 확장 환경. baseEnv의 모든 속성과 클라이언트/서버 연결 URI, 프로토콜, 렌더 모드 설정을 포함합니다.
루트 환경변수 (.env)
워크스페이스 루트에 있는 .env 파일에서 환경변수를 설정할 수 있습니다. 이 변수들은 Node.js 환경에서 process.env를 통해 접근 가능하며, baseEnv와 baseClientEnv를 초기화하는데 사용됩니다.
.env (Root)
NEXT_PUBLIC_ 접두사가 붙은 변수는 브라우저에 노출됩니다. 민감한 데이터(API 키, 비밀번호)를 NEXT_PUBLIC_ 변수에 넣지 마세요.
⚠️필수 변수
NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_REPO_NAME, NEXT_PUBLIC_SERVE_DOMAIN는 필수입니다. 설정되지 않으면 애플리케이션에서 에러가 발생합니다.
baseEnv
baseEnv는 전체 애플리케이션에서 공유되는 핵심 환경 변수를 포함합니다. process.env에서 자동으로 읽어오며 환경 설정에 대한 타입 안전한 접근을 제공합니다.
BaseEnv Interface
속성 상세:
environment- local: 로컬 개발 환경
- debug: 테스트용 디버그 서버 환경
- develop: 개발/스테이징 환경
- main: 프로덕션 환경
- testing: 자동화 테스트 환경
operationMode- local: 로컬 서비스로 로컬에서 실행
- edge: 엣지 배포 (Vercel Edge 등)
- cloud: 클라우드/쿠버네티스 배포
- module: 모듈/라이브러리로 실행
networkType- mainnet: 프로덕션 네트워크 (environment가 'main'일 때 자동 선택)
- testnet: 테스트 네트워크 (environment가 'develop'일 때 자동 선택)
- debugnet: 디버그 네트워크 (다른 환경의 기본값)
baseClientEnv
baseClientEnv는 클라이언트 특화 설정으로 baseEnv를 확장합니다. 클라이언트/서버 컨텍스트를 자동 감지하고 적절한 연결 URI를 생성합니다.
BaseClientEnv Interface
자동 생성 URI:
🖥️로컬 환경 예시
clientHttpUri: "http://localhost:4200"
serverHttpUri: "http://localhost:8080/backend"
serverGraphqlUri: "http://localhost:8080/backend/graphql"
serverWsUri: "ws://localhost:8080"☁️클라우드 환경 예시
clientHttpUri: "https://myapp-debug.example.com"
serverHttpUri: "https://myapp-debug.example.com/backend"
serverGraphqlUri: "https://myapp-debug.example.com/backend/graphql"
serverWsUri: "wss://myapp-debug.example.com"사용 예시
프레임워크 전반에서 baseEnv와 baseClientEnv가 사용되는 실제 예시입니다:
백엔드 서버 설정
boot.ts - Server Initialization
클라이언트 API 연결
client.ts - API Client Setup
SSR/CSR 감지가 포함된 라우터
router.ts - Navigation with Context Detection
환경 설정
각 애플리케이션은 앱별 설정으로 baseEnv/baseClientEnv를 확장합니다. env 폴더에는 NEXT_PUBLIC_ENV에 따라 선택되는 환경별 파일이 포함됩니다.
env/env.client.ts - Client Environment Router
env/env.client.local.ts - Local Client Config
env/env.server.local.ts - Local Server Config
📁환경 파일 구조
apps/myapp/env/
├── env.client.ts # Client env router
├── env.client.type.ts # Client env type
├── env.client.local.ts # Local client config
├── env.client.debug.ts # Debug client config
├── env.client.develop.ts # Develop client config
├── env.client.main.ts # Production client config
├── env.server.ts # Server env router
├── env.server.type.ts # Server env type
├── env.server.local.ts # Local server config
├── env.server.debug.ts # Debug server config
├── env.server.develop.ts # Develop server config
└── env.server.main.ts # Production server config환경 설정 모범 사례
1️⃣환경 체크 사용
baseEnv.environment를 사용하여 조건부로 기능을 활성화합니다. 프로덕션(main)에서는 인트로스펙션, 상세 로깅, 디버그 도구를 비활성화합니다.
2️⃣DOM 작업 전 side 확인
window, document 또는 브라우저 전용 API에 접근하기 전에 항상 baseClientEnv.side를 확인하세요. baseClientEnv.side === "client" 가드를 사용합니다.
3️⃣민감한 설정 분리
API 키, 비밀번호, 시크릿은 env.server.*.ts 파일에만 넣습니다. 민감한 데이터를 env.client.*.ts나 NEXT_PUBLIC_ 변수에 포함하지 마세요.
4️⃣자동 생성 URI 사용
URL을 하드코딩하는 대신 baseClientEnv.serverHttpUri와 serverGraphqlUri를 사용하세요. 환경과 배포 컨텍스트에 따라 자동으로 조정됩니다.
🎉 학습한 내용:
- ✓ Node.js process.env를 위한 루트 .env 파일 설정
- ✓ 핵심 환경 변수를 위한 baseEnv (appName, environment, operationMode, networkType)
- ✓ 클라이언트/서버 컨텍스트 감지와 자동 생성 연결 URI를 위한 baseClientEnv
- ✓ 환경 기반 파일 선택을 통한 애플리케이션별 env 설정
- ✓ 안전하고 컨텍스트 인식 환경 사용을 위한 모범 사례