sevalla-hosting/skills

Desplegando Next.js en Sevalla

Sevalla es un PaaS (de Kinsta) con dos productos de hosting para Next.js:

• Application Hosting ejecuta un servidor Node.js real. Requerido para SSR, manejadores de rutas (rutas API), proxy (anteriormente middleware), ISR (revalidate), acciones de servidor o websockets.
• Static Site Hosting sirve la salida de una exportación estática (output: 'export'). Sin código del lado del servidor en absoluto. Límite de 100 sitios estáticos por compañía.

Acierta esta decisión primero. Determina todo lo que sigue.

Paso 0: Decidir qué producto de hosting usar

Inspecciona el repositorio antes de hacer cualquier otra cosa:

1. Lee next.config.js / next.config.ts / next.config.mjs en busca de output: 'export' o output: 'standalone'.
2. Busca en el código fuente: app/api/, pages/api/, proxy.ts o proxy.js (Next.js 16), middleware.ts o middleware.js (Next.js 15 y anteriores), "use server", getServerSideProps, revalidate (ISR), NextResponse, o cualquier cliente de base de datos o autenticación usado del lado del servidor.
3. Decide:
   • Si está presente alguno de los anteriores: Application Hosting (servidor requerido). Ve al Paso 1.
   • Ninguno presente, contenido puramente estático, marketing o blog: Static Site Hosting es más simple y barato. Lee references/static-hosting.md.
   • Si no estás seguro, o el usuario quiere características dinámicas más tarde: por defecto, Application Hosting. Puede hacer todo lo que el hosting estático puede.

Si es genuinamente ambiguo, haz al usuario una pregunta: "¿Esta aplicación necesita un servidor en vivo (rutas API, ISR, autenticación, llamadas a base de datos) o es completamente estática?" No adivines en silencio, porque la elección incorrecta significa rehacer todo el despliegue.

También verifica si el repositorio tiene un cliente de base de datos (Prisma, Drizzle, pg, mysql2, Mongoose, redis, ioredis) y si hay subidas de archivos. Si encuentras alguno, lee references/data-services.md antes del Paso 3.

Paso 1: Elegir una estrategia de compilación (Application Hosting)

Sevalla compila aplicaciones basadas en Git con una de cuatro estrategias:

• Nixpacks, la opción por defecto. Sin configuración para una aplicación Next.js estándar. Úsalo a menos que haya una razón para no hacerlo.
• Railpack, el sucesor de Nixpacks. También sin configuración. Una buena opción para una aplicación nueva. Configúralo con el campo de API build_type: "railpack".
• Dockerfile, cuando el usuario quiere una imagen pequeña y reproducible, tiene un monorepo con el que los compiladores auto-detectados tienen dificultades, o pide Docker.
• Buildpacks (pack). Raramente necesario para Next.js.

Lee references/app-hosting.md antes de escribir cualquier configuración. Tiene los scripts exactos de package.json, el Dockerfile recomendado, las anulaciones de nixpacks.toml y la configuración de Ruta de compilación para monorepos. No crees un Dockerfile o nixpacks.toml a partir de conocimientos generales de Next.js. Sevalla tiene restricciones específicas (a continuación) que las guías genéricas no mencionan.

Paso 2: Preparar el repositorio (restricciones de Sevalla)

Estas tropiezan casi todos los primeros despliegues. Verifica todas ellas antes de desplegar:

