La respuesta corta
Para desplegar frontend y backend por separado, publicá la API primero y abrí un endpoint en su URL pública. Después fijá la variable pública del frontend en ese origen y construí el frontend. La URL de la API que queda en el bundle de JavaScript es pública. Un error de CORS después del deploy quiere decir que la API no permitió el origen exacto del frontend. Las cookies en un pedido cross-origin del frontend a la API necesitan credentials, atributos de cookie y protección CSRF. Un hostname privado del proyecto no es una URL que el navegador del visitante pueda llamar.
Un frontend y un backend en el mismo proyecto siguen siendo dos servicios. La página de producto es Frontend y API. Los pasos están en Desplegar un frontend y una API juntos.
Por qué son dos servicios
El frontend y la API tienen builds distintos y configuración de runtime distinta. La guía de frontend y API los separa así:
| Servicio | Resultado del build | Configuración de runtime |
|---|---|---|
| Frontend estático | HTML, JavaScript y assets | Origen público de la API incrustado durante el build |
| API HTTP | Proceso de servidor | URL de la base, secretos de firma y orígenes de navegador permitidos |
Si usás renderizado de servidor con Next.js, el frontend también es un proceso de servidor. Contalo como tal en la estimación de recursos, y distinguí los pedidos de servidor a servidor de los pedidos del navegador. Qué cambia en ese servidor está en Next.js en producción. Un sitio Astro estático con una API aparte está en Hosting para Astro.
Arrancá con repositorios separados si todavía no definiste los contextos de build de un monorepo. Esa es la instrucción de la guía.
Primero la API, después el frontend
Desplegá el backend primero. Verificá un endpoint en su URL pública. Fijá la variable pública de la API en el frontend con ese origen. Después construí y desplegá el frontend.
El build del frontend copia el origen al que va a llamar. Construirlo antes de que la API tenga URL pública deja en el bundle el valor que había, muchas veces una URL de localhost. Desplegar frontend y backend por separado sigue ese orden.
La URL de la API es una variable pública de build
La URL de la API es una variable de entorno del frontend, y es pública. En un frontend Vite, la guía lee import.meta.env.VITE_API_ORIGIN y tira un error si falta. Esa es la URL de la API de Vite en producción: un valor elegido antes del build, no un secreto que puedas cambiar reiniciando los mismos archivos.
const apiOrigin = import.meta.env.VITE_API_ORIGIN;
if (!apiOrigin) throw new Error("VITE_API_ORIGIN is required");
export async function getMessage() {
const response = await fetch(new URL("/api/message", apiOrigin));
if (!response.ok) throw new Error("API request failed");
return response.json();
}
Los prefijos VITE_* y NEXT_PUBLIC_* marcan valores pensados para el código del navegador. Unbroker elige las variables públicas de build para el entorno de destino antes de construir. Las variables privadas quedan solo en runtime. Un valor que termina en el bundle de JavaScript es público aunque lo hayas escrito en la vista Variables del servicio.
La guía llama a esto configuración del navegador, no un lugar para una contraseña de base. Una contraseña de base y un secreto de firma de sesión van en la API, como variables de runtime. Alcances, previews y rotación están en Variables de entorno y secretos. Los pasos están en Configure environment variables and secrets.
Abrí el servicio, editá la clave y cargá el valor en Cloud. Si ese valor queda compilado en los assets del frontend, el cambio pide un build nuevo. Redesplegar el bundle viejo deja el origen anterior en su lugar.
Los hostnames privados no son para el navegador
Un hostname privado del proyecto no es alcanzable desde el navegador del visitante. Las llamadas del navegador necesitan una ruta pública o un proxy de backend que operes vos.
Un pedido que un servidor le hace a otro no es la llamada que hace el navegador. Mantenelos separados cuando el frontend mismo es un proceso de servidor. Esta nota no describe el hostname privado como URL del navegador.
Errores de CORS después del deploy
CORS es el mecanismo de headers HTTP con el que un servidor le dice al navegador qué otros orígenes pueden leer una respuesta. Un origen es un esquema, un host y un puerto. La guía de CORS de MDN es la referencia de los headers de abajo. La guía de Unbroker pide configurar la API para el origen exacto del frontend.
fetch() y XMLHttpRequest siguen la política del mismo origen. La página puede leer una respuesta de otro origen solo si esa respuesta trae los headers CORS correctos. Un pedido que anda en la terminal no prueba CORS ni las reglas de cookies del navegador. Probá el flujo en un navegador.
El navegador manda el origen de la página en el header Origin. La API responde con Access-Control-Allow-Origin en ese origen. En un pedido sin credentials, * significa cualquier origen. https://app.example.com y un origen de localhost no son el mismo origen. Una lista que solo nombra la máquina donde desarrollaste no permite el sitio desplegado.
Un pedido que no es simple manda primero un preflight OPTIONS. Un pedido simple es GET, HEAD o POST, sin headers custom, y con un content type application/x-www-form-urlencoded, multipart/form-data o text/plain. application/json no está en esa lista, así que un POST JSON lleva preflight. El preflight le dice a la API qué método y qué headers va a usar el pedido real. La API tiene que permitirlos antes de que el navegador mande el pedido real.
Cuando el navegador va a mandar credentials, el servidor no puede usar * en Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods ni Access-Control-Expose-Headers. Tiene que nombrarlos. Si una respuesta con credentials dice Access-Control-Allow-Origin: *, el navegador la bloquea y reporta un error de CORS en la consola. Si el origen permitido puede cambiar con el pedido, MDN dice que el servidor también debería mandar Vary: Origin.
JavaScript no se entera del motivo. MDN dice que el único lugar para ver la falla concreta es la consola del navegador. Leé ese mensaje antes de cambiar la API.
Si la API es Express, el proceso de producción alrededor de esa política está en Express en producción. Esta nota no elige un paquete de CORS.
Cookies y credentials entre orígenes
Por defecto, un fetch() o XMLHttpRequest entre orígenes no manda credentials. Para mandar cookies, poné credentials en "include" en fetch(), o XMLHttpRequest.withCredentials en true. En una respuesta CORS, el navegador ignora Set-Cookie salvo que el pedido haya incluido credentials. También le niega la respuesta a la página salvo que la API mande Access-Control-Allow-Credentials: true. Un preflight no debe incluir credentials. La respuesta del preflight igual tiene que mandar Access-Control-Allow-Credentials: true cuando el pedido real las va a usar. Esas reglas están en la guía de CORS de MDN.
SameSite controla si la cookie sale en un pedido cross-site. MDN lo define como un pedido que viene de otro sitio, y el esquema cuenta. Un sitio no es el mismo límite que un origen. Los valores están en Set-Cookie:
| Valor | Cuándo el navegador manda la cookie |
|---|---|
Strict | Solo en pedidos del mismo sitio que la definió. |
Lax | Pedidos del mismo sitio, más pedidos cross-site que son navegaciones de nivel superior con un método seguro. Un fetch() no es esa navegación. |
None | Pedidos cross-site y del mismo sitio. Secure también tiene que estar. |
Algunos navegadores usan Lax cuando SameSite no está. MDN dice que el default no es el mismo en todos los navegadores. Esta nota no nombra cuáles.
Secure manda la cookie solo por https:, salvo en localhost. Un sitio http: no puede definir una cookie Secure. HttpOnly impide que JavaScript lea la cookie por Document.cookie. El navegador igual puede mandarla en fetch() cuando el pedido incluye credentials.
Una cookie que define la API, mientras la página se cargó desde otro sitio, es una cookie de terceros. MDN dice que las políticas de cookies de terceros siguen aplicando, más allá de los headers CORS que devuelvas. Un navegador configurado para rechazar cookies de terceros no va a guardar ese Set-Cookie. La política por defecto difiere entre navegadores.
La guía de Unbroker dice que, si usás cookies, configures credentials, atributos de cookie y protección CSRF de forma explícita. SameSite da algo de protección contra cross-site request forgery. No reemplaza esa política de CSRF. MDN también marca que un pedido simple puede parecer el envío de un formulario, así que el servidor ya tiene que protegerse contra CSRF en ese caso. Esta nota no elige un mecanismo de CSRF.
Health checks y cómo verificar los dos servicios
Verificá la carga de una página, un pedido a la API, un login y una escritura. Hacelo en cada entorno. La guía lista esas cuatro pruebas.
Un health check fallido impide que una revisión que no está sana quede como live. Revisá los logs de build y de runtime antes de reintentar. Esa regla está en Deployments. Por dónde empezar cuando un release falla está en Depurar un deploy fallido.
Los logs de runtime están en Free y en Pro. La tabla de planes lista las métricas de recursos como no disponibles en Free, y los health checks avanzados como capacidad de Pro. Esta nota no describe qué suma el check avanzado, y no prescribe una ruta. Las filas están en Plans.
Previews y producción
Usá una variable por entorno para que un frontend de preview no llame a la API de producción. El ejemplo de la guía de variables es un origen de API de producción en Production y un origen de staging en Preview. No pongas una credencial de base de producción en All, salvo que los entornos de preview deban recibirla.
Un preview nuevo copia All y Preview. Nunca copia una variable que es solo de Production. Un preview que ya existe conserva los valores que copió, hasta que lo edites o lo recrees. Cambiar una variable de producción no sanea los previews anteriores.
Los previews de pull request piden Pro. Las variables compartidas del proyecto también piden Pro. Una variable de servicio pertenece a una aplicación, y pisa una variable compartida del proyecto con la misma clave. Cómo se crea y se borra un preview está en Entornos de preview por pull request.
Los dominios propios, al final
Adjuntá dominios de producción recién cuando las dos URLs default funcionan. Los dominios propios y el TLS gestionado piden Pro. La guía de dominio personalizado arranca desde Unbroker Pro, un servicio HTTP en marcha y permiso para cambiar el DNS.
Cuando cambian los hostnames, sumá el origen nuevo a las allowlists de callbacks de autenticación, a la configuración de CORS y a los trusted hosts. Reconstruí el frontend si el origen de la API está incrustado en el bundle. El DNS, la verificación y el certificado están en Dominio personalizado y HTTPS.
Dejá el hostname default. Separa una falla de la aplicación de una falla del dominio.
Cómo funciona en Unbroker
Creá un servicio de repositorio para el frontend y otro para la API, en un proyecto. Usá el preset estático para el frontend. Usá Node.js o un Dockerfile para la API.
Free sale $0. Permite un proyecto, dos servicios en total y tres pedidos de deploy por día UTC. La página de precios lista los mismos topes: un proyecto, hasta dos servicios y tres deploys por día UTC. Los límites de deploy se reinician a las 00:00 UTC, y los deploys que no usaste no se acumulan. Cada servicio Free corre una réplica, hasta 250m de CPU y 256 MiB, y duerme cuando está idle. El primer pedido después de un sueño puede tardar más mientras la aplicación arranca. Despertar no pide un deploy nuevo.
La tabla de planes incluye en Free los sitios estáticos de React, Vue, Vite y Astro, y incluye Node.js gestionado. Los builds de Dockerfile, otras recetas de framework, los dominios propios con TLS gestionado, las variables compartidas del proyecto, los previews de pull request y los health checks avanzados no están en Free. Están en Pro. Un frontend estático y una API de Node.js gestionado pueden entrar en el tope de Free. Una API construida con Dockerfile, no. La lista completa de lo que incluye ese plan de $0, y de lo que deja afuera, está en qué puede correr un plan de hosting backend gratis.
Pro sale $25 por mes con $25 de crédito de uso. El crédito se reinicia en cada ciclo, no se acumula y no tiene valor en efectivo. Si el uso elegible queda por debajo del crédito, el cargo mensual sigue siendo el precio del plan. Si el uso elegible lo pasa, solo se suma la diferencia. Los precios de la página de planes están en USD y no incluyen impuestos aplicables. Esos términos rigen desde el 23 de septiembre de 2026. Las filas están en precios y en Plans.
Cuando sumás réplicas, dejá el estado compartido en una base de datos, no en memoria. Estimá los dos servicios, sus builds y cualquier almacén de datos. El precio del backend solo no es el costo del stack. La página comercial de este esquema es Frontend y API.
Checklist
- Desplegá la API primero. Abrí un endpoint en su URL pública antes de construir el frontend.
- Fijá la variable pública de la API, por ejemplo
VITE_API_ORIGIN, en ese origen. Construí el frontend después de cargar el valor. - Dejá los secretos fuera de
VITE_*yNEXT_PUBLIC_*. Poné la URL de la base y los secretos de firma en la API. - Permití el origen exacto del frontend. No uses
*en una respuesta que lleva credentials. - Si el navegador manda cookies, poné
credentials: "include", devolvéAccess-Control-Allow-Credentials: true, configuráSameSiteySecure, y sumá protección CSRF. - No apuntes el navegador a un hostname privado del proyecto. Usá una ruta pública o un proxy de backend que operes vos.
- Dale a los previews su propio origen de API. Los previews que ya existen conservan los valores copiados hasta que los edites o los recrees.
- Adjuntá dominios propios recién cuando las dos URLs default funcionan. Actualizá callbacks, CORS y trusted hosts, y después reconstruí el frontend.
- En cada entorno, revisá la carga de una página, un pedido a la API, un login y una escritura. Un health check fallido no queda live.
- Estimá los dos servicios, sus builds y el almacén de datos. Dejá el estado compartido en una base cuando sumes réplicas.
Preguntas frecuentes
¿Hay que desplegar el frontend y el backend por separado o juntos?
Como servicios separados, aunque vivan en el mismo proyecto. El build del frontend estático es HTML, JavaScript y assets, y el origen público de la API queda incrustado en ese build. El build de la API es un proceso de servidor, con la URL de la base, los secretos de firma y los orígenes de navegador permitidos. Eso es desplegar frontend y backend por separado: dos builds distintos. Los pasos están en Desplegar un frontend y una API juntos.
¿Por qué el frontend sigue llamando a localhost después del deploy?
La URL de la API quedó compilada en el bundle de JavaScript. Unbroker elige las variables públicas de build, incluidas VITE_* y NEXT_PUBLIC_*, para el entorno de destino antes del build. Cambiar esa variable pide un build nuevo. Redesplegar los mismos assets no reemplaza un valor que ya está incrustado. Si el código todavía tiene una URL de localhost, esa cadena es la que llama el navegador.
¿Por qué aparece un error de CORS después del deploy si en local andaba?
El origen de después del deploy no es el origen que la API permitía en tu máquina. Un origen es el esquema, el host y el puerto. La API tiene que permitir el origen exacto del frontend. Un pedido que anda en la terminal no prueba CORS. JavaScript no recibe el motivo. La consola del navegador es donde se ve la falla. MDN lo documenta en la guía de CORS.
¿Puedo poner una API key en variables VITE_ o NEXT_PUBLIC_?
No. Esos prefijos marcan valores pensados para el código del navegador. Un valor incrustado en el bundle de JavaScript es público aunque lo hayas escrito en Variables. Una contraseña de base y un secreto de firma de sesión van en la API, como variables de runtime. Cómo funcionan los alcances está en Variables de entorno y secretos.
¿Cómo funcionan las cookies si el frontend y la API están en orígenes distintos?
Un fetch entre orígenes no manda cookies salvo que pongas credentials en include. La API tiene que responder Access-Control-Allow-Credentials: true y nombrar el origen, no *. SameSite y Secure deciden cuándo el navegador adjunta la cookie. MDN cubre las dos cosas en la guía de CORS y en Set-Cookie. La guía de Unbroker también pide configurar la protección CSRF de forma explícita. Las políticas de cookies de terceros siguen aplicando.
¿El navegador puede llamar a la API por un hostname privado del proyecto?
No. Un hostname privado del proyecto no es alcanzable desde el navegador del visitante. Las llamadas del navegador necesitan una ruta pública o un proxy de backend que operes vos. Eso lo dice la guía de frontend y API.
¿Puedo correr un frontend y una API en el plan Free de Unbroker?
Un frontend estático y una API de Node.js gestionado, sí. Free sale $0, con un proyecto y dos servicios en total. Los sitios estáticos de React, Vue, Vite y Astro están incluidos, y Node.js gestionado también. Cada servicio Free corre una réplica, hasta 250m de CPU y 256 MiB, y duerme cuando está idle. El primer pedido después de un sueño puede tardar más. Los dominios propios, las variables compartidas del proyecto, los previews de pull request, los builds de Dockerfile, otras recetas de framework y los health checks avanzados piden Pro. Pro sale $25 por mes con $25 de crédito de uso. Las filas están en precios y en Plans.