환경변수

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 설정
✓ 안전하고 컨텍스트 인식 환경 사용을 위한 모범 사례

환경변수

🔧baseEnv

서버와 클라이언트 전반에서 공유되는 핵심 환경 변수. 앱 식별정보, 환경 타입, 운영 모드, 네트워크 설정을 포함합니다.

🌐baseClientEnv

클라이언트 측 작업을 위한 확장 환경. baseEnv의 모든 속성과 클라이언트/서버 연결 URI, 프로토콜, 렌더 모드 설정을 포함합니다.

루트 환경변수 (.env)

.env (Root)

NEXT_PUBLIC_ 접두사가 붙은 변수는 브라우저에 노출됩니다. 민감한 데이터(API 키, 비밀번호)를 NEXT_PUBLIC_ 변수에 넣지 마세요.

⚠️필수 변수

NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_REPO_NAME, NEXT_PUBLIC_SERVE_DOMAIN는 필수입니다. 설정되지 않으면 애플리케이션에서 에러가 발생합니다.

baseEnv

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 설정
✓ 안전하고 컨텍스트 인식 환경 사용을 위한 모범 사례