1. Lee el puerto de $PORT y enlázalo a 0.0.0.0. El puerto predeterminado del proceso web es 8080, y Sevalla lo pasa en PORT. Solo los puertos 80 y 443 están abiertos a internet, y Sevalla los enruta a $PORT. Con Nixpacks o Railpack, el script de inicio debe ser next start -p ${PORT:-8080} -H 0.0.0.0. Un simple next start escucha en el 3000.
2. Las variables NEXT_PUBLIC_* se incluyen en tiempo de compilación. Créalas como variables de tiempo de compilación (is_buildtime: true) antes de que se ejecute la compilación. Una variable añadida más tarde necesita un nuevo despliegue, no un reinicio.
3. El sistema de archivos es efímero. Cualquier cosa que la aplicación escriba en disco en tiempo de ejecución (subidas, archivos generados, cachés en disco) se pierde en cada redepliegue o reinicio. Usa almacenamiento de objetos, o un disco persistente si la aplicación realmente necesita escrituras en disco local (por ejemplo SQLite o un CMS auto-alojado). Consulta references/data-services.md.
4. output: 'standalone' solo con el Dockerfile. next start no usa el paquete standalone, y Next.js advierte "next start" no funciona con la configuración "output: standalone". Así que con Nixpacks o Railpack, deja output sin configurar. Con el Dockerfile, configura output: 'standalone'.
5. No confirmes node_modules o .next. Una carpeta node_modules confirmada es una causa documentada de compilaciones fallidas en Sevalla.
6. Fija la versión de Node.js. Nixpacks usa Node 18 por defecto, y Next.js 16 necesita Node 20.9 o posterior. Configura "engines": { "node": "22.x" } en package.json, o la variable de tiempo de compilación NIXPACKS_NODE_VERSION=22.
7. Monorepos: configura la Ruta de compilación (campo de API build_path) a la carpeta de la aplicación Next.js, por ejemplo apps/web. Con el Dockerfile, también configura docker_context y dockerfile_path.
8. Nombre de package.json: no uses "node" o "js" como nombre del paquete. Está documentado que rompe las compilaciones de Sevalla.
9. Las comillas dobles en los valores de las variables deben escaparse como \". Las comillas sin escapar se pierden o hacen que el despliegue falle.
10. Secretos (URLs de base de datos, claves API) van en las variables de entorno de Sevalla. Nunca confirmes un archivo .env con secretos reales.

Paso 3: Desplegar

Usa la primera opción que esté disponible, en este orden:

