create-express-esm 1.1.12 → 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,48 +31,70 @@
 
 ```bash
 npx create-express-esm
-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
 ```
 
 ## 📂 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)
@@ -78,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

@@ -14,11 +14,11 @@ const __dirname = path.dirname(__filename);
 async function run() {
   console.clear();
   
-  // 1. 시작 인사 (Intro)
-  p.intro(`${chalk.bgBlue.white(' create-express-esm ')} ${chalk.dim('v1.1.9')}`);
+  // 1. 시작 인사
+  p.intro(`${chalk.bgBlue.white(' create-express-esm ')} ${chalk.dim('v1.2.0-beta')}`);
 
   try {
-    // 2. 사용자 질문 그룹 (Group)
+    // 2. 사용자 질문 그룹
     const project = await p.group(
       {
         projectName: () =>
@@ -43,6 +43,11 @@ async function run() {
             message: 'Vitest 테스트 환경을 추가하시겠습니까?',
             initialValue: true,
           }),
+        useDb: () =>
+          p.confirm({
+            message: 'Prisma ORM (PostgreSQL) 및 전역 에러 핸들링을 추가하시겠습니까?',
+            initialValue: false,
+          }),
       },
       {
         onCancel: () => {
@@ -52,18 +57,19 @@ async function run() {
       }
     );
 
-    const { projectName, language, useTest } = project;
+    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');
 
-    // 3. 파일 구성 시작 (Spinner)
+    // 3. 파일 구성 시작
     const s = p.spinner();
     s.start('프로젝트 템플릿을 복사하는 중...');
 
-    // 템플릿 전체 복사 (Vitest 파일 포함)
+    // 기본 언어 템플릿 복사
     await fs.copy(templatePath, targetPath);
 
-    // 도트 파일 변환 (예: _env -> .env)
+    // 도트 파일 변환 (_env -> .env 등)
     const renameMap = {
       'gitignore': '.gitignore',
       '_gitignore': '.gitignore',
@@ -75,50 +81,110 @@ async function run() {
       if (await fs.pathExists(oldFilePath)) {
         await fs.move(oldFilePath, path.join(targetPath, newName), { overwrite: true });
         if (newName === '.env') {
-            await fs.copy(path.join(targetPath, '.env'), path.join(targetPath, '.env.example'));
+          await fs.copy(path.join(targetPath, '.env'), path.join(targetPath, '.env.example'));
         }
       }
     }
 
-    // 4. 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 선택 시 실행 환경(tsx) 강제 설정
     if (language === 'ts') {
       pkg.scripts.dev = "nodemon --exec tsx src/server.ts";
       pkg.devDependencies["tsx"] = "^4.7.0";
-      // 구형 ts-node 제거
-      if (pkg.devDependencies["ts-node"]) delete pkg.devDependencies["ts-node"];
     }
 
-    // 테스트 환경 사용 여부에 따른 처리
-    const configExt = language === 'ts' ? 'ts' : 'js';
-    const testFileExt = language === 'ts' ? 'ts' : 'js';
-
+    // 테스트 환경 설정 (비사용 시 관련 파일 및 패키지 제거)
     if (!useTest) {
-      // 사용자가 원치 않으면 복사된 테스트 파일 삭제
+      const configExt = language === 'ts' ? 'ts' : 'js';
+      const testFileExt = language === 'ts' ? 'ts' : 'js';
       await fs.remove(path.join(targetPath, `vitest.config.${configExt}`));
       await fs.remove(path.join(targetPath, `src/app.test.${testFileExt}`));
-
-      // package.json에서 관련 설정 제거
       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"];
-    } else {
-      // 사용자가 원하면 스크립트가 확실히 있는지 보장
-      pkg.scripts.test = "vitest";
-      pkg.scripts["test:ui"] = "vitest --ui";
+    }
+
+    // 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 });
     s.stop('파일 구성 완료!');
 
-    // 5. 의존성 설치 (Spinner)
+    // 6. 의존성 설치
     const installSpinner = p.spinner();
     installSpinner.start('의존성 패키지를 설치하는 중... (npm install)');
     
@@ -129,12 +195,15 @@ async function run() {
       installSpinner.stop(chalk.red('설치 실패 (수동 설치가 필요할 수 있습니다)'));
     }
 
-    // 6. 마무리 (Note & Outro)
-    p.note(
-      chalk.cyan(`cd ${projectName}\n${useTest ? 'npm test\n' : ''}npm run dev`),
-      '시작하려면 다음 명령어를 입력하세요'
-    );
+    // 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-express-esm",
-  "version": "1.1.12",
+  "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",

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=3000
-NODE_ENV=development
+# PostgreSQL Connection String
+# 형식: postgresql://사용자:비밀번호@호스트:포트/데이터베이스명?schema=public
+DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/myapp?schema=public"

package/template/ts/_env

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