@hamjimin/xplat-back 0.1.0

package/README.md

@@ -0,0 +1,289 @@
+# xplat-back
+
+Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)
+
+파일명과 API endpoint가 자동으로 일치하는 라우팅 시스템을 제공합니다. 디렉토리 구조를 기반으로 자동으로 Express 라우터를 생성하여, 파일명만으로 API endpoint를 매핑할 수 있습니다.
+
+## 특징
+
+- 🚀 **파일 기반 라우팅**: 파일명과 디렉토리 구조가 API endpoint로 자동 매핑
+- 📁 **자동 라우터 생성**: 디렉토리 구조를 재귀적으로 탐색하여 라우터 자동 생성
+- ⚡ **빠른 프로젝트 설정**: CLI를 통한 프로젝트 초기화
+- 🔧 **TypeScript 지원**: 완전한 TypeScript 타입 정의 포함
+- 🎯 **zium-backend 기반**: 검증된 프로젝트 구조 기반
+
+## 설치
+
+```bash
+npm install xplat-back
+# 또는
+yarn add xplat-back
+```
+
+## 빠른 시작
+
+### CLI를 통한 프로젝트 초기화
+
+```bash
+npx xplat-back [project-name]
+```
+
+옵션:
+
+```bash
+npx xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+```
+
+사용 가능한 옵션:
+- `-p, --port <port>`: 서버 포트 (기본값: 4000)
+- `-c, --cors <origins>`: CORS 허용 origins (쉼표로 구분)
+- `-r, --router-dir <directory>`: 라우터 디렉토리 (기본값: src/restapi)
+- `--router-path <path>`: 라우터 base path (기본값: /restapi)
+
+### 수동 설정
+
+#### 1. 패키지 설치
+
+```bash
+npm install express xplat-back
+npm install -D typescript @types/express @types/node ts-node tsconfig-paths
+```
+
+#### 2. Express 앱 생성
+
+`src/app.ts`:
+
+```typescript
+import express, { Application } from 'express';
+import * as path from 'path';
+import { createApp } from 'xplat-back';
+
+const app: Application = createApp({
+  cors: {
+    origin: ['http://localhost:3000'],
+    credentials: true,
+  },
+  router: {
+    directory: path.join(__dirname, 'restapi'),
+    basePath: '/restapi',
+  },
+  trustProxy: true,
+});
+
+const port = parseInt(process.env.PORT || '4000', 10);
+
+app.listen(port, () => {
+  console.log(`🚀 Server is running on port ${port}`);
+});
+
+export default app;
+```
+
+#### 3. 라우트 파일 생성
+
+`src/restapi/health.ts`:
+
+```typescript
+import express, { Request, Response } from 'express';
+
+const router = express.Router();
+
+router.get('/', (req: Request, res: Response) => {
+  res.json({
+    success: true,
+    message: 'Server is healthy',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+export = router;
+```
+
+이제 `GET /restapi/health` 엔드포인트가 자동으로 생성됩니다!
+
+#### 4. 서버 실행
+
+```bash
+npm run dev
+# 또는
+ts-node -r tsconfig-paths/register src/app.ts
+```
+
+## API 문서
+
+### `createApp(config?)`
+
+Express 애플리케이션을 생성합니다.
+
+#### Parameters
+
+```typescript
+interface AppConfig {
+  cors?: {
+    origin?: string[] | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+    credentials?: boolean;
+  };
+  json?: {
+    limit?: string;
+  };
+  urlencoded?: {
+    extended?: boolean;
+  };
+  router?: {
+    directory?: string;
+    basePath?: string;
+  };
+  trustProxy?: boolean;
+  middleware?: Array<(req: Request, res: Response, next: NextFunction) => void>;
+}
+```
+
+#### 예제
+
+```typescript
+import { createApp } from 'xplat-back';
+
+const app = createApp({
+  cors: {
+    origin: process.env.CORS_ALLOW_ORIGINS?.split(',') ?? ['*'],
+    credentials: true,
+  },
+  router: {
+    directory: path.join(__dirname, 'restapi'),
+    basePath: '/restapi',
+  },
+  middleware: [
+    // 커스텀 미들웨어
+    (req, res, next) => {
+      console.log(`${req.method} ${req.path}`);
+      next();
+    },
+  ],
+});
+```
+
+### `createRouter(directory)`
+
+디렉토리 구조를 기반으로 Express 라우터를 생성합니다.
+
+#### Parameters
+
+- `directory` (string): 라우트 파일들이 위치한 디렉토리 경로
+
+#### 예제
+
+```typescript
+import { createRouter } from 'xplat-back';
+import * as path from 'path';
+
+const router = createRouter(path.join(__dirname, 'restapi'));
+app.use('/restapi', router);
+```
+
+#### 라우팅 규칙
+
+디렉토리 구조가 다음과 같을 때:
+
+```
+restapi/
+├── health.ts          → GET /restapi/health
+├── user/
+│   ├── profile.ts     → GET /restapi/user/profile
+│   └── settings.ts    → GET /restapi/user/settings
+└── admin/
+    └── users.ts       → GET /restapi/admin/users
+```
+
+- 파일명이 endpoint로 변환됩니다 (`.ts`, `.js` 확장자 제거)
+- 디렉토리는 경로의 일부가 됩니다
+- 각 파일은 Express Router를 export해야 합니다
+
+## 라우트 파일 작성법
+
+각 라우트 파일은 Express Router를 export해야 합니다:
+
+```typescript
+import express, { Request, Response } from 'express';
+
+const router = express.Router();
+
+// GET /restapi/example
+router.get('/', (req: Request, res: Response) => {
+  res.json({ message: 'Hello World' });
+});
+
+// POST /restapi/example
+router.post('/', (req: Request, res: Response) => {
+  res.json({ message: 'Created' });
+});
+
+export = router;
+// 또는
+export default router;
+```
+
+## 프로젝트 구조 예시
+
+```
+my-backend-project/
+├── src/
+│   ├── app.ts              # Express 앱 설정
+│   ├── server.ts           # 서버 시작 (선택적)
+│   └── restapi/            # API 라우트 파일들
+│       ├── health.ts       # GET /restapi/health
+│       ├── user/
+│       │   └── profile.ts  # GET /restapi/user/profile
+│       └── admin/
+│           └── users.ts    # GET /restapi/admin/users
+├── dist/                   # TypeScript 컴파일 결과
+├── tsconfig.json
+├── package.json
+└── .env
+```
+
+## 환경변수
+
+`.env` 파일에서 설정할 수 있는 환경변수:
+
+```env
+NODE_ENV=development
+PORT=4000
+CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:5173
+```
+
+## TypeScript 설정
+
+권장 `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## 라이센스
+
+ISC
+
+## 기여
+
+버그 리포트 및 기능 제안은 이슈로 등록해주세요.
+
+## 관련 프로젝트
+
+이 패키지는 [zium-backend](https://github.com/your-org/zium-backend) 프로젝트의 구조를 기반으로 만들어졌습니다.

package/bin/xplat-back

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli/index.js');

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const init_1 = require("./init");
+/**
+ * CLI 진입점
+ */
+async function main() {
+    try {
+        const args = process.argv.slice(2);
+        // 간단한 옵션 파싱
+        const config = {};
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            switch (arg) {
+                case '--port':
+                case '-p':
+                    config.port = args[++i];
+                    break;
+                case '--cors':
+                case '-c':
+                    config.corsOrigins = args[++i];
+                    break;
+                case '--router-dir':
+                case '-r':
+                    config.routerDirectory = args[++i];
+                    break;
+                case '--router-path':
+                    config.routerBasePath = args[++i];
+                    break;
+                case '--help':
+                case '-h':
+                    showHelp();
+                    process.exit(0);
+                    break;
+                default:
+                    if (!arg.startsWith('-')) {
+                        config.projectName = arg;
+                    }
+            }
+        }
+        await (0, init_1.initializeProject)(config);
+    }
+    catch (error) {
+        console.error('❌ 초기화 중 오류가 발생했습니다:', error.message);
+        if (process.env.DEBUG) {
+            console.error(error);
+        }
+        process.exit(1);
+    }
+}
+/**
+ * 도움말 출력
+ */
+function showHelp() {
+    console.log(`
+xplat-back CLI
+
+Usage:
+  xplat-back [options] [project-name]
+
+Options:
+  -p, --port <port>              서버 포트 (기본값: 4000)
+  -c, --cors <origins>           CORS 허용 origins (쉼표로 구분, 기본값: http://localhost:3000)
+  -r, --router-dir <directory>   라우터 디렉토리 (기본값: src/restapi)
+      --router-path <path>       라우터 base path (기본값: /restapi)
+  -h, --help                     도움말 출력
+
+Examples:
+  xplat-back
+  xplat-back my-project
+  xplat-back --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+  `);
+}
+// CLI 실행
+if (require.main === module) {
+    main();
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 초기화 설정 인터페이스
+ */
+export interface InitConfig {
+    projectName?: string;
+    port?: string;
+    corsOrigins?: string;
+    routerDirectory?: string;
+    routerBasePath?: string;
+}
+/**
+ * 프로젝트 초기화 로직
+ *
+ * @param config 초기화 설정
+ */
+export declare function initializeProject(config?: InitConfig): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,264 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeProject = initializeProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 프로젝트 초기화 로직
+ *
+ * @param config 초기화 설정
+ */
+async function initializeProject(config = {}) {
+    const projectRoot = process.cwd();
+    const projectName = config.projectName || path.basename(projectRoot);
+    const port = config.port || '4000';
+    const corsOrigins = config.corsOrigins || 'http://localhost:3000';
+    const routerDirectory = config.routerDirectory || 'src/restapi';
+    const routerBasePath = config.routerBasePath || '/restapi';
+    console.log('\n🚀 xplat-back 프로젝트 초기화를 시작합니다...\n');
+    // src 디렉토리 생성
+    const srcDir = path.join(projectRoot, 'src');
+    if (!fs.existsSync(srcDir)) {
+        fs.mkdirSync(srcDir, { recursive: true });
+        console.log(`✅ src 디렉토리가 생성되었습니다.`);
+    }
+    // restapi 디렉토리 생성
+    const restapiDir = path.join(projectRoot, routerDirectory);
+    if (!fs.existsSync(restapiDir)) {
+        fs.mkdirSync(restapiDir, { recursive: true });
+        console.log(`✅ ${routerDirectory} 디렉토리가 생성되었습니다.`);
+    }
+    // app.ts 파일 생성
+    await createAppFile(projectRoot, port, corsOrigins, routerDirectory, routerBasePath);
+    // server.ts 파일 생성 (선택적)
+    await createServerFile(projectRoot, port, corsOrigins, routerDirectory, routerBasePath);
+    // tsconfig.json 파일 생성
+    await createTsConfigFile(projectRoot);
+    // package.json 파일 생성 (없는 경우만)
+    await createPackageJsonFile(projectRoot, projectName);
+    // .env 파일 생성
+    await createEnvFile(projectRoot, port, corsOrigins);
+    // 예시 라우트 파일 생성
+    await createExampleRouteFile(restapiDir);
+    console.log('\n✅ 프로젝트 초기화가 완료되었습니다!');
+    console.log(`\n생성된 파일:`);
+    console.log(`  - src/app.ts`);
+    console.log(`  - src/server.ts (선택적)`);
+    console.log(`  - tsconfig.json`);
+    console.log(`  - package.json (없던 경우만)`);
+    console.log(`  - .env`);
+    console.log(`  - ${routerDirectory}/health.ts`);
+    console.log(`\n다음 단계:`);
+    console.log(`  1. npm install (또는 yarn install)`);
+    console.log(`  2. npm run dev (또는 yarn dev)로 서버 실행`);
+    console.log(`  3. ${routerDirectory} 디렉토리에 API 라우트 파일을 추가하세요\n`);
+}
+/**
+ * app.ts 파일 생성
+ */
+async function createAppFile(projectRoot, port, corsOrigins, routerDirectory, routerBasePath) {
+    const appFilePath = path.join(projectRoot, 'src', 'app.ts');
+    if (fs.existsSync(appFilePath)) {
+        console.log(`⚠️  src/app.ts 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const appContent = `import express, { Application } from 'express';
+import * as path from 'path';
+import { createApp } from 'xplat-back';
+
+const app: Application = createApp({
+  cors: {
+    origin: process.env.CORS_ALLOW_ORIGINS
+      ? process.env.CORS_ALLOW_ORIGINS.split(',').map(s => s.trim())
+      : ['${corsOrigins}'],
+    credentials: true,
+  },
+  router: {
+    directory: path.join(__dirname, '${routerDirectory.replace('src/', '')}'),
+    basePath: '${routerBasePath}',
+  },
+  trustProxy: true,
+});
+
+const port = parseInt(process.env.PORT || '${port}', 10);
+
+app.listen(port, () => {
+  console.log(\`🚀 Server is running on port \${port}\`);
+  console.log(\`📡 API endpoint: http://localhost:\${port}${routerBasePath}\`);
+});
+
+export default app;
+`;
+    fs.writeFileSync(appFilePath, appContent, 'utf-8');
+    console.log(`✅ src/app.ts 파일이 생성되었습니다.`);
+}
+/**
+ * server.ts 파일 생성 (선택적)
+ */
+async function createServerFile(projectRoot, port, corsOrigins, routerDirectory, routerBasePath) {
+    const serverFilePath = path.join(projectRoot, 'src', 'server.ts');
+    if (fs.existsSync(serverFilePath)) {
+        console.log(`⚠️  src/server.ts 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const serverContent = `import * as path from 'path';
+import { createApp } from 'xplat-back';
+
+/**
+ * 서버 시작 함수
+ */
+async function startServer() {
+  const app = createApp({
+    cors: {
+      origin: process.env.CORS_ALLOW_ORIGINS
+        ? process.env.CORS_ALLOW_ORIGINS.split(',').map(s => s.trim())
+        : ['${corsOrigins}'],
+      credentials: true,
+    },
+    router: {
+      directory: path.join(__dirname, '${routerDirectory.replace('src/', '')}'),
+      basePath: '${routerBasePath}',
+    },
+    trustProxy: true,
+  });
+
+  const port = parseInt(process.env.PORT || '${port}', 10);
+
+  app.listen(port, () => {
+    console.log(\`🚀 Server is running on port \${port}\`);
+    console.log(\`📡 API endpoint: http://localhost:\${port}${routerBasePath}\`);
+  });
+
+  return app;
+}
+
+// 서버 시작
+if (require.main === module) {
+  startServer().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  });
+}
+
+export default startServer;
+`;
+    fs.writeFileSync(serverFilePath, serverContent, 'utf-8');
+    console.log(`✅ src/server.ts 파일이 생성되었습니다.`);
+}
+/**
+ * tsconfig.json 파일 생성
+ */
+async function createTsConfigFile(projectRoot) {
+    const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+    if (fs.existsSync(tsconfigPath)) {
+        console.log(`⚠️  tsconfig.json 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const templatePath = path.join(__dirname, 'templates', 'tsconfig.json.example');
+    const templateContent = fs.readFileSync(templatePath, 'utf-8');
+    fs.writeFileSync(tsconfigPath, templateContent, 'utf-8');
+    console.log(`✅ tsconfig.json 파일이 생성되었습니다.`);
+}
+/**
+ * package.json 파일 생성 (없는 경우만)
+ */
+async function createPackageJsonFile(projectRoot, projectName) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        console.log(`⚠️  package.json 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const packageJsonContent = {
+        name: projectName.toLowerCase().replace(/\s+/g, '-'),
+        version: '0.1.0',
+        description: 'Backend project generated with xplat-back',
+        main: 'dist/app.js',
+        scripts: {
+            build: 'tsc',
+            dev: 'ts-node -r tsconfig-paths/register src/app.ts',
+            start: 'node dist/app.js',
+            clean: 'rm -rf dist',
+        },
+        dependencies: {
+            express: '^4.18.2',
+            'xplat-back': '^0.1.0',
+        },
+        devDependencies: {
+            '@types/express': '^4.17.21',
+            '@types/node': '^20.10.0',
+            'ts-node': '^10.9.2',
+            'tsconfig-paths': '^4.2.0',
+            typescript: '^5.3.3',
+        },
+    };
+    fs.writeFileSync(packageJsonPath, JSON.stringify(packageJsonContent, null, 2) + '\n', 'utf-8');
+    console.log(`✅ package.json 파일이 생성되었습니다.`);
+}
+/**
+ * .env 파일 생성
+ */
+async function createEnvFile(projectRoot, port, corsOrigins) {
+    const envPath = path.join(projectRoot, '.env');
+    if (fs.existsSync(envPath)) {
+        console.log(`⚠️  .env 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const envContent = `# Application Configuration
+NODE_ENV=development
+PORT=${port}
+
+# CORS Configuration
+CORS_ALLOW_ORIGINS=${corsOrigins}
+
+# Add your environment variables below
+`;
+    fs.writeFileSync(envPath, envContent, 'utf-8');
+    console.log(`✅ .env 파일이 생성되었습니다.`);
+}
+/**
+ * 예시 라우트 파일 생성
+ */
+async function createExampleRouteFile(restapiDir) {
+    const healthPath = path.join(restapiDir, 'health.ts');
+    if (fs.existsSync(healthPath)) {
+        console.log(`⚠️  health.ts 파일이 이미 존재합니다. 건너뜁니다.`);
+        return;
+    }
+    const templatePath = path.join(__dirname, 'templates', 'restapi', 'health.ts.example');
+    const templateContent = fs.readFileSync(templatePath, 'utf-8');
+    fs.writeFileSync(healthPath, templateContent, 'utf-8');
+    console.log(`✅ health.ts 파일이 생성되었습니다.`);
+}

package/dist/cli/templates/app.ts.example

@@ -0,0 +1,26 @@
+import express, { Application } from 'express';
+import * as path from 'path';
+import { createApp } from 'xplat-back';
+
+const app: Application = createApp({
+  cors: {
+    origin: process.env.CORS_ALLOW_ORIGINS
+      ? process.env.CORS_ALLOW_ORIGINS.split(',').map(s => s.trim())
+      : ['http://localhost:3000'],
+    credentials: true,
+  },
+  router: {
+    directory: path.join(__dirname, 'restapi'),
+    basePath: '/restapi',
+  },
+  trustProxy: true,
+});
+
+const port = parseInt(process.env.PORT || '4000', 10);
+
+app.listen(port, () => {
+  console.log(`🚀 Server is running on port ${port}`);
+  console.log(`📡 API endpoint: http://localhost:${port}/restapi`);
+});
+
+export default app;

package/dist/cli/templates/package.json.example

@@ -0,0 +1,23 @@
+{
+  "name": "my-backend-project",
+  "version": "0.1.0",
+  "description": "Backend project generated with xplat-back",
+  "main": "dist/app.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node -r tsconfig-paths/register src/app.ts",
+    "start": "node dist/app.js",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "xplat-back": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.3.3"
+  }
+}

package/dist/cli/templates/restapi/health.ts.example

@@ -0,0 +1,17 @@
+import express, { Request, Response } from 'express';
+
+const router = express.Router();
+
+/**
+ * 헬스 체크 엔드포인트
+ * GET /restapi/health
+ */
+router.get('/', (req: Request, res: Response) => {
+  res.json({
+    success: true,
+    message: 'Server is healthy',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+export = router;

package/dist/cli/templates/server.ts.example

@@ -0,0 +1,40 @@
+import * as path from 'path';
+import { createApp } from 'xplat-back';
+
+/**
+ * 서버 시작 함수
+ */
+async function startServer() {
+  const app = createApp({
+    cors: {
+      origin: process.env.CORS_ALLOW_ORIGINS
+        ? process.env.CORS_ALLOW_ORIGINS.split(',').map(s => s.trim())
+        : ['http://localhost:3000'],
+      credentials: true,
+    },
+    router: {
+      directory: path.join(__dirname, 'restapi'),
+      basePath: '/restapi',
+    },
+    trustProxy: true,
+  });
+
+  const port = parseInt(process.env.PORT || '4000', 10);
+
+  app.listen(port, () => {
+    console.log(`🚀 Server is running on port ${port}`);
+    console.log(`📡 API endpoint: http://localhost:${port}/restapi`);
+  });
+
+  return app;
+}
+
+// 서버 시작
+if (require.main === module) {
+  startServer().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  });
+}
+
+export default startServer;

package/dist/cli/templates/tsconfig.json.example

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/createApp.d.ts

@@ -0,0 +1,32 @@
+import { Application } from 'express';
+import { AppConfig } from './types';
+/**
+ * Express 앱 생성 함수
+ *
+ * zium-backend의 app.ts 구조를 기반으로 한 Express 애플리케이션을 생성합니다.
+ * 파일명과 API endpoint가 자동으로 일치하도록 라우팅 시스템을 포함합니다.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'xplat-back';
+ *
+ * const app = createApp({
+ *   cors: {
+ *     origin: ['http://localhost:3000'],
+ *     credentials: true
+ *   },
+ *   router: {
+ *     directory: path.join(__dirname, 'restapi'),
+ *     basePath: '/restapi'
+ *   }
+ * });
+ *
+ * app.listen(4000, () => {
+ *   console.log('Server is running on port 4000');
+ * });
+ * ```
+ *
+ * @param config - 앱 설정 옵션
+ * @returns Express Application 인스턴스
+ */
+export declare function createApp(config?: AppConfig): Application;

package/dist/createApp.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
+const express_1 = __importDefault(require("express"));
+const cookie_parser_1 = __importDefault(require("cookie-parser"));
+const cors_1 = __importDefault(require("cors"));
+const path = __importStar(require("path"));
+const route_1 = require("./util/route");
+/**
+ * Express 앱 생성 함수
+ *
+ * zium-backend의 app.ts 구조를 기반으로 한 Express 애플리케이션을 생성합니다.
+ * 파일명과 API endpoint가 자동으로 일치하도록 라우팅 시스템을 포함합니다.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'xplat-back';
+ *
+ * const app = createApp({
+ *   cors: {
+ *     origin: ['http://localhost:3000'],
+ *     credentials: true
+ *   },
+ *   router: {
+ *     directory: path.join(__dirname, 'restapi'),
+ *     basePath: '/restapi'
+ *   }
+ * });
+ *
+ * app.listen(4000, () => {
+ *   console.log('Server is running on port 4000');
+ * });
+ * ```
+ *
+ * @param config - 앱 설정 옵션
+ * @returns Express Application 인스턴스
+ */
+function createApp(config = {}) {
+    const app = (0, express_1.default)();
+    // Trust proxy 설정 (실제 IP를 얻기 위해)
+    if (config.trustProxy !== false) {
+        app.set('trust proxy', true);
+    }
+    // CORS 설정
+    app.use((req, res, next) => {
+        res.vary('Origin');
+        next();
+    });
+    const corsOrigin = config.cors?.origin ||
+        (process.env.CORS_ALLOW_ORIGINS
+            ? process.env.CORS_ALLOW_ORIGINS.split(',').map(s => s.trim())
+            : ['*']);
+    app.use((0, cors_1.default)({
+        origin: typeof corsOrigin === 'function'
+            ? corsOrigin
+            : corsOrigin,
+        credentials: config.cors?.credentials !== false,
+    }));
+    // Body parser 설정
+    app.use(express_1.default.json({ limit: config.json?.limit || '1mb' }));
+    app.use(express_1.default.urlencoded({
+        extended: config.urlencoded?.extended !== false
+    }));
+    // Cookie parser 설정
+    app.use((0, cookie_parser_1.default)());
+    // 커스텀 미들웨어 적용
+    if (config.middleware && config.middleware.length > 0) {
+        config.middleware.forEach(middleware => {
+            app.use(middleware);
+        });
+    }
+    // 라우터 등록
+    if (config.router?.directory) {
+        const routerDirectory = config.router.directory;
+        const basePath = config.router.basePath || '/restapi';
+        // 절대 경로가 아니면 현재 작업 디렉토리를 기준으로 해석
+        const absoluteRouterDirectory = path.isAbsolute(routerDirectory)
+            ? routerDirectory
+            : path.join(process.cwd(), routerDirectory);
+        try {
+            const router = (0, route_1.createRouter)(absoluteRouterDirectory);
+            app.use(basePath, router);
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to load router from directory "${absoluteRouterDirectory}". ` +
+                `Make sure the directory exists and contains route files.`);
+        }
+    }
+    // 404 핸들러
+    app.use((req, res) => {
+        res.status(404).json({
+            success: false,
+            message: 'Not Found',
+            path: req.path,
+        });
+    });
+    // 에러 핸들러
+    app.use((err, req, res, next) => {
+        console.error('Error:', err);
+        res.status(500).json({
+            success: false,
+            message: process.env.NODE_ENV === 'production'
+                ? 'Internal Server Error'
+                : err.message,
+            ...(process.env.NODE_ENV !== 'production' && { stack: err.stack }),
+        });
+    });
+    return app;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * xplat-back
+ *
+ * Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)
+ *
+ * 파일명과 API endpoint가 자동으로 일치하는 라우팅 시스템을 제공합니다.
+ *
+ * @packageDocumentation
+ */
+export { createRouter } from './util/route';
+export { createApp } from './createApp';
+export type { AppConfig, ExtendedRequest, ExtendedResponse, } from './types';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * xplat-back
+ *
+ * Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)
+ *
+ * 파일명과 API endpoint가 자동으로 일치하는 라우팅 시스템을 제공합니다.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = exports.createRouter = void 0;
+// 라우팅 유틸리티
+var route_1 = require("./util/route");
+Object.defineProperty(exports, "createRouter", { enumerable: true, get: function () { return route_1.createRouter; } });
+// Express 앱 생성 함수
+var createApp_1 = require("./createApp");
+Object.defineProperty(exports, "createApp", { enumerable: true, get: function () { return createApp_1.createApp; } });

package/dist/types/index.d.ts

@@ -0,0 +1,75 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Express 앱 설정 옵션
+ */
+export interface AppConfig {
+    /**
+     * CORS 설정
+     */
+    cors?: {
+        /**
+         * 허용할 origin 목록 (문자열 배열 또는 함수)
+         * 기본값: process.env.CORS_ALLOW_ORIGINS를 쉼표로 분리한 배열, 또는 ['*']
+         */
+        origin?: string[] | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+        /**
+         * Credentials 허용 여부
+         * 기본값: true
+         */
+        credentials?: boolean;
+    };
+    /**
+     * JSON body parser 설정
+     */
+    json?: {
+        /**
+         * 최대 body 크기
+         * 기본값: '1mb'
+         */
+        limit?: string;
+    };
+    /**
+     * URL encoded body parser 설정
+     */
+    urlencoded?: {
+        /**
+         * extended 옵션
+         * 기본값: true
+         */
+        extended?: boolean;
+    };
+    /**
+     * 라우터 설정
+     */
+    router?: {
+        /**
+         * 라우트 파일들이 위치한 디렉토리 경로
+         * 기본값: 'src/restapi'
+         */
+        directory?: string;
+        /**
+         * 라우터를 등록할 base path
+         * 기본값: '/restapi'
+         */
+        basePath?: string;
+    };
+    /**
+     * Trust proxy 설정
+     * 기본값: true
+       */
+    trustProxy?: boolean;
+    /**
+     * 커스텀 미들웨어 함수들
+     */
+    middleware?: Array<(req: Request, res: Response, next: NextFunction) => void>;
+}
+/**
+ * 확장된 Express Request 타입
+ */
+export interface ExtendedRequest extends Request {
+}
+/**
+ * 확장된 Express Response 타입
+ */
+export interface ExtendedResponse extends Response {
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/util/route.d.ts

@@ -0,0 +1,24 @@
+import express from 'express';
+/**
+ * 파일 경로 기준 동적 라우터 생성
+ *
+ * 디렉토리 구조를 API endpoint로 자동 매핑합니다.
+ *
+ * @example
+ * // 디렉토리 구조:
+ * // restapi/
+ * //   ├── health.ts
+ * //   ├── user/
+ * //   │   └── profile.ts
+ * //   └── admin/
+ * //       └── users.ts
+ *
+ * // 결과:
+ * // /restapi/health → restapi/health.ts
+ * // /restapi/user/profile → restapi/user/profile.ts
+ * // /restapi/admin/users → restapi/admin/users.ts
+ *
+ * @param directory - 라우트 파일들이 위치한 루트 디렉토리
+ * @returns Express Router 인스턴스
+ */
+export declare function createRouter(directory: string): express.Router;

package/dist/util/route.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouter = createRouter;
+const express_1 = __importDefault(require("express"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 파일 경로 기준 동적 라우터 생성
+ *
+ * 디렉토리 구조를 API endpoint로 자동 매핑합니다.
+ *
+ * @example
+ * // 디렉토리 구조:
+ * // restapi/
+ * //   ├── health.ts
+ * //   ├── user/
+ * //   │   └── profile.ts
+ * //   └── admin/
+ * //       └── users.ts
+ *
+ * // 결과:
+ * // /restapi/health → restapi/health.ts
+ * // /restapi/user/profile → restapi/user/profile.ts
+ * // /restapi/admin/users → restapi/admin/users.ts
+ *
+ * @param directory - 라우트 파일들이 위치한 루트 디렉토리
+ * @returns Express Router 인스턴스
+ */
+function createRouter(directory) {
+    const router = express_1.default.Router();
+    const files = fs.readdirSync(directory);
+    for (const file of files) {
+        const filePath = path.join(directory, file);
+        if (fs.statSync(filePath).isDirectory()) {
+            // 디렉토리인 경우 재귀적으로 라우터 생성
+            const subRouter = createRouter(filePath);
+            router.use(`/${file}`, subRouter);
+        }
+        else {
+            // 파일인 경우 라우터 생성
+            if (file.endsWith('.ts') || file.endsWith('.js')) {
+                const routePath = `/${file.replace('.ts', '').replace('.js', '')}`;
+                const required = require(filePath);
+                const routeModule = required.default || required;
+                router.use(routePath, routeModule);
+            }
+        }
+    }
+    return router;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hamjimin/xplat-back",
+  "version": "0.1.0",
+  "description": "Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "xplat-back": "./bin/xplat-back"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "copy-templates": "mkdir -p dist/cli/templates && cp -r src/cli/templates/* dist/cli/templates/",
+    "prebuild": "npm run copy-templates",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "backend",
+    "scaffolding",
+    "router",
+    "api",
+    "framework"
+  ],
+  "author": "xplat",
+  "license": "ISC",
+  "dependencies": {
+    "express": "^4.18.2",
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "@types/cookie-parser": "^1.4.6",
+    "@types/cors": "^2.8.17",
+    "typescript": "^5.3.3"
+  }
+}