The short answer

To deploy frontend and backend separately, publish the API first and open one endpoint on its public URL. Then set the frontend’s public API variable to that origin and build the frontend. The API URL in the JavaScript bundle is public. A CORS error after deploy means the API did not allow the frontend’s exact origin. Cookies on a cross-origin request from the frontend to the API need credentials, cookie attributes, and CSRF protection. A private project hostname is not a URL the visitor’s browser can call.

A frontend and backend in the same project are still two services. The product page is Frontend and API. The steps are Deploy a frontend and API together.

Why two services

The frontend and the API have different builds and different runtime configuration. The frontend and API guide splits them like this:

ServiceBuild resultRuntime configuration
Static frontendHTML, JavaScript, and assetsPublic API origin embedded during the build
HTTP APIServer processDatabase URL, signing secrets, and allowed browser origins

If you use Next.js server rendering, the frontend is also a server process. Treat it as one for resource estimates, and distinguish server-to-server requests from browser requests. What changes for that server is Next.js in production. A static Astro site with a separate API is Astro hosting.

Start with separate repositories if you have not already defined build contexts for a monorepo. That is the guide’s instruction.

Deploy the API first, then the frontend

Deploy the backend first. Verify an endpoint at its public URL. Set the frontend’s public API variable to that origin. Then build and deploy the frontend.

The frontend build copies the origin it will call. Building it before the API has a public URL means the bundle embeds whatever value you had, often a localhost URL. A separate frontend and backend deployment follows that order.

The API URL is a public build-time variable

The API URL is an environment variable on the frontend, and it is public. For a Vite frontend, the guide reads import.meta.env.VITE_API_ORIGIN and throws if it is missing. That is the Vite API URL in production: a value chosen before the build, not a secret you can swap by restarting the same files.

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

Prefixes such as VITE_* and NEXT_PUBLIC_* identify values intended for browser code. Unbroker selects public build variables for the target environment before building. Private variables stay runtime-only. A value that lands in the JavaScript bundle is public even if you typed it in the service’s Variables view.

The guide calls this browser configuration, not a place for a database password. A database password and a session signing secret belong on the API as runtime variables. Scopes, previews, and rotation are Environment variables and secrets. The steps are Configure environment variables and secrets.

Open the service, edit the key, and enter the value in Cloud. If that value is compiled into frontend assets, the change needs a new build. Redeploying the old bundle leaves the previous origin in place.

Private hostnames are not for the browser

A private project hostname is not reachable by a visitor’s browser. Browser calls need a public route or a backend proxy you operate.

A request one server makes to another is not the call the browser makes. Keep those apart when the frontend itself is a server process. This page does not describe the private hostname as a browser URL.

CORS errors after deploy

CORS is the HTTP-header mechanism a server uses to tell the browser which other origins may read a response. An origin is a scheme, a host, and a port. MDN’s CORS guide is the reference for the headers below. The Unbroker guide says to configure the API for the frontend’s exact origin.

fetch() and XMLHttpRequest follow the same-origin policy. The page can read a cross-origin response only when that response carries the right CORS headers. A successful terminal request does not test CORS or browser cookie rules. Test the flow in a browser.

The browser sends the page’s origin on the Origin header. The API answers with Access-Control-Allow-Origin set to that origin. For a request without credentials, * means any origin. https://app.example.com and a localhost origin are not the same origin. An allow list that only names the machine you developed on does not allow the deployed site.

A request that is not simple sends an OPTIONS preflight first. A simple request is GET, HEAD, or POST, with no custom headers, and a content type of application/x-www-form-urlencoded, multipart/form-data, or text/plain. application/json is not on that list, so a JSON POST is preflighted. The preflight tells the API which method and headers the real request will use. The API has to allow them before the browser sends the real request.

When the browser will send credentials, the server must not use * for Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods, or Access-Control-Expose-Headers. It must name them. If a credentialed response says Access-Control-Allow-Origin: *, the browser blocks it and reports a CORS error in the console. If the allowed origin can change with the request, MDN says the server should also send Vary: Origin.

JavaScript is not told why. MDN says the only place to see the specific failure is the browser console. Read that message before you change the API.

If the API is Express, the production process around that policy is Express in production. This page does not pick a CORS package.

