# Deploy de um frontend e uma API separados: URL da API, CORS e cookies

Faça o deploy de frontend e backend separados. A URL da API é uma variável pública do build. Ajuste CORS, cookies e os previews.

Canonical URL: https://unbroker.cloud/pt/blog/frontend-and-api
Published: 2026-11-11
Reviewed: 2026-11-11
Author: Timoteo Borgobello

## A resposta curta

Para o deploy frontend e backend separados, publique a API primeiro e abra um endpoint na URL pública dela. Depois defina a variável pública do frontend nessa origem e gere o build do frontend. A URL da API que fica no bundle de JavaScript é pública. Um erro de CORS depois do deploy significa que a API não permitiu a origem exata do frontend. Cookies num pedido cross-origin do frontend para a API precisam de credentials, atributos de cookie e proteção contra CSRF. Um hostname privado do projeto não é uma URL que o navegador do visitante consiga chamar.

Frontend e backend no mesmo projeto continuam sendo dois serviços. A página de produto é [Frontend e API](https://unbroker.cloud/pt/solucoes/frontend-and-api). Os passos estão em [Publicar um frontend e uma API juntos](https://docs.unbroker.cloud/guides/frontend-and-api).

## Por que são dois serviços

O frontend e a API têm builds diferentes e configuração de runtime diferente. O [guia de frontend e API](https://docs.unbroker.cloud/guides/frontend-and-api) separa assim:

| Serviço | Resultado do build | Configuração de runtime |
| --- | --- | --- |
| Frontend estático | HTML, JavaScript e assets | Origem pública da API embutida durante o build |
| API HTTP | Processo de servidor | URL do banco, segredos de assinatura e origens de navegador permitidas |

Se você usa renderização no servidor com Next.js, o frontend também é um processo de servidor. Trate assim na estimativa de recursos, e separe pedidos de servidor para servidor dos pedidos do navegador. O que muda nesse servidor está em [Next.js em produção](https://unbroker.cloud/pt/blog/nextjs-in-production). Um site Astro estático com uma API separada está em [Hospedagem Astro](https://unbroker.cloud/pt/blog/astro-hosting).

Comece com repositórios separados se você ainda não definiu os contextos de build de um monorepo. Essa é a instrução do guia.

## Primeiro a API, depois o frontend

Faça o deploy do backend primeiro. Confira um endpoint na URL pública dele. Defina a variável pública da API no frontend com essa origem. Depois gere o build e publique o frontend.

O build do frontend copia a origem que ele vai chamar. Gerar esse build antes de a API ter URL pública deixa no bundle o valor que estava lá, muitas vezes uma URL de localhost. O deploy de frontend e backend separados segue essa ordem.

## A URL da API é uma variável pública de build

A URL da API é uma variável de ambiente do frontend, e é pública. Num frontend Vite, o guia lê `import.meta.env.VITE_API_ORIGIN` e lança um erro se ela faltar. Essa é a URL da API do Vite em produção: um valor escolhido antes do build, não um segredo que você troca reiniciando os mesmos arquivos.

```js
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();
}
```

Os prefixos `VITE_*` e `NEXT_PUBLIC_*` marcam valores feitos para o código do navegador. A Unbroker escolhe as variáveis públicas de build para o ambiente de destino antes de construir. Variáveis privadas ficam só em runtime. Um valor que entra no bundle de JavaScript é público mesmo se você digitou em Variables, no serviço.

O guia chama isso de configuração do navegador, não de lugar para senha de banco. Uma senha de banco e um segredo de assinatura de sessão ficam na API, como variáveis de runtime. Escopos, previews e rotação estão em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets). Os passos estão em [Configure environment variables and secrets](https://docs.unbroker.cloud/guides/environment-variables).

Abra o serviço, edite a chave e grave o valor no Cloud. Se esse valor é compilado nos assets do frontend, a mudança pede um build novo. Fazer deploy do bundle antigo deixa a origem anterior no lugar.

## Hostnames privados não são para o navegador

Um hostname privado do projeto não é alcançável pelo navegador do visitante. Chamadas do navegador precisam de uma rota pública ou de um proxy de backend que você opera.

Um pedido que um servidor faz a outro não é a chamada que o navegador faz. Mantenha os dois separados quando o próprio frontend é um processo de servidor. Este texto não descreve o hostname privado como URL do navegador.

## Erros de CORS depois do deploy

CORS é o mecanismo de headers HTTP com que um servidor diz ao navegador quais outras origens podem ler uma resposta. Uma origem é um esquema, um host e uma porta. O [guia de CORS do MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) é a referência dos headers abaixo. O guia da Unbroker pede para configurar a API para a origem exata do frontend.

`fetch()` e `XMLHttpRequest` seguem a política da mesma origem. A página só consegue ler uma resposta de outra origem quando essa resposta traz os headers CORS certos. Um pedido que funciona no terminal não testa CORS nem as regras de cookie do navegador. Teste o fluxo num navegador.

O navegador envia a origem da página no header `Origin`. A API responde com `Access-Control-Allow-Origin` nessa origem. Num pedido sem credentials, `*` significa qualquer origem. `https://app.example.com` e uma origem de localhost não são a mesma origem. Uma lista que só nomeia a máquina onde você desenvolveu não libera o site publicado.

Um pedido que não é simples envia primeiro um preflight `OPTIONS`. Um pedido simples é `GET`, `HEAD` ou `POST`, sem headers custom, e com content type `application/x-www-form-urlencoded`, `multipart/form-data` ou `text/plain`. `application/json` não está nessa lista, então um `POST` JSON leva preflight. O preflight diz à API qual método e quais headers o pedido real vai usar. A API precisa permitir isso antes de o navegador enviar o pedido real.

Quando o navegador vai enviar credentials, o servidor não pode usar `*` em `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, `Access-Control-Allow-Methods` nem `Access-Control-Expose-Headers`. Precisa nomear. Se uma resposta com credentials diz `Access-Control-Allow-Origin: *`, o navegador bloqueia e reporta um erro de CORS no console. Se a origem permitida pode mudar com o pedido, o MDN diz que o servidor também deveria enviar `Vary: Origin`.

O JavaScript não fica sabendo do motivo. O MDN diz que o único lugar para ver a falha específica é o console do navegador. Leia essa mensagem antes de mudar a API.

Se a API é Express, o processo de produção em volta dessa política está em [Express em produção](https://unbroker.cloud/pt/blog/express-in-production). Este texto não escolhe um pacote de CORS.

## Cookies e credentials entre origens

Por padrão, um `fetch()` ou `XMLHttpRequest` entre origens não envia credentials. Para enviar cookies, defina `credentials` como `"include"` no `fetch()`, ou `XMLHttpRequest.withCredentials` como `true`. Numa resposta CORS, o navegador ignora `Set-Cookie` a menos que o pedido tenha incluído credentials. Ele também esconde a resposta da página a menos que a API envie `Access-Control-Allow-Credentials: true`. Um preflight não deve incluir credentials. A resposta do preflight ainda precisa enviar `Access-Control-Allow-Credentials: true` quando o pedido real for usá-las. Essas regras estão no [guia de CORS do MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).

`SameSite` controla se o cookie sai num pedido cross-site. O MDN define isso como um pedido que vem de outro site, e o esquema conta. Um site não é o mesmo limite que uma origem. Os valores estão em [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie):

| Valor | Quando o navegador envia o cookie |
| --- | --- |
| `Strict` | Só em pedidos do mesmo site que definiu o cookie. |
| `Lax` | Pedidos do mesmo site, mais pedidos cross-site que são navegações de nível superior com um método seguro. Um `fetch()` não é essa navegação. |
| `None` | Pedidos cross-site e do mesmo site. `Secure` também precisa estar definido. |

Alguns navegadores usam `Lax` quando `SameSite` é omitido. O MDN diz que o padrão não é o mesmo em todo navegador. Este texto não nomeia quais.

`Secure` envia o cookie só em `https:`, exceto em localhost. Um site `http:` não consegue definir um cookie `Secure`. `HttpOnly` impede o JavaScript de ler o cookie por `Document.cookie`. O navegador ainda pode enviá-lo no `fetch()` quando o pedido inclui credentials.

Um cookie definido pela API, enquanto a página foi carregada de outro site, é um cookie de terceiros. O MDN diz que as políticas de cookies de terceiros continuam valendo, quaisquer que sejam os headers CORS que você devolva. Um navegador configurado para rejeitar cookies de terceiros não guarda esse `Set-Cookie`. A política padrão difere entre navegadores.

O guia da Unbroker diz que, se você usa cookies, configure credentials, atributos de cookie e proteção CSRF de forma explícita. `SameSite` dá alguma proteção contra cross-site request forgery. Não substitui essa política de CSRF. O MDN também nota que um pedido simples pode parecer o envio de um formulário, então o servidor já precisa se proteger contra CSRF nesse caso. Este texto não escolhe um mecanismo de CSRF.

## Health checks e como verificar os dois serviços

Confira o carregamento de uma página, um pedido à API, um login e uma escrita. Faça isso em cada ambiente. O guia lista essas quatro provas.

Um health check que falha impede que uma revisão que não está saudável seja tratada como live. Revise os logs de build e de runtime antes de tentar de novo. Essa regra está em [Deployments](https://docs.unbroker.cloud/deployments/overview). Por onde começar quando um release falha está em [Depurar um deploy com falha](https://unbroker.cloud/pt/blog/debug-failed-deployment).

Logs de runtime estão no Free e no Pro. A tabela de planos lista métricas de recursos como indisponíveis no Free, e health checks avançados como capacidade do Pro. Este texto não descreve o que o check avançado acrescenta, e não prescreve um caminho. As linhas estão em [Plans](https://docs.unbroker.cloud/billing/plans).

## Previews e produção

Use uma variável por ambiente para um frontend de preview não chamar a API de produção. O exemplo do guia de variáveis é uma origem de API de produção em Production e uma origem de staging em Preview. Não coloque uma credencial de banco de produção em All, a menos que os ambientes de preview devam recebê-la.

Um preview novo copia All e Preview. Nunca copia uma variável que é só de Production. Um preview que já existe guarda os valores que copiou, até você editar esse preview ou recriá-lo. Mudar uma variável de produção não limpa os previews anteriores.

Previews de pull request exigem Pro. Variáveis compartilhadas do projeto também exigem Pro. Uma variável de serviço pertence a uma aplicação, e ela substitui uma variável compartilhada do projeto com a mesma chave. Como um preview é criado e removido está em [Ambientes de preview de pull request](https://unbroker.cloud/pt/blog/pull-request-preview-environments).

## Domínios próprios por último

Anexe domínios de produção só depois que as duas URLs padrão funcionarem. Domínios próprios e TLS gerenciado exigem Pro. O [guia de domínio personalizado](https://docs.unbroker.cloud/guides/custom-domain) começa no Unbroker Pro, com um serviço HTTP no ar e permissão para mudar o DNS.

Quando os hostnames mudam, inclua a origem nova nas allowlists de callback de autenticação, na configuração de CORS e nos trusted hosts. Gere o build do frontend de novo se a origem da API está embutida no bundle. DNS, verificação e certificado estão em [Domínio personalizado e HTTPS](https://unbroker.cloud/pt/blog/custom-domain-https).

Mantenha o hostname padrão. Ele separa uma falha da aplicação de uma falha do domínio.

## Como isso funciona na Unbroker

Crie um serviço de repositório para o frontend e outro para a API, num projeto. Use o preset estático para o frontend. Use Node.js ou um Dockerfile para a API.

O Free custa $0. Permite um projeto, dois serviços no total e três pedidos de deploy por dia UTC. A [página de preços](https://unbroker.cloud/pt/precos) lista os mesmos tetos: um projeto, até dois serviços e três deploys por dia UTC. Os limites de deploy reiniciam à 00:00 UTC, e deploys não usados não acumulam. Cada serviço Free roda uma réplica, até 250m de CPU e 256 MiB, e dorme quando fica idle. O primeiro pedido depois de um sono pode demorar mais enquanto a aplicação sobe. Acordar não pede um deploy novo.

A tabela de planos inclui no Free os sites estáticos de React, Vue, Vite e Astro, e inclui Node.js gerenciado. Builds de Dockerfile, outras receitas de framework, domínios próprios com TLS gerenciado, variáveis compartilhadas do projeto, previews de pull request e health checks avançados não estão no Free. Estão no Pro. Um frontend estático e uma API de Node.js gerenciado cabem no teto do Free. Uma API construída com Dockerfile, não. A lista completa do que esse plano de $0 inclui, e do que fica de fora, está em [o que um plano de hospedagem backend grátis consegue rodar](https://unbroker.cloud/pt/blog/free-backend-hosting).

O Pro custa $25 por mês com $25 de crédito de uso. O crédito reinicia a cada ciclo de cobrança, não acumula e não tem valor em dinheiro. Se o uso elegível fica abaixo do crédito, a cobrança mensal continua o preço do plano. Se o uso elegível passa do crédito, só a diferença é somada. Os preços da página de planos estão em USD e não incluem impostos aplicáveis. Esses termos valem desde 23 de setembro de 2026. As linhas estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans).

Quando você adiciona réplicas, mantenha o estado compartilhado num banco de dados, não na memória. Estime os dois serviços, os builds deles e qualquer armazenamento de dados. O preço do backend sozinho não é o custo da stack. A página comercial desse desenho é [Frontend e API](https://unbroker.cloud/pt/solucoes/frontend-and-api).

## Checklist

1. Publique a API primeiro. Abra um endpoint na URL pública dela antes de gerar o build do frontend.
2. Defina a variável pública da API, por exemplo `VITE_API_ORIGIN`, nessa origem. Gere o build do frontend depois de gravar o valor.
3. Deixe segredos fora de `VITE_*` e `NEXT_PUBLIC_*`. Coloque a URL do banco e os segredos de assinatura na API.
4. Permita a origem exata do frontend. Não use `*` numa resposta que carrega credentials.
5. Se o navegador envia cookies, defina `credentials: "include"`, devolva `Access-Control-Allow-Credentials: true`, configure `SameSite` e `Secure`, e inclua proteção CSRF.
6. Não aponte o navegador para um hostname privado do projeto. Use uma rota pública ou um proxy de backend que você opera.
7. Dê aos previews a própria origem de API. Previews que já existem guardam os valores copiados até você editar ou recriar.
8. Anexe domínios próprios só depois que as duas URLs padrão funcionarem. Atualize callbacks, CORS e trusted hosts, e depois gere o build do frontend de novo.
9. Em cada ambiente, confira o carregamento de uma página, um pedido à API, um login e uma escrita. Um health check que falha não fica live.
10. Estime os dois serviços, os builds e o armazenamento de dados. Mantenha o estado compartilhado num banco quando adicionar réplicas.

## Perguntas frequentes

### O frontend e o backend devem ser publicados separados ou juntos?

Como serviços separados, mesmo quando vivem no mesmo projeto. O build do frontend estático é HTML, JavaScript e assets, e a origem pública da API fica embutida nesse build. O build da API é um processo de servidor, com a URL do banco, os segredos de assinatura e as origens de navegador permitidas. Publicar frontend e backend separados é fazer esses dois builds. Os passos estão em [Publicar um frontend e uma API juntos](https://docs.unbroker.cloud/guides/frontend-and-api).

### Por que o frontend ainda chama localhost depois do deploy?

A URL da API foi compilada no bundle de JavaScript. A Unbroker escolhe as variáveis públicas de build, inclusive VITE_* e NEXT_PUBLIC_*, para o ambiente de destino antes do build. Mudar essa variável pede um build novo. Fazer deploy dos mesmos assets não troca um valor que já está embutido. Se o código ainda tem uma URL de localhost, essa string é o que o navegador chama.

### Por que aparece um erro de CORS depois do deploy se funcionava localmente?

A origem de depois do deploy não é a origem que a API permitia na sua máquina. Uma origem é o esquema, o host e a porta. A API precisa permitir a origem exata do frontend. Um pedido que funciona no terminal não testa CORS. O JavaScript não recebe o motivo. O console do navegador é onde a falha aparece. O MDN documenta isso no [guia de CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).

### Posso colocar uma API key em variáveis VITE_ ou NEXT_PUBLIC_?

Não. Esses prefixos marcam valores feitos para o código do navegador. Um valor embutido no bundle de JavaScript é público mesmo se você digitou em Variables. Uma senha de banco e um segredo de assinatura de sessão ficam na API, como variáveis de runtime. Como os escopos funcionam está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

### Como os cookies funcionam quando o frontend e a API estão em origens diferentes?

Um fetch entre origens não envia cookies a menos que você defina credentials como include. A API precisa responder Access-Control-Allow-Credentials: true e nomear a origem, não *. SameSite e Secure decidem quando o navegador anexa o cookie. O MDN cobre os dois no [guia de CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) e em [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie). O guia da Unbroker também pede para configurar a proteção CSRF de forma explícita. As políticas de cookies de terceiros continuam valendo.

### O navegador pode chamar a API por um hostname privado do projeto?

Não. Um hostname privado do projeto não é alcançável pelo navegador do visitante. Chamadas do navegador precisam de uma rota pública ou de um proxy de backend que você opera. Isso está no [guia de frontend e API](https://docs.unbroker.cloud/guides/frontend-and-api).

### Posso rodar um frontend e uma API no plano Free da Unbroker?

Um frontend estático e uma API de Node.js gerenciado, sim. O Free custa $0, com um projeto e dois serviços no total. Sites estáticos de React, Vue, Vite e Astro estão incluídos, e o Node.js gerenciado também. Cada serviço Free roda uma réplica, até 250m de CPU e 256 MiB, e dorme quando fica idle. O primeiro pedido depois de um sono pode demorar mais. Domínios próprios, variáveis compartilhadas do projeto, previews de pull request, builds de Dockerfile, outras receitas de framework e health checks avançados exigem Pro. O Pro custa $25 por mês com $25 de crédito de uso. As linhas estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans).

## Related reading

- [Frontend e API](https://unbroker.cloud/pt/solucoes/frontend-and-api)
- [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets)
- [Domínio personalizado e HTTPS](https://unbroker.cloud/pt/blog/custom-domain-https)
- [Next.js em produção](https://unbroker.cloud/pt/blog/nextjs-in-production)
- [Hospedagem Astro](https://unbroker.cloud/pt/blog/astro-hosting)
- [Express em produção](https://unbroker.cloud/pt/blog/express-in-production)
- [Ambientes de preview de pull request](https://unbroker.cloud/pt/blog/pull-request-preview-environments)
- [Depurar um deploy com falha](https://unbroker.cloud/pt/blog/debug-failed-deployment)
- [Preços](https://unbroker.cloud/pt/precos)
- [O que o plano de $0 consegue rodar](https://unbroker.cloud/pt/blog/free-backend-hosting)
