gaonjs (가온)

AI가 개발을 가장 잘하는 Node.js 풀스택 웹 프레임웍.

Gaon은 "정답이 하나(The One Way)"를 지향합니다 — 흔한 작업마다 관례가 하나로 정해져 있어, 사람도 AI도 헤매지 않고 첫 시도에 동작하는 코드를 씁니다. 타입은 스키마 → 모델 → 컨트롤러 → 페이지까지 자동으로 흐르고, 인증·실시간·잡·메일 등 배터리가 기본 포함됩니다.

ℹ️ 설치명은 gaonjs, CLI 명령은 gaon 입니다. (npm 패키지명 gaon 은 유사도 정책으로 점유 불가 → 파사드 패키지명을 gaonjs 로 확정.)

설치 → 첫 화면까지 (약 60초)

gaon new my-app              # 새 프로젝트 스캐폴드 (파일 → 설치 → git init)
                             #   설치 없이: npx gaonjs new my-app
cd my-app
gaon dev                     # 개발 스택 통합 기동 (Docker · .gaon 생성 · serve · 워처)

gaon dev 는 Docker Compose(DB·Redis·NATS 등)를 띄우고, 타입 브리지(.gaon/)를 생성하고, 웹 서버를 부팅하고, 코드 변경을 감시해 재시작까지 합니다. 브라우저에서 개발 랜딩이 뜨면 준비 완료입니다. (운영은 감시 없는 gaon serve.)

핵심 개념

• 배터리 포함 — 인증(세션·JWT), 실시간(채널·프레즌스·gaon hub), 비동기 잡 (NATS JetStream·아웃박스·크론), 메일, 파일 스토리지, i18n 이 코어에 들어 있습니다. gaon g auth 한 번이면 회원가입·로그인·세션·보호 라우트가 스캐폴드됩니다.
• 타입이 끝까지 흐른다 — domain/schema 의 컬럼을 지우면, 그 컬럼을 쓰는 .vue 페이지에서 vue-tsc 가 컴파일 에러를 냅니다. 스키마 → model() → 컨트롤러 render props → 페이지 pageProps<'app:ctrl#action'>() 까지 타입 브리지(.gaon/)로 자동 연결됩니다.
• 프론트는 Inertia SPA — 별도 REST 엔드포인트도, 클라이언트 라우터도 없습니다. 컨트롤러가 this.render('Posts/Index', props) 로 Vue 페이지에 props 를 넘기고, 폼은 useForm(...), 페이지 이동은 Link/router.visit 를 씁니다.
• 보안 기본 켬 — CORS·rate limit·CSRF 가 기본 활성화됩니다(끄는 것만 명시 설정).
• The One Way — 선택지가 생기면 정답이 하나가 되는 쪽을 고릅니다. 탈출구는 남기되 기본 경로에서는 아무것도 고르지 않게 합니다.

프로젝트 구조

my-app/
├─ domain/            # schema · models · services · jobs · events · mails · seed
├─ apps/<이름>/       # app.config.ts · routes.ts · controllers · pages · components
├─ shared/            # 앱 간 공유 (라우트를 모르는 순수 UI/유틸)
├─ gaon.config.ts     # DB 등 공통 설정
└─ compose.yaml       # 개발 인프라 (Docker)

개발자는 gaonjs 하나만 설치합니다 — 내부는 @gaonjs/* 로 모듈화돼 있고, 파사드 서브패스로 가져옵니다: gaonjs/web · gaonjs/data · gaonjs/vue · gaonjs/async · gaonjs/mail · gaonjs/storage · gaonjs/i18n · gaonjs/service.

주요 CLI

gaon new <name>      # 새 프로젝트 스캐폴드
gaon dev             # 개발 스택 통합 (Docker · .gaon · serve · 워처)
gaon g auth          # 인증 배터리 스캐폴드
gaon g <타입> …      # controller · model · page · job · app · ui-kit 생성
gaon db migrate      # 마이그레이션 (diff · migrate · status · seed · reset)
gaon check           # typecheck · vue-tsc · build 통합 검사
gaon doctor          # 정적 검사 (관례 위반·안티패턴 · --fix)
gaon serve           # 운영 웹 서버 부팅 (감시 없음)
gaon work / gaon hub # 비동기 워커 · 실시간 허브

모든 명령은 --json 출력을 지원합니다(자동화·CI).

AI 네이티브

Gaon 은 AI 에이전트가 첫 시도에 정답을 쓰도록 설계됐습니다. gaon new 는 프로젝트에 AGENTS.md + agents/*.md(관례 정본 · doctor 검사 목록 포함)를 함께 스캐폴드하므로, Claude Code 같은 에이전트가 그 규칙을 그대로 따릅니다. gaon mcp(MCP 도구)로 에이전트에 프레임웍 능력을 노출할 수도 있습니다.

• 홈페이지 / 문서: https://gaonjs.dev
• 라이선스: MIT