create-express-esm 1.1.11 → 1.2.0

package/README.md

@@ -1,10 +1,10 @@
 # 🚀 Create Express ESM (CLI)
 
-> **Modern Express Generator**
+> **Modern Express Generator with Database & Error Handling**
 >
-> "1초 만에 완성하는 Modern Express(ESM) 환경"
+> "1초 만에 완성하는 Modern Express(ESM) + Prisma + Docker 환경"
 >
-> CommonJS(require)가 아닌, 최신 ES Modules(import/export) 문법을 기반으로 하는 Express 프로젝트 구조를 자동으로 생성해주는 CLI 도구입니다.
+> CommonJS(require)가 아닌, 최신 ES Modules(import/export) 문법을 기반으로 하며, 데이터베이스 연동 및 전문적인 에러 핸들링까지 포함된 Express 프로젝트 구조를 자동으로 생성해주는 CLI 도구입니다.
 
 [![npm version](https://img.shields.io/npm/v/create-express-esm.svg)](https://www.npmjs.com/package/create-express-esm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -15,12 +15,14 @@
 
 ## ✨ Key Features (핵심 기능)
 
-기존 `express-generator`의 한계를 분석하고 개선하여 개발했습니다.
+기존 `express-generator`의 한계를 분석하고 개선하여 개발했습니다. v1.2.0 업데이트를 통해 실무형 풀스택 베이스를 제공합니다.
 
 - **🌐 Multi-Language Support**: JavaScript(ESM)와 **TypeScript** 중 원하는 개발 환경을 선택할 수 있습니다.
+- **🗄️ Database Integration**: **Prisma ORM**과 **PostgreSQL** 환경을 즉시 구축합니다. (Docker Compose 자동 생성)
+- **🚨 Professional Error Handling**: `AppError` 클래스와 **Global Error Middleware**를 통한 중앙 집중식 에러 처리 시스템을 제공합니다.
 - **🧪 Integrated Testing**: 최신 테스트 프레임워크인 **Vitest**와 API 테스트용 **Supertest** 환경을 자동 설정합니다.
-- **🏗 Layered Architecture**: 실무 표준인 `Controller` - `Service` - `Route` 계층 구조를 제공합니다.
-- **⚡️ Modern TS Execution**: `ts-node`의 ESM 호환성 문제를 해결한 **`tsx`**를 채택하여 쾌적한 개발 환경을 제공합니다.
+- **🏗 Layered Architecture**: 실무 표준인 `Controller` - `Service` - `Route` - `Middleware` 계층 구조를 제공합니다.
+- **⚡️ Modern Execution**: `ts-node`의 ESM 호환성 문제를 해결한 **`tsx`**를 채택하여 쾌적한 개발 환경을 제공합니다.
 - **📦 Smart Auto-Installation**: 프로젝트 생성 즉시 의존성 설치 및 환경 변수(`.env`) 세팅을 완료합니다.
 
 ## 🚀 Quick Start (사용법)
@@ -29,13 +31,29 @@
 
 ```bash
 npx create-express-esm
-npm install -g create-express-esm
-npm install create-express-esm
 ```
 
-또는 전역으로 설치하여 사용할 수도 있습니다
+### 프로젝트 생성 후 DB 시작하기
+
+DB 옵션을 선택했다면, 단 몇 줄의 명령어로 개발 준비가 끝납니다.
+
+```bash
+# 1. 프로젝트 폴더 이동
+cd my-app
+
+# 2. Docker를 통한 PostgreSQL 실행
+npm run db:up
+
+# 3. Prisma 스키마를 DB에 반영 (테이블 생성)
+npm run db:push
 
+# 4. 서버 실행
+npm run dev
 ```
+
+또는 전역으로 설치하여 사용할 수도 있습니다.
+
+```bash
 npm install -g create-express-esm
 create-express-esm
 ```
@@ -43,36 +61,40 @@ create-express-esm
 ## 📂 Project Structure (폴더 구조)
 
 이 도구는 **Layered Architecture (계층형 아키텍처)**를 기반으로 프로젝트를 생성합니다.
-**관심사 분리(Separation of Concerns)** 원칙을 적용하여, 로직이 섞이지 않고 유지보수가 쉬운 구조를 제공합니다.
+관심사 분리(Separation of Concerns) 원칙을 적용하여 유지보수가 쉬운 구조를 제공합니다.
 
 ```text
 my-app/
+├── prisma/             # 🗄️ Prisma Schema & Migrations
 ├── src/
 │   ├── controllers/    # 🕹️ 요청 처리 및 응답 반환 (Controller Layer)
 │   ├── services/       # 🧠 비즈니스 로직 처리 (Service Layer)
 │   ├── routes/         # 🚦 API 엔드포인트 정의 (Route Layer)
-│   ├── app.ts (or .js) # 🏗️ Express 앱 설정 및 미들웨어
-│   ├── server.ts (.js) # 🚀 서버 진입점 (Entry Point)
+│   ├── middlewares/    # 🛡️ 전역 에러 핸들러 및 커스텀 미들웨어
+│   ├── utils/          # 🛠️ AppError 클래스 등 공통 유틸리티
+│   ├── lib/            # 🖇️ Prisma Client 인스턴스 (Singleton)
+│   ├── app.ts          # 🏗️ Express 앱 설정 및 미들웨어
+│   ├── server.ts       # 🚀 서버 진입점 (Entry Point)
 │   └── app.test.ts     # 🧪 Vitest 샘플 테스트 코드
-├── .env                # 🔐 환경 변수 (자동 생성)
+├── .env                # 🔐 환경 변수 (DATABASE_URL 자동 생성)
+├── docker-compose.yml  # 🐳 PostgreSQL 컨테이너 설정
 ├── vitest.config.ts    # 🧪 Vitest 설정 파일
 ├── tsconfig.json       # ⚙️ TS 컴파일러 설정 (TS 선택 시)
 └── package.json        # 📦 의존성 및 스크립트
 ```
 
-주인님, 요청하신 대로 🛠 Tech Stack (기술 스택) 섹션부터 마지막까지의 내용을 마크다운 코드로 정리해 드립니다. 이 부분은 주인님이 이번에 해결하신 기술적 도전 과제들이 고스란히 담겨 있어 포트폴리오로서의 가치가 매우 높습니다.
-
-Markdown
-
 ## 🛠 Tech Stack (기술 스택)
 
 - **Runtime**: Node.js (v20+)
 - **Framework**: Express.js
 - **Language**: JavaScript (ESM) / TypeScript 5.x
+- **ORM**: Prisma (PostgreSQL)
+- **Infrastructure**: Docker Compose
 - **Testing**: Vitest, Supertest
 - **Dev Tools**:
   - `tsx` (TypeScript Execution Engine)
   - `nodemon` (Hot Reload)
+  - `@clack/prompts` (Interactive CLI UI)
   - `dotenv` (Environment Variables)
   - `cors` (Cross-Origin Resource Sharing)
   - `chalk` (CLI Styling)
@@ -80,15 +102,18 @@ Markdown
 ## 📝 Retrospective
 
 - **표준화된 환경의 중요성**: CJS에서 ESM으로 넘어가는 과도기적 문제를 해결하며 모던 자바스크립트 모듈 시스템에 대한 깊은 이해를 얻었습니다.
+- **에러 핸들링의 중앙화**: 개별 컨트롤러에서 반복되던 에러 처리 로직을 전역 미들웨어로 위임하여 코드 가독성과 유지보수성을 극대화했습니다.
+- **인프라 환경 이슈 해결**: 로컬 PostgreSQL과의 포트 충돌(5432 vs 5433) 및 도커 볼륨 인증 문제를 해결하며, 사용자에게 가장 안정적인 DB 연결 가이드를 제공하는 데 성공했습니다.
 - **UX 기반 설계**: 사용자가 프로젝트를 생성하자마자 `npm run dev`와 `npm test`를 즉시 실행할 수 있는 "Zero-Config" 환경을 제공하는 데 집중했습니다.
-- **배포 프로세스의 성숙**: 수동 배포의 위험성을 CI/CD와 OIDC 도입을 통해 자동화하며 소프트웨어 릴리스 과정의 안정성을 확보했습니다.
 
 ## 🗺️ Roadmap (Future Plans)
 
 - [x] **TypeScript Support**: `.ts` 템플릿 및 `tsx` 환경 최적화
 - [x] **Test Environment**: Vitest 및 Supertest 설정 자동화
-- [ ] **Interactive UI Upgrade**: `Clack` 라이브러리를 통한 시각적 CLI UI 개선
-- [ ] **Database Integration**: Prisma/Sequelize 등 ORM 선택 옵션 추가
+- [x] **Interactive UI Upgrade**: `Clack` 라이브러리를 통한 시각적 CLI UI 개선
+- [x] **Database Integration**: Prisma/PostgreSQL 및 Docker 선택 옵션 추가
+- [ ] **Authentication Template**: JWT/Passport를 이용한 기본 인증 로직 추가
+- [ ] **Deployment Guide**: AWS/Render 등 주요 플랫폼 배포 가이드라인 추가
 
 ## 📝 License
 

package/bin/cli.js

@@ -1,52 +1,75 @@
 #!/usr/bin/env node
 
-import { input, select, confirm } from '@inquirer/prompts';
+import * as p from '@clack/prompts';
 import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
+// ESM 환경에서 __dirname 구현
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 async function run() {
-  console.log(chalk.blue.bold('\n🚀 Create Express ESM 시작!\n'));
+  console.clear();
+  
+  // 1. 시작 인사
+  p.intro(`${chalk.bgBlue.white(' create-express-esm ')} ${chalk.dim('v1.2.0-beta')}`);
 
   try {
-    // 1. 사용자 질문
-    const projectName = await input({
-      message: '생성할 프로젝트 이름을 입력하세요:',
-      default: 'my-app',
-    });
-
-    const language = await select({
-      message: '사용할 언어를 선택하세요:',
-      choices: [
-        { name: 'JavaScript (ESM)', value: 'js' },
-        { name: 'TypeScript', value: 'ts' },
-      ],
-    });
-
-    const useTest = await confirm({
-      message: 'Vitest 테스트 환경을 추가하시겠습니까?',
-      default: true,
-    });
+    // 2. 사용자 질문 그룹
+    const project = await p.group(
+      {
+        projectName: () =>
+          p.text({
+            message: '프로젝트 이름을 입력하세요:',
+            placeholder: 'my-app',
+            validate: (value) => {
+              if (value.length === 0) return '프로젝트 이름은 필수입니다!';
+              if (fs.existsSync(path.join(process.cwd(), value))) return '해당 폴더가 이미 존재합니다.';
+            },
+          }),
+        language: () =>
+          p.select({
+            message: '사용할 언어를 선택하세요:',
+            options: [
+              { value: 'js', label: 'JavaScript (ESM)' },
+              { value: 'ts', label: 'TypeScript' },
+            ],
+          }),
+        useTest: () =>
+          p.confirm({
+            message: 'Vitest 테스트 환경을 추가하시겠습니까?',
+            initialValue: true,
+          }),
+        useDb: () =>
+          p.confirm({
+            message: 'Prisma ORM (PostgreSQL) 및 전역 에러 핸들링을 추가하시겠습니까?',
+            initialValue: false,
+          }),
+      },
+      {
+        onCancel: () => {
+          p.cancel('프로젝트 생성이 취소되었습니다.');
+          process.exit(0);
+        },
+      }
+    );
 
+    const { projectName, language, useTest, useDb } = project;
     const targetPath = path.join(process.cwd(), projectName);
     const templatePath = path.join(__dirname, '../template', language);
+    const commonPath = path.join(__dirname, '../template/common');
 
-    // 2. 폴더 존재 여부 확인
-    if (fs.existsSync(targetPath)) {
-      console.error(chalk.red(`\n❌ 오류: '${projectName}' 폴더가 이미 존재합니다.`));
-      process.exit(1);
-    }
+    // 3. 파일 구성 시작
+    const s = p.spinner();
+    s.start('프로젝트 템플릿을 복사하는 중...');
 
-    // 3. 기본 템플릿 복사
-    console.log(chalk.cyan(`\n📂 [${language.toUpperCase()}] 템플릿 구성을 시작합니다...`));
+    // 기본 언어 템플릿 복사
     await fs.copy(templatePath, targetPath);
 
-    // 4. 도트 파일 변환 (_env -> .env 등)
+    // 도트 파일 변환 (_env -> .env 등)
     const renameMap = {
       'gitignore': '.gitignore',
       '_gitignore': '.gitignore',
@@ -55,109 +78,137 @@ async function run() {
 
     for (const [oldName, newName] of Object.entries(renameMap)) {
       const oldFilePath = path.join(targetPath, oldName);
-      const newFilePath = path.join(targetPath, newName);
       if (await fs.pathExists(oldFilePath)) {
-        await fs.move(oldFilePath, newFilePath, { overwrite: true });
+        await fs.move(oldFilePath, path.join(targetPath, newName), { overwrite: true });
         if (newName === '.env') {
-          await fs.copy(newFilePath, path.join(targetPath, '.env.example'));
+          await fs.copy(path.join(targetPath, '.env'), path.join(targetPath, '.env.example'));
         }
       }
     }
-    
-    // 5. package.json 동적 수정
+
+    // 4. DB 및 에러 핸들링 선택 시 추가 파일 복사 및 코드 주입
+    if (useDb) {
+      // (1) Prisma 설정 및 Docker Compose 복사
+      await fs.copy(path.join(commonPath, 'prisma'), path.join(targetPath, 'prisma'));
+      await fs.copy(path.join(commonPath, 'docker-compose.yml'), path.join(targetPath, 'docker-compose.yml'));
+
+      // (2) 소스 코드 복사 (lib, services, controllers, routes, utils, middlewares)
+      const sourceFolders = ['lib', 'services', 'controllers', 'routes', 'utils', 'middlewares'];
+      for (const folder of sourceFolders) {
+        const srcFolderPath = path.join(commonPath, 'src', folder);
+        const destFolderPath = path.join(targetPath, 'src', folder);
+        
+        if (await fs.pathExists(srcFolderPath)) {
+          await fs.ensureDir(destFolderPath);
+          const files = await fs.readdir(srcFolderPath);
+          for (const file of files) {
+            // 사용자가 선택한 언어(ts/js)와 일치하는 파일만 복사
+            if (file.endsWith(`.${language}`)) {
+              await fs.copy(path.join(srcFolderPath, file), path.join(destFolderPath, file));
+            }
+          }
+        }
+      }
+
+      // (3) app.ts / app.js 에 코드 주입 (중요!)
+      const mainFilePath = path.join(targetPath, `src/app.${language}`);
+      if (await fs.pathExists(mainFilePath)) {
+        let content = await fs.readFile(mainFilePath, 'utf-8');
+        
+        // 상단 임포트 주입
+        const imports = [
+          `import userRoutes from './routes/userRoutes.js';`,
+          `import { errorHandler } from './middlewares/errorMiddleware.js';`
+        ].join('\n');
+        content = imports + '\n' + content;
+
+        // 라우터 등록 주입 (express.json() 뒤에)
+        const routeCode = `\napp.use('/users', userRoutes);`;
+        content = content.replace('app.use(express.json());', `app.use(express.json());${routeCode}`);
+
+        // 전역 에러 핸들러 주입 (서버 실행 직전에)
+        const errorMiddlewareCode = `\n// 전역 에러 핸들러 (모든 라우터 다음에 위치해야 함)\napp.use(errorHandler);\n`;
+        if (content.includes('export default app;')) {
+          content = content.replace('export default app;', `${errorMiddlewareCode}\nexport default app;`);
+        } else {
+          content += `\n${errorMiddlewareCode}`;
+        }
+
+        await fs.writeFile(mainFilePath, content);
+      }
+
+      // (4) .env 파일에 DATABASE_URL 추가
+      const envPath = path.join(targetPath, '.env');
+      const dbUrlContent = `
+# PostgreSQL Connection (Docker Compose default)
+DATABASE_URL="postgresql://myuser:mypassword@localhost:5432/mydb?schema=public"
+`;
+      await fs.appendFile(envPath, dbUrlContent);
+    }
+
+    // 5. package.json 동적 최적화
     const pkgPath = path.join(targetPath, 'package.json');
     const pkg = await fs.readJson(pkgPath);
     pkg.name = projectName;
 
-    // [추가된 부분] TypeScript 환경에서 ESM 에러를 방지하기 위한 tsx 설정
     if (language === 'ts') {
-      console.log(chalk.yellow(`⚙️  TypeScript ESM 실행 환경(tsx)을 최적화하는 중...`));
-      
-      // ts-node 대신 tsx를 사용하여 .js 확장자 임포트 문제 해결
       pkg.scripts.dev = "nodemon --exec tsx src/server.ts";
-      
-      // 의존성 교체
-      pkg.devDependencies = {
-        ...pkg.devDependencies,
-        "tsx": "^4.7.0"
-      };
-      
-      // 기존에 ts-node가 있다면 제거 (중복 방지)
-      delete pkg.devDependencies['ts-node'];
+      pkg.devDependencies["tsx"] = "^4.7.0";
     }
 
-    // Vitest 설정 (이슈 #3 구현 부분)
-    if (useTest) {
-      console.log(chalk.yellow(`🧪 Vitest 설정 및 샘플 테스트를 생성하는 중...`));
-      
-      pkg.scripts = {
-        ...pkg.scripts,
-        "test": "vitest",
-        "test:ui": "vitest --ui",
-        "test:run": "vitest run"
-      };
-
-      const testDeps = {
-        "vitest": "^1.0.0",
-        "supertest": "^6.3.3"
-      };
-
-      if (language === 'ts') {
-        testDeps["@types/supertest"] = "^2.0.12";
-      }
-
-      pkg.devDependencies = {
-        ...pkg.devDependencies,
-        ...testDeps
-      };
-
-      // Vitest 설정 파일 생성
+    // 테스트 환경 설정 (비사용 시 관련 파일 및 패키지 제거)
+    if (!useTest) {
       const configExt = language === 'ts' ? 'ts' : 'js';
-      const configContent = `import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-  },
-});`;
-      await fs.writeFile(path.join(targetPath, `vitest.config.${configExt}`), configContent);
-
-      // 샘플 테스트 파일 생성
       const testFileExt = language === 'ts' ? 'ts' : 'js';
-      const testContent = `import { describe, it, expect } from 'vitest';
-import request from 'supertest';
-import app from './app.js';
-
-describe('API Health Check Test', () => {
-  it('GET / 요청이 성공해야 한다', async () => {
-    const res = await request(app).get('/');
-    expect(res.status).toBe(200);
-    expect(res.text).toContain('Server is Running');
-  });
-});`;
-      await fs.writeFile(path.join(targetPath, `src/app.test.${testFileExt}`), testContent);
+      await fs.remove(path.join(targetPath, `vitest.config.${configExt}`));
+      await fs.remove(path.join(targetPath, `src/app.test.${testFileExt}`));
+      delete pkg.scripts.test;
+      delete pkg.scripts["test:ui"];
+      delete pkg.scripts["test:run"];
+      delete pkg.devDependencies.vitest;
+      delete pkg.devDependencies.supertest;
+      if (pkg.devDependencies["@types/supertest"]) delete pkg.devDependencies["@types/supertest"];
+    }
+
+    // DB 의존성 및 스크립트 추가
+    if (useDb) {
+      pkg.scripts["db:up"] = "docker-compose up -d";
+      pkg.scripts["db:push"] = "prisma db push";
+      pkg.scripts["prisma:generate"] = "prisma generate";
+      pkg.scripts["prisma:studio"] = "prisma studio";
+      
+      pkg.dependencies["@prisma/client"] = "^5.0.0";
+      pkg.devDependencies["prisma"] = "^5.0.0";
     }
 
     await fs.writeJson(pkgPath, pkg, { spaces: 2 });
-    console.log(chalk.green(`✅ 모든 구성 완료!`));
+    s.stop('파일 구성 완료!');
 
-    // 6. 패키지 자동 설치
-    console.log(chalk.yellow(`\n📦 의존성 패키지를 설치합니다... (npm install)`));
-    execSync('npm install', { cwd: targetPath, stdio: 'inherit' });
+    // 6. 의존성 설치
+    const installSpinner = p.spinner();
+    installSpinner.start('의존성 패키지를 설치하는 중... (npm install)');
+    
+    try {
+      execSync('npm install', { cwd: targetPath, stdio: 'ignore' });
+      installSpinner.stop('설치 완료!');
+    } catch (e) {
+      installSpinner.stop(chalk.red('설치 실패 (수동 설치가 필요할 수 있습니다)'));
+    }
 
-    console.log(chalk.green(`\n✨ 프로젝트 생성 성공!`));
-    console.log(chalk.white(`\n다음 명령어를 입력해 보세요:\n`));
-    console.log(chalk.cyan(`   cd ${projectName}`));
-    if (useTest) console.log(chalk.cyan(`   npm test`));
-    console.log(chalk.cyan(`   npm run dev\n`));
+    // 7. 마무리
+    let nextSteps = `cd ${projectName}\n`;
+    if (useDb) {
+      nextSteps += `${chalk.bold('npm run db:up')} (DB 실행)\n`;
+      nextSteps += `${chalk.bold('npm run db:push')} (테이블 생성)\n`;
+    }
+    nextSteps += `npm run dev`;
+
+    p.note(chalk.cyan(nextSteps), '시작하려면 다음 명령어를 입력하세요');
+    p.outro(chalk.green('✨ 모든 준비가 끝났습니다. 즐거운 개발 되세요!'));
 
   } catch (error) {
-    if (error.name === 'ExitPromptError') { // 오타 수정: ExitPnromptError -> ExitPromptError
-      console.log(chalk.yellow('\n\n👋 설치를 중단했습니다.'));
-    } else {
-      console.error(chalk.red('\n❌ 오류 발생:'), error);
-    }
+    p.cancel(`오류 발생: ${error.message}`);
+    process.exit(1);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-express-esm",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "A modern CLI tool to bootstrap Express.js applications with ES Modules and Layered Architecture.",
   "main": "index.js",
   "type": "module",
@@ -25,7 +25,7 @@
   "author": "munjuin",
   "license": "MIT",
   "dependencies": {
-    "@inquirer/prompts": "^8.1.0",
+    "@clack/prompts": "^0.11.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "fs-extra": "^11.3.2",

package/template/common/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+services:
+  db:
+    image: postgres:15-alpine
+    restart: always
+    environment:
+      - POSTGRES_USER=myuser
+      - POSTGRES_PASSWORD=mypassword
+      - POSTGRES_DB=mydb
+    ports:
+      - '5432:5432'
+    volumes:
+      - db-data:/var/lib/postgresql/data
+
+volumes:
+  db-data:

package/template/common/prisma/schema.prisma

@@ -0,0 +1,16 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}

package/template/common/src/controllers/userController.ts

@@ -0,0 +1,42 @@
+import { Request, Response, NextFunction } from 'express';
+import { userService } from '../services/userService.js';
+
+export const userController = {
+  // 1. 모든 사용자 조회
+  async getUsers(req: Request, res: Response, next: NextFunction) {
+    try {
+      const users = await userService.getAllUsers();
+      res.json(users);
+    } catch (error) {
+      next(error); // 에러를 전역 핸들러로 던짐
+    }
+  },
+
+  // 2. 새 사용자 생성
+  async createUser(req: Request, res: Response, next: NextFunction) {
+    try {
+      const { email, name } = req.body;
+      const newUser = await userService.createUser({ email, name });
+      res.status(201).json(newUser);
+    } catch (error) {
+      next(error); // 여기서 에러가 던져지면 errorHandler가 P2002(중복) 등을 처리함
+    }
+  },
+
+  // 3. 특정 사용자 조회
+  async getUserById(req: Request, res: Response, next: NextFunction) {
+    try {
+      const id = parseInt(req.params.id);
+      const user = await userService.getUserById(id);
+      
+      if (!user) {
+        // AppError를 사용해 404 에러를 직접 던질 수도 있습니다.
+        throw new Error('사용자를 찾을 수 없습니다.');
+      }
+      
+      res.json(user);
+    } catch (error) {
+      next(error);
+    }
+  }
+};

package/template/common/src/middlewares/errorMiddleware.ts

@@ -0,0 +1,19 @@
+import { Request, Response, NextFunction } from 'express';
+import { AppError } from '../utils/appError.js';
+
+export const errorHandler = (err: any, req: Request, res: Response, next: NextFunction) => {
+  err.statusCode = err.statusCode || 500;
+
+  // Prisma 고유 에러 처리 (예: 이메일 중복)
+  if (err.code === 'P2002') {
+    err.message = '이미 사용 중인 데이터(이메일 등)가 있습니다.';
+    err.statusCode = 400;
+  }
+
+  res.status(err.statusCode).json({
+    status: 'error',
+    message: err.message,
+    // 개발 환경에서만 에러 스택 표시
+    stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
+  });
+};

package/template/common/src/utils/appError.ts

@@ -0,0 +1,12 @@
+export class AppError extends Error {
+  public statusCode: number;
+  public isOperational: boolean;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = true; // 예측 가능한 에러임을 표시
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/template/js/_env

@@ -1,2 +1,3 @@
-PORT=8080PORT=3000
-NODE_ENV=development
+# PostgreSQL Connection String
+# 형식: postgresql://사용자:비밀번호@호스트:포트/데이터베이스명?schema=public
+DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/myapp?schema=public"