In an Expo Router app, fetch('/api/waitlist') works in development but fails in the native release build; why, and how do you fix it?

## The symptom A team adds `src/app/api/waitlist+api.ts` to an Expo Router app. In development everything works: the web page and the iOS simulator both call `fetch('/api/waitlist')` and get a response. Then a release build of the native app ships, and the same call fails. Nothing is wrong with the handler. The problem is **what a relative URL means on a phone**. ## Why development hides the problem In a browser, `/api/waitlist` is resolved against the page's own origin, the site that served the HTML. A native app has no page origin. Expo Router's server features are built on native implementations of `window.location` and `fetch` that point at a server: 1. **In development**, that server is the **Expo dev server** started by `npx expo start`. It bundles and executes API routes on demand, so relative requests succeed. It even serves them when `web.output` is not `server`, printing only a warning. 2. **In a release build**, there is no dev server. Relative URLs resolve against the **`origin`** configured for the `expo-router` config plugin. If no origin was configured and no server was deployed, the request has nowhere to go. So the development loop proves the handler works; it does not prove there is a production server or that the app knows where it is. ## The fix, step by step 1. **Set `web.output` to `server`**, so the export produces a server bundle in `dist/server`. 2. **Export and deploy the server**: `npx expo export --platform web`, then deploy to EAS Hosting with `eas deploy` or to another host through an `expo-server` adapter. 3. **Point the native app at it**: set the `origin` option of the `expo-router` plugin in the app config to the deployed HTTPS URL, then rebuild, because the value is baked into the build. 4. **Provide the server's environment**: the deployed server does not read `.env` files; secrets such as the waitlist service key must be configured on the host. ```json { "expo": { "web": { "output": "server" }, "plugins": [["expo-router", { "origin": "https://example.com" }]] } } ``` ## Automating the origin Expo has an **alpha** path that deploys the server during the native build: with `EXPO_UNSTABLE_DEPLOY_SERVER=1` set, an EAS Build deploys a versioned server to EAS Hosting and writes the generated origin into the build. Its documented limits matter in an interview answer: - `origin` must **not** be set manually in the app config. - It does not support a dynamic `app.config.js` or `app.config.ts` yet. - `EXPO_NO_DEPLOY=1` skips it, and deployment logs go to `.expo/logs/deploy.log`. The benefit is **versioning**: each native build talks to the server deployed alongside it, so an old binary in users' hands keeps calling a compatible API. ## Testing the release path locally You can reproduce the production setup without shipping: 1. `npx expo export` to build the production server. 2. `npx expo serve` to host it, by default on `http://localhost:8081`. 3. Temporarily set the plugin `origin` to that URL and build in release mode with automatic deployment disabled, for example `EXPO_NO_DEPLOY=1 npx expo run:ios --configuration Release`. Remove the local origin before building for the store. ## Production judgment | Concern | What to decide | |---|---| | Old binaries | The API contract must stay compatible with every native version still installed | | Origin per environment | Staging and production builds need different origins | | Web vs native callers | Web calls are same-origin; native calls come from anywhere and need their own abuse protection | | Absolute vs relative URLs | An explicit base URL from config is easier to reason about than relying on the origin mapping | - Treat a missing origin as a release-checklist item; the failure only appears in release builds. - Log the server URL a build uses at startup in internal builds, so a wrong origin is visible immediately. This behaviour is documented for Expo SDK 57 with Expo Router 57.x; native deployment of server features is still marked alpha.