@fursys/create-app

퍼시스홀딩스 사내 표준 프로젝트 스캐폴드 CLI. 한 줄 명령으로 사내 Coolify 배포 표준(Dockerfile · 환경변수 컨벤션 · Health Check) 을 사전 만족하는 Next.js 15 + TypeScript + Tailwind + shadcn/ui 프로젝트를 생성합니다.

사용법

가장 간단한 한 줄

npm create @fursys/app@latest my-dashboard

실행하면 먼저 "무엇을 만드시나요?" 를 물어보고, 용도에 맞는 프리셋을 생성합니다:

| 선택 | 프리셋 | 스택 | |------|--------|------| | 웹 서비스 | web-next | Next.js 15 (사내 데이터·DB·외부 API 연결) | | 데이터 분석 | data-fastapi | FastAPI + pandas (엑셀·CSV·DB 분석/시각화) | | 경량 대시보드 | dashboard-vite | Vite + React (연결 없이 화면만, 정적) |

그다음 자동으로:

1. 선택한 프리셋의 사내 표준 보일러플레이트 복사
2. 의존성 자동 설치 (web-next/dashboard-vite 는 npm install, data-fastapi 는 venv 안내)
3. git init (선택)

# 비대화형으로 용도를 바로 지정하려면 --type
npx --yes @fursys/create-app@latest my-app --type web-next
npx --yes @fursys/create-app@latest my-dash --type dashboard-vite
npx --yes @fursys/create-app@latest my-data --type data-fastapi

옵션

# 인터랙티브 (이름 안 적으면 물어봐요)
npm create @fursys/app@latest

# 자동 install 건너뛰기
npx --yes @fursys/create-app@latest my-dashboard --no-install

# Git 초기화도 건너뛰기
npx --yes @fursys/create-app@latest my-dashboard --no-git

# fgdw(사내 MSSQL Data Warehouse) 연결 스캐폴딩 포함/제외 (web-next·data-fastapi 만)
#   플래그를 주면 "fgdw 쓰세요?" 프롬프트를 생략합니다.
npx --yes @fursys/create-app@latest my-app --type web-next --fgdw
npx --yes @fursys/create-app@latest my-app --type web-next --no-fgdw

처음 사용하시는 분께 (Node.js 설치)

Windows

nodejs.org 에서 LTS 버전을 다운로드 후 설치하시거나, 사내 winget 이 가능하면:

winget install OpenJS.NodeJS.LTS

설치 후 새 PowerShell / cmd 창을 열어주세요. 그리고 버전 확인:

node --version    # v20.x 이상이면 OK
npm --version

macOS

brew install node@20
# 또는 nvm 사용자라면
nvm install --lts && nvm use --lts

만들어지는 것 (웹 서비스 / web-next 프리셋 기준)

아래는 기본 프리셋인 웹 서비스의 구성입니다. 데이터 분석(FastAPI)·경량 대시보드(Vite)는 각 프리셋의 README.md/AGENTS.md 를 참고하세요. 세 프리셋 모두 사내 Coolify 배포 표준(Dockerfile · Health Check · 시크릿 규칙)을 만족합니다.

• Next.js 15 (Page Router) + React 19 + TypeScript
• Tailwind CSS + shadcn/ui (Button, Card 기본 포함)
• 헤더 + 카드 3개 샘플 대시보드 (src/pages/index.tsx)
• API Routes 샘플 — /api/healthz, /api/hello
• 사내 Coolify 배포용 Dockerfile (Next.js standalone, 3-stage)
• AI 코딩 지침 파일 — AGENTS.md, CLAUDE.md (시크릿/UI/배포 사내 규칙 박혀있음. Claude Code / Kilo / Cursor 가 자동으로 참고)
• 한글 README + 사내 링크
• .env.example — 시크릿 보안 주석 포함

요구 사항

• Node.js 20 이상 (npm 도 함께 설치됨)
• 처음 사용 시 인터넷 연결 (라이브러리 다운로드)
• (배포 시) 사내 Coolify 접근 — Docker 는 로컬에 없어도 OK

CLI 동작 흐름

$ npm create @fursys/app@latest my-dashboard

  ┌──  퍼시스 사내 표준 프로젝트 생성  ──┐
  │  Next.js (Page Router) + TypeScript │
  │  Tailwind CSS + shadcn/ui           │
  │  사내 Coolify 배포 표준              │
  └─────────────────────────────────────┘

  ◇  템플릿 복사 완료
  ◇  라이브러리 설치 완료
  ◇  Git 초기화 완료

  ✓  완성되었어요!

AI 코딩 도구로 이어가기

생성된 프로젝트의 AGENTS.md / CLAUDE.md 에 사내 규칙(시크릿 처리, 변수명 컨벤션, UI 패턴, Coolify 배포 표준) 이 박혀있어요. Claude Code, Kilo, Cursor 같은 AI 도구로 이어서 작업하시면 첫 코드부터 사내 표준이 자연스럽게 적용됩니다.

만들어진 프로젝트가 통과하는 검사

본 스캐폴드 결과물은 사내 보안 검토 스킬 coolify-review v1.3.0 에서 Critical 0건, High 0건, ✅ 배포 가능 을 받습니다. 비개발자가 시작점부터 사내 정책을 안전하게 만족하도록 설계되었어요.

범위 (현재 v0.2.0)

• 3개 용도 프리셋: web-next(Next.js) · data-fastapi(FastAPI+pandas) · dashboard-vite(Vite 정적)
• CLI: 용도 선택(--type) + 프로젝트 이름 (인터랙티브 또는 인자)
• 프리셋별 의존성 자동 설치 + git init
• 각 프리셋에 AI 지침(AGENTS.md, CLAUDE.md) + 사내 Coolify 배포 표준 동봉
• MSSQL 커넥터 표준: web-next=mssql, data-fastapi=pymssql
• fgdw 옵션 (web-next·data-fastapi): "fgdw 쓰세요?" 선택 시 사내 MSSQL Data Warehouse 연결 헬퍼(FGDW_DB_* 표준 env + 드라이버 헬퍼)를 오버레이 (--fgdw / --no-fgdw)

다음 (예정)

• GitHub Actions 자동 publish (태그 push → npm publish)
• --with-ai 옵션 (Claude 기반)
• 경량 대시보드의 더 가벼운 변형(순수 HTML) 검토
• 자세한 계획: docs/create-app/PLAN.md

라이선스

사내 전용 — LICENSE 참고

문의: IT본부 AI추진팀 저장소: https://github.com/ai-admin-hub/fursys-create-app