API Starter

Fábrica de APIs HTTP en Bun + Hono: un repositorio base y un generador con el que crear APIs independientes (pequeña y pública, single-tenant, SaaS multi-tenant, plataforma de integraciones) con poda física de las capacidades que no uses.

Este repositorio no es una mega-API compartida: cada proyecto generado es un repositorio propio, autocontenido y sin dependencia en runtime de este starter.

¿Qué necesitas hacer?

Crear una API nueva

git clone https://github.com/JhonMA82/api-starter.git
cd api-starter
bun install --frozen-lockfile
bun run create:project -- --profile=minimal --out=../my-api
cd ../my-api
bun install
cp .env.example .env
bun run dev

Comprueba que responde: curl http://localhost:3000/health → {"status":"ok"}.

Elige otro perfil o una composición por features en la guía Elegir un perfil. El recorrido completo está en Crear un proyecto.

Mantener el starter

Guías para quien modifica este repositorio (base, generador, perfiles, CI o política de actualización): Documentación para mantenedores.

Elegir perfil

Necesidad	Perfil recomendado
API pública sin DB ni cuentas	minimal
API con persistencia sin usuarios	data-api
Aplicación single-tenant con usuarios	authenticated
SaaS con organizaciones, membresías y auditoría	multi-tenant-core
Multi-tenant con API keys, jobs y webhooks	integration-platform
Todas las capacidades disponibles	platform

multi-tenant está deprecated (usa multi-tenant-core, integration-platform o platform). Explicación por caso de uso y límites: choose-a-profile.md.

Qué incluye (resumen)

Configuración fail-fast, errores RFC 9457, OpenAPI 3.1 + Scalar, logging estructurado, autenticación Better Auth, autorización deny-by-default con auditoría append-only, multi-tenancy, outbox/jobs/API keys/webhooks, archivos con URLs firmadas, notificaciones, SDK TypeScript y operación (métricas, Docker no-root, backup/restore). Detalle: Capabilities.

Estado y requisitos

• Versión: 0.12.2 (fuente: package.json).
• Bun 1.4.0 (.bun-version; CI lo respeta). Podman o Docker solo para la base de datos local.
• Pins exactos de dependencias y bun.lock commiteado; catálogo en catalog/dependencies.json.

Arranque de este repositorio (mantenedores)

bun install           # instala los workspaces (bun.lock fijado)
cp .env.example .env  # plantilla de entorno; ajusta si hace falta
bun run dev           # servidor en watch en http://localhost:3000

Los valores obligatorios del repositorio completo son DATABASE_URL y BETTER_AUTH_SECRET (LOG_LEVEL por defecto info); en un proyecto generado, las obligatorias dependen del perfil (ver reference/environment.md). Para perfiles con persistencia, la base de datos local, Docker/Podman, volúmenes y Drizzle Studio están documentados en PostgreSQL local; el flujo de migraciones es bun run db:up && bun run db:migrate (ver operations/migrations.md).

Documentación

• docs/README.md — índice por tarea: onboarding, guías, arquitectura, referencia, operación y mantenimiento.
• Histórico y trazabilidad — especificación original y reportes de validación cerrados (no normativos).

Licencia

MIT — ver LICENSE.