Cookies and credentials across origins

By default, a cross-origin fetch() or XMLHttpRequest does not send credentials. To send cookies, set credentials to "include" on fetch(), or set XMLHttpRequest.withCredentials to true. On a CORS response, the browser ignores Set-Cookie unless the request included credentials. It also withholds the response from the page unless the API sends Access-Control-Allow-Credentials: true. A preflight must not include credentials. The preflight response still has to send Access-Control-Allow-Credentials: true when the real request will use them. Those rules are in MDN’s CORS guide.

SameSite controls whether the cookie goes out on a cross-site request. MDN defines that as a request from a different site, and the scheme counts. A site is not the same boundary as an origin. The attribute values are on Set-Cookie:

ValueWhen the browser sends the cookie
StrictOnly for requests from the same site that set the cookie.
LaxSame-site requests, plus cross-site requests that are top-level navigations with a safe method. A fetch() is not that navigation.
NoneCross-site and same-site requests. Secure must also be set.

Some browsers use Lax when SameSite is omitted. MDN says the default is not the same in every browser. This page does not name which ones.

Secure sends the cookie only on https:, except on localhost. An http: site cannot set a Secure cookie. HttpOnly stops JavaScript from reading the cookie through Document.cookie. The browser can still send that cookie on fetch() when the request includes credentials.

A cookie set by the API, while the page was loaded from another site, is a third-party cookie. MDN says third-party cookie policies still apply, whatever CORS headers you return. A browser configured to reject third-party cookies will not store that Set-Cookie. The default policy differs between browsers.

The Unbroker guide says that if you use cookies, configure credentials, cookie attributes, and CSRF protection explicitly. SameSite provides some protection against cross-site request forgery. It does not replace that CSRF policy. MDN also notes that a simple request can look like a form submission, so the server already has to protect against CSRF for that case. This page does not pick a CSRF mechanism.

Health checks and verifying both services

Verify a page load, an API request, a login, and a write. Do that for each environment. The guide lists those four checks.

A failed health check prevents an unhealthy revision from being treated as live. Review the build and runtime logs before you retry. That rule is Deployments. Where to start when a release fails is Debug a failed deployment.

Runtime logs are available on Free and on Pro. The plans table lists resource metrics as not available on Free, and advanced health checks as a Pro capability. This page does not describe what the advanced check adds, and it does not prescribe a path. The rows are in Plans.

Previews and production

Use an environment-specific variable so a preview frontend does not call the production API. The environment guide’s example is a production API origin under Production and a staging origin under Preview. Do not put a production database credential in All unless preview environments should receive it.

A new preview copies All and Preview. It never copies a Production-only variable. An existing preview keeps the values it already copied until you edit that preview or recreate it. Changing a production variable does not sanitize previous previews.

Pull request previews require Pro. Shared project variables require Pro as well. A service variable belongs to one application, and it overrides a shared project variable with the same key. How a preview is created and removed is Pull request preview environments.

Custom domains last

Attach production domains only after both default service URLs work. Custom domains and managed TLS require Pro. The custom domain guide starts from Unbroker Pro, a running HTTP service, and permission to change DNS.

When the hostnames change, add the new origin to authentication callback allowlists, CORS configuration, and trusted-host settings. Rebuild the frontend if the API origin is embedded in the bundle. DNS, verification, and the certificate are Custom domain and HTTPS.

Keep the default hostname. It separates an application failure from a domain failure.

How this works on Unbroker

Create one repository service for the frontend and another for the API, in one project. Use the static preset for the frontend. Use Node.js or a Dockerfile for the API.

Free is $0. It allows one project, two services in total, and three deploy requests per UTC day. The pricing page lists the same caps: one project, up to two services, and three deploys per UTC day. Deploy limits reset at 00:00 UTC, and unused deploys do not carry forward. Each Free service runs one replica, up to 250m CPU and 256 MiB, and sleeps when idle. The first request after a sleep can take longer while the application starts. Waking does not require a new deployment.

The plans table includes static sites for React, Vue, Vite, and Astro on Free, and it includes managed Node.js. Dockerfile builds, other framework recipes, custom domains and managed TLS, shared project variables, pull request previews, and advanced health checks are not on Free. They are on Pro. A static frontend and a managed Node.js API can fit the Free cap. An API built from a Dockerfile cannot. The full list of what that $0 plan includes, and what it leaves out, is what a free backend plan can run.

