@kood/claude-code 0.1.7 → 0.1.9

package/templates/hono/docs/library/hono/env-setup.md

@@ -1,22 +1,19 @@
 # Hono - 환경 변수 설정
 
-> **상위 문서**: [Hono](./index.md)
-
-환경별 `.env` 파일 설정 및 타입 안전한 환경 변수 관리 방법입니다.
+> 타입 안전한 환경 변수 관리
 
 ---
 
-## 환경별 .env 파일 구조
+## 파일 구조
 
 ```
 프로젝트/
-├── .env                    # 기본 환경 변수 (공통)
+├── .env                    # 기본 (공통)
 ├── .env.development        # 개발 환경
-├── .env.production         # 프로덕션 환경
-├── .env.local              # 로컬 개발 (gitignore)
-├── .env.example            # 예시 파일 (커밋용)
-└── src/
-    └── env.ts              # 환경 변수 검증 및 타입
+├── .env.production         # 프로덕션
+├── .env.local              # 로컬 (gitignore)
+├── .env.example            # 템플릿 (커밋용)
+└── src/env.ts              # 검증 및 타입
 ```
 
 ---
@@ -24,242 +21,77 @@
 ## 설치
 
 ```bash
-npm install dotenv
+npm install dotenv zod
 npm install -D @types/node
 ```
 
 ---
 
-## 환경 변수 파일 예시
-
-### .env.example (커밋용 템플릿)
-
-```env
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-# 환경 변수 템플릿
-# 복사 후 .env.local 로 저장하여 사용
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-# 앱 설정
-NODE_ENV=development
-PORT=3000
-
-# 데이터베이스
-DATABASE_URL=postgresql://user:password@localhost:5432/mydb
-
-# 인증
-JWT_SECRET=your-secret-key-here
-JWT_EXPIRES_IN=7d
-
-# 외부 서비스
-OPENAI_API_KEY=sk-xxx
-REDIS_URL=redis://localhost:6379
-```
-
-### .env.development
-
-```env
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-# 개발 환경 설정
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-NODE_ENV=development
-PORT=3000
-
-# 개발용 데이터베이스
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_dev
-
-# 개발용 시크릿 (짧은 값 OK)
-JWT_SECRET=dev-secret-key
-JWT_EXPIRES_IN=1d
-
-# 개발용 외부 서비스
-OPENAI_API_KEY=sk-dev-xxx
-REDIS_URL=redis://localhost:6379
-
-# 개발용 옵션
-LOG_LEVEL=debug
-CORS_ORIGIN=http://localhost:5173
-```
-
-### .env.production
-
-```env
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-# 프로덕션 환경 설정
-# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-NODE_ENV=production
-PORT=8080
-
-# 프로덕션 데이터베이스
-DATABASE_URL=postgresql://user:strongpassword@prod-db.example.com:5432/myapp
-
-# 프로덕션 시크릿 (강력한 값 필수)
-JWT_SECRET=super-secure-production-secret-key-at-least-32-chars
-JWT_EXPIRES_IN=7d
-
-# 프로덕션 외부 서비스
-OPENAI_API_KEY=sk-prod-xxx
-REDIS_URL=redis://prod-redis.example.com:6379
-
-# 프로덕션 옵션
-LOG_LEVEL=info
-CORS_ORIGIN=https://myapp.com
-```
-
----
-
-## 타입 안전한 환경 변수 (Zod)
+## Zod로 환경 변수 검증
 
 ### src/env.ts
 
 ```typescript
-// src/env.ts
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 환경 변수 검증 및 타입 정의
-// 앱 시작 시 자동으로 환경 변수를 검증합니다
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 import { z } from 'zod'
 
-// 환경 변수 스키마
 const envSchema = z.object({
-  // 앱 설정
   NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
   PORT: z.coerce.number().default(3000),
-
-  // 데이터베이스
   DATABASE_URL: z.string().url(),
-
-  // 인증
   JWT_SECRET: z.string().min(16),
   JWT_EXPIRES_IN: z.string().default('7d'),
-
-  // 외부 서비스 (선택적)
   OPENAI_API_KEY: z.string().optional(),
-  REDIS_URL: z.string().url().optional(),
-
-  // 옵션
   LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
   CORS_ORIGIN: z.string().default('*'),
 })
 
-// 환경 변수 타입 추출
 export type Env = z.infer<typeof envSchema>
 
-// 환경 변수 파싱 및 검증
 const parseEnv = (): Env => {
   const result = envSchema.safeParse(process.env)
-
   if (!result.success) {
-    console.error('❌ 환경 변수 검증 실패:')
-    console.error(result.error.format())
+    console.error('환경 변수 검증 실패:', result.error.format())
     process.exit(1)
   }
-
   return result.data
 }
 
-// 검증된 환경 변수 export
 export const env = parseEnv()
 ```
 
 ---
 
