Expo Router Server API

Common errors

• Error: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an Expo Router API route or other server module, which are typically ESM.
  fix Refactor imports to use ES module `import` syntax (e.g., `import { someFunction } from 'some-package';`).

• 405 Method Not Allowed

  cause An API route was called with an HTTP method that is not explicitly exported by the `+api.ts` file (e.g., calling a `POST` route when only `GET` is exported).
  fix Ensure that the corresponding HTTP method (e.g., `export function POST(request: Request) { ... }`) is defined and exported in your `+api.ts` file for the method you are using.

• Failed to fetch /your-api-route (or similar network error in native builds)

  cause The native application cannot resolve the API route URL, typically because the `origin` is not correctly configured for production deployments, or `web.output: "server"` is missing.
  fix Verify `web.output: "server"` is set in `app.json`. For production native builds, set `"expo": { "extra": { "router": { "origin": "https://your-deployed-server.com" } } }` in your `app.json`.

• Property 'push' does not exist on type 'Omit<Router, "navigate">' (or similar TypeScript error with router methods)

  cause You are using `expo-router`'s navigation functions (like `router.push`) but haven't enabled or correctly configured typed routes, or are trying to access server-only types in a client context.
  fix Run `npx expo customize tsconfig.json` and ensure you start the development server (`npx expo start`) to generate typed routes. Make sure your `tsconfig.json` includes `expo-router/tsconfig.json`.

Warnings

• breaking For Expo Router API routes and server-side features to function correctly, you must configure `"web": { "output": "server" }` in your `app.json` or `app.config.js` file. Omitting this will prevent server bundles from being generated.
  Fix: Add `"web": { "output": "server" }` under the `"expo"` key in your `app.json`.
• gotcha The runtime APIs exposed by `expo-server` (e.g., `origin`, `environment`, `runTask`, `deferTask`) are strictly for server-side code. Attempting to use them in client-side bundles will result in runtime errors.
  Fix: Ensure these imports and calls are isolated to files designated as server-side (e.g., `+api.ts` files or React Server Components).
• gotcha When deploying Expo Router API routes to production or native builds, especially to third-party services, you often need to explicitly set the `origin` property in your `app.json` or `app.config.js` to the deployed server's URL. In development, it automatically points to the dev server.
  Fix: For production, set `"expo": { "extra": { "router": { "origin": "https://your-server.com" } } }`. Remember to remove or conditionally set `origin` for local development if it causes issues.
• gotcha Environment variables behave differently on the server vs. client. Server routes (e.g., `+api.ts`) have access to all environment variables, while client-side code only has access to those prefixed with `EXPO_PUBLIC_`.
  Fix: Use server-side API routes to securely handle sensitive environment variables (e.g., API keys) and avoid exposing them to the client bundle. Always prefix client-facing environment variables with `EXPO_PUBLIC_`.
• deprecated React Server Components (RSC) support in Expo Router, while powerful, is still considered experimental or in beta. APIs may be subject to breaking changes without major SDK version bumps, and some traditional React features (hooks, state, browser APIs) are not available in RSCs.
  Fix: Exercise caution when using RSCs. Test thoroughly, be aware of their limitations, and refer to the latest Expo documentation for best practices and stability notes. Use the 'use client' directive for components requiring client-side interactivity.

Install

• npm install expo-server npm
• yarn add expo-server yarn
• pnpm add expo-server pnpm

Imports

• origin
  wrong:

  const { origin } = require('expo-server');

  correct:

  import { origin } from 'expo-server';

  Expo Router API routes and server modules are primarily ESM. CommonJS 'require' should be avoided.
• environment
  wrong:

  import { ENVIRONMENT } from 'expo-server';

  correct:

  import { environment } from 'expo-server';

  Ensure correct named import; casing matters.
• createRequestHandler
  wrong:

  import { createRequestHandler } from 'expo-server';

  correct:

  import { createRequestHandler } from 'expo-server/adapter/http';

  Specific adapters are imported from sub-paths, not directly from the root package.

Quickstart

Demonstrates creating a basic server-side API route using `expo-server` within an Expo Router project, including environment checks.

/* app.json */
{
  "expo": {
    "web": {
      "output": "server"
    }
  }
}

/* src/app/hello+api.ts */
// Ensure your project has 'web.output': 'server' in app.json for API routes to be bundled.
import { environment, origin } from 'expo-server';

export async function GET(request: Request) {
  const url = new URL(request.url);
  const name = url.searchParams.get('name') || 'world';
  
  console.log(`API Call received from origin: ${origin()}`);
  console.log(`Running in environment: ${environment()}`);

  return Response.json({
    message: `Hello, ${name}! This is a server-side API route.`,
    isProduction: environment() === 'production',
    currentOrigin: origin()
  });
}

// To test, run `npx expo start` and then navigate to `http://localhost:8081/hello` or `http://localhost:8081/hello?name=Alice` in your browser or a tool like curl.
// In a native app, you would fetch from `/hello` and Expo Router would correctly proxy it to the server.