1. El servidor MCP de Sevalla (https://mcp.sevalla.com/mcp). Tiene dos herramientas: search encuentra endpoints de API en la especificación, y execute ejecuta JavaScript que llama a sevalla.request({ method, path, body }). Usa las rutas de API en la tabla siguiente.
2. La CLI de sevalla, con --json en cada comando para que puedas leer los IDs. Instálala con npm install -g @sevalla/cli (Node 22+) o brew install sevalla-hosting/tap/sevalla. Inicia sesión con sevalla login (autorización de dispositivo en el navegador) o configura SEVALLA_API_TOKEN.
3. La API REST en https://api.sevalla.com/v3 con una clave API Bearer.

Si ninguna está disponible, dile al usuario cómo añadir el servidor MCP (consulta las guías de inicio rápido para agentes de codificación en https://docs.sevalla.com/quick-starts/coding-agents/overview), o dale los pasos del panel de control en references/dashboard.md. Solo el primer inicio de sesión necesita al usuario.

Application Hosting

#	Acción	API (MCP execute o REST)	CLI
1	Elegir una ubicación	GET /resources/clusters	sevalla resources clusters --json
2	Crear la aplicación	POST /applications con display_name, cluster_id, source (privateGit para un repositorio conectado de GitHub, GitLab o Bitbucket, publicGit para una URL pública), git_type, repo_url, default_branch	sevalla apps create --name <nombre> --cluster <id-del-clúster> --source privateGit --git-type github --repository https://github.com/<propietario>/<repositorio> --branch <rama> --json
3	Configurar la estrategia de compilación y la ruta de compilación, si no son las predeterminadas	PATCH /applications/{id} con build_type (nixpacks, railpack, dockerfile, pack) y build_path	sevalla apps update <id-de-la-app> --build-type railpack --json. La CLI no tiene un flag de ruta de compilación: sevalla apps update <id-de-la-app> --data '{"build_path":"apps/web"}' --json
4	Añadir variables de entorno	POST /applications/{id}/env-vars con key y value. is_runtime e is_buildtime ambos predeterminados a true, lo cual es correcto para NEXT_PUBLIC_*.	sevalla apps env-vars create <id-de-la-app> --key <CLAVE> --value "<valor>" (disponible en tiempo de compilación y en tiempo de ejecución)
5	Conectar una base de datos, si la hay	Consulta references/data-services.md
6	Desplegar	POST /applications/{id}/deployments. Crear una aplicación no inicia un despliegue.	sevalla apps deployments trigger <id-de-la-app> --branch <rama> --json

Si el paso 2 falla con HTTP 500 para un repositorio privateGit, la causa más probable es que la aplicación de GitHub de Sevalla no pueda ver el repositorio. La API no lo dice. Compruébalo con sevalla git providers --json: el settings_url abre la instalación de la aplicación de GitHub. El usuario (o un propietario de la organización de GitHub) debe dar acceso a la aplicación al repositorio. Un repositorio en una organización que el usuario no posee necesita que un propietario lo añada. Luego intenta el paso 2 de nuevo.

Una aplicación nueva tiene el despliegue automático desactivado. Si el usuario quiere un despliegue en cada push, configura auto_deploy: true con PATCH /applications/{id} (funciona solo para privateGit).

Para Static Site Hosting, sigue references/static-hosting.md en su lugar. Crear un sitio estático inicia su primer despliegue automáticamente.

Paso 4: Verificar

Un despliegue que comenzó no es un despliegue que funciona. Haz todo esto antes de decirle al usuario que está listo:

1. Espera la compilación. Consulta GET /applications/{id}/deployments/{deployment_id} (CLI: sevalla apps deployments get <id-del-despliegue> --app-id <id-de-la-app> --json) cada 15 a 30 segundos hasta que status sea success o failed. Otros valores son waiting, inProgress, cancelled y skipped.
2. Si falló, lee el registro de compilación. GET /applications/{id}/deployments/{deployment_id}/logs (CLI: sevalla apps deployments logs ...). Compara el error con la tabla de solución de problemas en references/app-hosting.md, corrige la causa y despliega de nuevo. No adivines dos veces sin leer el registro. Juzga el éxito por el status del despliegue, no por la severidad del registro: la salida de compilación normal escrita en stderr aparece con "severity": "error" en una compilación exitosa.
3. Encuentra la URL en vivo. GET /applications/{id}/domains (CLI: sevalla apps domains list --app-id <id-de-la-app> --json). Cada aplicación recibe un dominio *.sevalla.app gratuito después de su primer despliegue exitoso.
4. Solicita la URL. Espera HTTP 200 en / y en un manejador de ruta, si la aplicación tiene uno. Un 502 o un tiempo de espera generalmente significa que el servidor no está escuchando en $PORT y 0.0.0.0.
5. Si la aplicación responde con un error, lee el registro de tiempo de ejecución. GET /applications/{id}/runtime-logs (CLI: sevalla apps logs runtime <id-de-la-app>).

Luego dile al usuario la URL en vivo, lo que configuraste y cualquier cosa que deba hacer él mismo (por ejemplo, añadir registros DNS para un dominio personalizado).

Paso 5: Pasos siguientes opcionales

• Dominio personalizado: sevalla apps domains add <id-de-la-app> --name ejemplo.com. El usuario debe añadir los registros DNS que Sevalla devuelve. SSL está incluido.
• Escalado: sevalla apps processes update <id-del-proceso> --app-id <id-de-la-app> --instances <n>. Con más de una instancia, no uses un disco persistente para el estado compartido. Usa almacenamiento de objetos o una base de datos.
• Rollback: sevalla apps deployments rollback <id-de-la-app> --deployment-id <id-del-despliegue>.

Archivos de referencia

• references/app-hosting.md: scripts de package.json, notas sobre Nixpacks y Railpack, el Dockerfile recomendado, configuración de monorepo, tabla de solución de problemas.
• references/static-hosting.md: configuración de exportación estática y despliegue para Static Site Hosting.
• references/data-services.md: bases de datos, almacenamiento de objetos y discos persistentes, y cómo sus detalles de conexión llegan a la aplicación.
• references/dashboard.md: los mismos pasos en el panel de control de Sevalla, para una persona.