Pro is $25 a month with $25 of usage credit. The credit resets each billing cycle, does not roll over, and has no cash value. If eligible usage stays under the credit, the monthly charge is still the plan price. If eligible usage is above the credit, only the difference is added. Prices on the plans page are in USD and exclude applicable taxes. Those terms are effective from September 23, 2026. The rows are on pricing and in Plans.

When you add replicas, keep shared state in a database rather than in memory. Estimate both services, their builds, and any data store. The price of the backend alone is not the cost of the stack. The commercial page for this layout is Frontend and API.

Checklist

  1. Deploy the API first. Open an endpoint on its public URL before you build the frontend.
  2. Set the public API variable, such as VITE_API_ORIGIN, to that origin. Build the frontend after the value is set.
  3. Keep secrets off VITE_* and NEXT_PUBLIC_*. Put the database URL and signing secrets on the API.
  4. Allow the frontend’s exact origin. Do not use * on a response that carries credentials.
  5. If the browser sends cookies, set credentials: "include", return Access-Control-Allow-Credentials: true, set SameSite and Secure, and configure CSRF protection.
  6. Do not point the browser at a private project hostname. Use a public route or a backend proxy you operate.
  7. Give previews their own API origin. Existing previews keep copied values until you edit or recreate them.
  8. Attach custom domains only after both default URLs work. Update callbacks, CORS, and trusted hosts, then rebuild the frontend.
  9. In each environment, check a page load, an API request, a login, and a write. A failed health check does not go live.
  10. Estimate both services, their builds, and the data store. Keep shared state in a database when you add replicas.

FAQ

Should the frontend and backend be deployed separately or together?

Deploy them as separate services, even when they live in one project. The static frontend build is HTML, JavaScript, and assets, and the public API origin is embedded during that build. The API build is a server process, with the database URL, signing secrets, and allowed browser origins. A separate frontend and backend deployment is those two builds. The steps are Deploy a frontend and API together.

Why does my frontend still call localhost after deploy?

The API URL was compiled into the JavaScript bundle. Unbroker selects public build variables, including VITE_* and NEXT_PUBLIC_*, for the target environment before the build. Changing that variable needs a new build. Redeploying the same assets does not replace a value already embedded. If the source still contains a localhost URL, that string is what the browser calls.

Why do I get a CORS error after deploying when it worked locally?

The origin after deploy is not the origin the API allowed on your machine. An origin is the scheme, the host, and the port. The API has to allow the frontend's exact origin. A request that succeeds in a terminal does not test CORS. JavaScript does not receive the reason. The browser console is where the failure is visible. MDN documents that in the CORS guide.

Can I put an API key in VITE_ or NEXT_PUBLIC_ variables?

No. Those prefixes identify values intended for browser code. A value embedded in the JavaScript bundle is public even if you typed it in Variables. A database password and a session signing secret belong on the API as runtime variables. How scopes work is Environment variables and secrets.

How do cookies work when the frontend and API are on different origins?

A cross-origin fetch does not send cookies unless you set credentials to include. The API must respond with Access-Control-Allow-Credentials: true, and it must name the origin instead of *. SameSite and Secure decide when the browser will attach the cookie. MDN covers both in the CORS guide and on Set-Cookie. The Unbroker guide also says to configure CSRF protection explicitly. Third-party cookie policies still apply.

Can the browser call the API through a private project hostname?

No. A private project hostname is not reachable by a visitor's browser. Browser calls need a public route or a backend proxy you operate. That is the frontend and API guide.

Can I run a frontend and an API on Unbroker's Free plan?

A static frontend and a managed Node.js API can. Free is $0, one project, and two services in total. Static sites for React, Vue, Vite, and Astro are included, and so is managed Node.js. Each Free service runs one replica, up to 250m CPU and 256 MiB, and sleeps when idle. The first request after a sleep can take longer. Custom domains, shared project variables, pull request previews, Dockerfile builds, other framework recipes, and advanced health checks require Pro. Pro is $25 a month with $25 of usage credit. The rows are on pricing and in Plans.