-## dotenv 설정
+## dotenv 로드
 
-### src/index.ts (진입점)
+### src/index.ts
 
 ```typescript
-// src/index.ts
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// Hono 앱 진입점
-// dotenv는 가장 먼저 import해야 합니다
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-import 'dotenv/config'  // ⚠️ 반드시 최상단!
+import 'dotenv/config'  // 최상단!
 import { serve } from '@hono/node-server'
 import { app } from './app'
 import { env } from './env'
 
-serve({
-  fetch: app.fetch,
-  port: env.PORT,
-}, (info) => {
-  console.log(`🚀 Server running on http://localhost:${info.port}`)
-  console.log(`📍 Environment: ${env.NODE_ENV}`)
+serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+  console.log(`Server: http://localhost:${info.port}`)
 })
 ```
 
-### 환경별 dotenv 로드
-
-```typescript
-// src/load-env.ts
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 환경별 .env 파일 로드
-// NODE_ENV에 따라 적절한 파일을 로드합니다
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-import { config } from 'dotenv'
-import path from 'node:path'
-
-const loadEnv = () => {
-  const nodeEnv = process.env.NODE_ENV || 'development'
-
-  // 로드 순서: .env.local → .env.{환경} → .env
-  const envFiles = [
-    `.env.local`,           // 로컬 오버라이드 (gitignore)
-    `.env.${nodeEnv}`,      // 환경별 설정
-    `.env`,                 // 기본 설정
-  ]
-
-  envFiles.forEach((file) => {
-    config({ path: path.resolve(process.cwd(), file) })
-  })
-}
-
-loadEnv()
-
-export {}
-```
-
-```typescript
-// src/index.ts
-import './load-env'  // ⚠️ 반드시 최상단!
-import { serve } from '@hono/node-server'
-import { app } from './app'
-import { env } from './env'
-
-// ... 나머지 코드
-```
-
 ---
 
-## Hono Bindings 타입 정의
+## Hono Bindings
 
 ### src/types/hono.ts
 
 ```typescript
-// src/types/hono.ts
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// Hono 앱 타입 정의
-// Bindings, Variables 등 전역 타입을 정의합니다
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 import type { Env } from '../env'
 
-// 환경 변수 Bindings
 export type Bindings = Env
 
-// 요청 간 공유 변수
 export type Variables = {
   requestId: string
   userId?: string
-  user?: {
-    id: string
-    email: string
-    role: string
-  }
 }
 
