framework

Croco Framework는 AWS Lambda와 API Gateway를 1급 시민으로 취급하는 Node.js 기반 TypeScript 프레임워크다. README는 스스로를 '주관이 뚜렷한(opinionated)' 프레임워크로 소개하며, 대규모 프로젝트에서 아키텍처 일관성을 유지하기 어렵다는 문제의식에서 역할별 패키지 경계를 명시적으로 나눈다. 패키지는 Kernel(프레임워크 런타임 기반: framework-context, framework-module), Contracts(provider·런타임 독립 도메인/프로토콜 계약: repository-core, protocols-rest, telemetry-api), Plugins(계약의 구현과 환경 바인딩: tx-drizzle, transports-http, preset-node), Application(앱 소유 모듈과 composition root), Profiles(검증된 plugin/module 조합: presentation-preset), Tooling(build, codegen, testing, CLI)의 6가지 역할로 분류된다. Kernel과 Contracts는 구체 Plugin에 의존하지 않으며, 문서에 따르면 역할의 기준 정보는 docs/package-catalog.json의 packageRoles다. Host·Transport·Build Target을 구분하는 점이 특징이다. Host는 Node process/server, Lambda invocation, Workers fetch 수명주기를 소유하고(preset-node, preset-lambda, preset-cloudflare), Transport는 HTTP·GraphQL·RPC 같은 프로토콜 표면을 실행하며, Build Target은 entrypoint·출력 디렉터리·module format·번들링 제약을 선언하는 Tooling 계약이다. Host 하나가 여러 Transport 콜백을 바인딩할 수 있다. 기능으로는 DDD 도메인 이벤트(events-core)와 RegisterEventHandler, Unit of Work 방식의 Transactional 트랜잭션(tx-core, AsyncLocalStorage 전파), RFC 7807 기반 Problem 응답 문제 상세화(problems-core), 재시도·복구 데코레이터(Retryable, Recover — retry-core), OpenTelemetry Span을 생성하는 Trace(telemetry-api), 데코레이터 기반 DI 컨테이너(framework-context)를 제공한다. REST 컨트롤러는 Controller/Get/Post 데코레이터로 정의하고 createApp과 createLambdaHost로 Lambda 핸들러를 구성한다. SaaS 도메인을 겨냥해 빌링·엔타이틀먼트·크레딧·미터링·고객 상태 등 계약 패키지와 Polar, Clerk, Drizzle, PostHog, QStash 같은 provider·integration 패키지가 함께 제공된다. 문서는 실패를 일반 Error나 silent fallback으로 숨기지 않고 Problem, retry, timeout, circuit breaker, idempotency, exhaustive handling으로 모델링하는 것을 원칙으로 내세운다. 시작 경로는 npx create-croco-app@latest로 스캐폴딩하고(예: --goal saas-api) pnpm demo:smoke로 외부 자격증명 없이 생성된 REST 계약과 인메모리 SaaS 흐름을 검증하는 방식이며, examples/quick-start-lambda에서 Auth와 Metering이 포함된 예제를 pnpm dev로 실행할 수 있다. 라우트 A는 문서 기반 스캐폴드 가이드, 라우트 B는 완성 예제 실행이다. README에 따르면 카탈로그는 public package 120개를 추적하고(비공개 2개 제외), 1.0 spine으로 18개 패키지를 release-critical 호환 범위로 고정한다. 그중 10개는 production-ready, 8개는 beta이며 alpha/WIP와 deprecated는 0개다. 성숙도·그룹 정보는 저장소 메타데이터에서 생성되는 산출물이고, drift가 생기면 docs:catalog:check가 실패한다고 설명한다. 벤치마크는 benchmarks/ 디렉터리에서 방법론·기준선·임계값을 관리하고 전용 workflow에서 최근 5회 green evidence를 기반으로 blocking gate로 동작한다고 서술하지만, 구체적 성능 수치는 README에 제시되지 않는다. NestJS·Hono·tRPC와의 비교표 역시 성능 수치나 경쟁사 평가가 아니라 설계 중심 차이를 설명하기 위한 것이라고 명시한다.