framework

Croco Framework is a Node.js-based TypeScript framework that treats AWS Lambda and API Gateway as first-class citizens. Describing itself as 'opinionated,' the framework explicitly divides package boundaries by role to maintain architectural consistency in large-scale projects. Packages are classified into six roles: Kernel (framework runtime base: framework-context, framework-module), Contracts (provider/runtime-independent domain/protocol contracts: repository-core, protocols-rest, telemetry-api), Plugins (implementation of contracts and environment binding: tx-drizzle, transports-http, preset-node), Application (app-owned modules and composition root), Profiles (verified plugin/module combinations: presentation-preset), and Tooling (build, codegen, testing, CLI). The Kernel and Contracts do not depend on specific Plugins, and the role criteria are defined in the packageRoles of docs/package-catalog.json. A key feature is the distinction between Host, Transport, and Build Target. The Host owns the lifecycle of Node processes/servers, Lambda invocations, or Workers fetch (preset-node, preset-lambda, preset-cloudflare). The Transport executes protocol surfaces such as HTTP, GraphQL, or RPC. The Build Target is a Tooling contract declaring entry points, output directories, module formats, and bundling constraints. A single Host can bind multiple Transport callbacks. Functional offerings include DDD domain events (events-core) with RegisterEventHandler, Unit of Work style Transactional transactions (tx-core, propagated via AsyncLocalStorage), RFC 7807-based Problem response detailing (problems-core), retry and recovery decorators (Retryable, Recover — retry-core), Trace for generating OpenTelemetry Spans (telemetry-api), and a decorator-based DI container (framework-context). REST controllers are defined using Controller/Get/Post decorators, and Lambda handlers are configured via createApp and createLambdaHost. Targeting the SaaS domain, it provides contract packages for billing, entitlement, credits, metering, and customer status, along with provider/integration packages for Polar, Clerk, Drizzle, PostHog, and QStash. The documentation emphasizes a principle of modeling failures through Problem, retry, timeout, circuit breaker, idempotency, and exhaustive handling, rather than hiding them as general Errors or silent fallbacks. Getting started involves scaffolding via npx create-croco-app@latest (e.g., --goal saas-api) and verifying REST contracts and in-memory SaaS flows without external credentials using pnpm demo:smoke. Examples including Auth and Metering can be run via pnpm dev in examples/quick-start-lambda. According to the README, the catalog tracks 120 public packages, with 18 packages fixed within a release-critical compatibility range as the 1.0 spine. Among these, 10 are production-ready and 8 are beta. Maturity and group information are artifacts generated from repository metadata; any drift causes docs:catalog:check to fail. Benchmarks are managed in the benchmarks/ directory with methodologies, baselines, and thresholds, acting as a blocking gate based on the last five green evidence runs in a dedicated workflow, though specific performance figures are not listed in the README. A comparison table with NestJS, Hono, and tRPC is provided to explain design-centric differences rather than performance metrics or competitor evaluations.