-// Hono 앱 타입
 export type HonoEnv = {
   Bindings: Bindings
   Variables: Variables
@@ -269,50 +101,24 @@ export type HonoEnv = {
 ### src/app.ts
 
 ```typescript
-// src/app.ts
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// Hono 앱 설정
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 import { Hono } from 'hono'
-import { cors } from 'hono/cors'
-import { logger } from 'hono/logger'
 import type { HonoEnv } from './types/hono'
 import { env } from './env'
 
 export const app = new Hono<HonoEnv>()
 
-// 미들웨어 설정
-app.use('*', logger())
-app.use('*', cors({ origin: env.CORS_ORIGIN }))
-
-// 환경 변수 바인딩 미들웨어 (Node.js용)
+// Node.js에서 env 바인딩
 app.use('*', async (c, next) => {
-  // Node.js에서는 process.env를 c.env로 바인딩
   Object.assign(c.env, env)
   await next()
 })
 
-// 라우트
-app.get('/', (c) => {
-  return c.json({
-    message: 'Hello Hono!',
-    environment: c.env.NODE_ENV,
-  })
-})
-
-app.get('/health', (c) => {
-  return c.json({
-    status: 'ok',
-    timestamp: new Date().toISOString(),
-  })
-})
+app.get('/', (c) => c.json({ env: c.env.NODE_ENV }))
 ```
 
 ---
 
-## Cloudflare Workers 환경
-
-Cloudflare Workers에서는 `wrangler.toml`과 `.dev.vars`를 사용합니다.
+## Cloudflare Workers
 
 ### wrangler.toml
 
@@ -324,135 +130,40 @@ compatibility_date = "2024-01-01"
 [vars]
 NODE_ENV = "production"
 LOG_LEVEL = "info"
-
-# 개발 환경 오버라이드
-[env.development.vars]
-NODE_ENV = "development"
-LOG_LEVEL = "debug"
 ```
 
-### .dev.vars (개발용 시크릿)
+### .dev.vars (시크릿, gitignore)
 
 ```env
-# ⚠️ 이 파일은 gitignore에 추가해야 합니다
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_dev
+DATABASE_URL=postgresql://localhost:5432/myapp_dev
 JWT_SECRET=dev-secret-key
-OPENAI_API_KEY=sk-dev-xxx
 ```
 
-### wrangler 시크릿 설정 (프로덕션)
+### 시크릿 설정
 
 ```bash
-# 시크릿 추가
 wrangler secret put DATABASE_URL
 wrangler secret put JWT_SECRET
-wrangler secret put OPENAI_API_KEY
-
-# 시크릿 목록 확인
-wrangler secret list
 ```
 
 ---
 
-## .gitignore 설정
+## .gitignore
 
 ```gitignore
-# 환경 변수 파일
 .env
 .env.local
 .env.*.local
 .dev.vars
 
-# 커밋해도 되는 파일
 !.env.example
 !.env.development
 !.env.production
 ```
 
-⚠️ **주의**: `.env.development`와 `.env.production`에는 **실제 시크릿을 절대 넣지 마세요!**
-- 실제 시크릿은 `.env.local` 또는 CI/CD 환경 변수로 관리
-- `.env.development`, `.env.production`은 기본값과 플레이스홀더만 포함
-
----
-
-## package.json 스크립트
-
-```json
-{
-  "scripts": {
-    "dev": "NODE_ENV=development tsx watch src/index.ts",
-    "build": "tsc",
-    "start": "NODE_ENV=production node dist/index.js",
-    "start:dev": "NODE_ENV=development node dist/index.js",
-    "typecheck": "tsc --noEmit"
-  }
-}
-```
-
-### cross-env 사용 (Windows 호환)
-
-```bash
-npm install -D cross-env
-```
-
-```json
-{
-  "scripts": {
-    "dev": "cross-env NODE_ENV=development tsx watch src/index.ts",
-    "start": "cross-env NODE_ENV=production node dist/index.js"
-  }
-}
-```
-
----
-
-## 환경 변수 사용 예시
-
-### 라우트에서 사용
-
-```typescript
-// src/routes/users.ts
-import { Hono } from 'hono'
-import type { HonoEnv } from '../types/hono'
-import { env } from '../env'
-
-const users = new Hono<HonoEnv>()
-
-users.get('/', (c) => {
-  // 방법 1: env 모듈에서 직접 가져오기 (권장)
-  const dbUrl = env.DATABASE_URL
-
-  // 방법 2: context에서 가져오기
-  const nodeEnv = c.env.NODE_ENV
-
-  return c.json({ environment: nodeEnv })
-})
-
-export { users }
-```
-
-### 조건부 로직
-
-```typescript
-import { env } from '../env'
-
-// 개발 환경에서만 실행
-if (env.NODE_ENV === 'development') {
-  console.log('🔧 Development mode')
-  // 개발용 설정...
-}
-
-// 프로덕션에서만 실행
-if (env.NODE_ENV === 'production') {
-  // 프로덕션 최적화...
-}
-```
-
 ---
 
 ## 관련 문서
 
 - [Hono 개요](./index.md)
-- [미들웨어](./middleware.md)
-- [Zod 검증](./validation.md)
-- [Cloudflare 배포](../deployment/cloudflare.md)
+- [Cloudflare 배포](../../deployment/cloudflare.md)