README

Punto de partida para proyectos nuevos de API en Laravel. Trae configurados el framework, la autenticación por token, las pruebas, el formateador, el contenedor de despliegue, el pipeline de GitLab y el contexto para trabajar con agentes de IA. No es un producto: no tiene casos de uso, spec ni contrato propios; los rellena la Fase 0 de cada proyecto que sale de aquí.

Qué trae


Framework	Laravel 13, solo API (`routes/api.php`)
Autenticación	Laravel Sanctum, tokens personales (`auth:sanctum`)
Pruebas	Pest 5 con el plugin de Laravel
Estilo	Laravel Pint (preset `laravel`) y `.editorconfig`
Desarrollo local	Laravel Sail (`compose.yaml`): aplicación, PostgreSQL 18 y Redis
Despliegue	`Dockerfile` (nginx + php-fpm) y la configuración de `deploy/`
CI	`.gitlab-ci.yml`: validaciones del método y build de la imagen al Container Registry
Agentes de IA	`AGENTS.md`, `CLAUDE.md`, Laravel Boost (MCP y skills) y guardarraíles en `scripts/hooks/`

El único endpoint es el de ejemplo, GET /api/user, protegido con Sanctum.

Requisitos

PHP 8.4 o superior y Composer 2.
Docker, para el entorno con Sail o para construir la imagen.

Crear un proyecto

Con el instalador de Laravel:

laravel new mi-proyecto --using=grupoapok/laravel-api-starter --no-node --no-boost

Las dos flags hacen falta porque el instalador activa esos pasos por defecto, también con un starter kit, y el starter no puede desactivarlos desde su lado:

--no-node — sin ella, el instalador corre npm install y npm run build aunque no exista package.json. Este starter es solo API y no tiene frontend, así que el build falla con npm error code ENOENT.
--no-boost — sin ella, el instalador vuelve a instalar Laravel Boost y a correr boost:install. El starter ya lo trae configurado (boost.json, los skills y el bloque de guías de AGENTS.md y CLAUDE.md); reinstalarlo es trabajo repetido y puede regenerar esos archivos.

composer create-project no corre ninguno de esos pasos: no necesita flags.

Si el paquete se publica en un registro privado, Composer necesita conocerlo antes (la entrada repositories o auth.json que corresponda).

Al crearse, el proyecto copia .env.example a .env y genera la clave de la aplicación.

Poner en marcha

composer setup   # dependencias, .env, clave y migraciones
composer dev     # levanta los contenedores de Sail y el servidor de desarrollo

.env.example usa SQLite. Para trabajar contra el PostgreSQL de Sail, cambia DB_CONNECTION y las variables DB_* en tu .env.

Comandos habituales

php artisan test --compact              # pruebas
vendor/bin/pint --dirty --format agent  # formatea lo que cambiaste

Imagen de despliegue

El Dockerfile instala las dependencias sin las de desarrollo y arranca con deploy/start.sh, que corre las migraciones, optimiza la aplicación y levanta nginx y php-fpm. La configuración de php-fpm se elige con el argumento PHP_FPM_CONF (php-fpm-prod.conf por defecto, php-fpm-dev.conf).

docker build -t mi-proyecto .

Pipeline

.gitlab-ci.yml tiene dos etapas:

validar — las comprobaciones del método, en .gitlab/ci/metodo.yml y scripts/ci/. Son iguales en todos los proyectos: no se editan en el proyecto.
build — en develop, staging y production, construye la imagen y la sube al Container Registry del proyecto, con estas etiquetas:
- <registry>/<proyecto>:<commit> y <registry>/<proyecto>:<rama>
- <registry>/<proyecto>/<entorno>:<commit> y <registry>/<proyecto>/<entorno>:latest

Los runners necesitan admitir Docker-in-Docker (modo privilegiado).

Trabajar con agentes de IA

Antes de trabajar, persona o agente, lee AGENTS.md: dice qué leer, en qué orden, qué no se toca y en qué fase está el proyecto. CLAUDE.md lo importa para Claude Code.

Licencia

MIT.

grupoapok / laravel-api-starter

Package info

Security

Statistics