API Routes

Learn how to create server endpoints with Expo Router.

This feature is still experimental. Available from Expo SDK 50 and Expo Router v3.

Expo Router enables you to write server code for all platforms, right in your app directory.

{
  "web": {
    "bundler": "metro",
    "output": "server"
  }
}

Server features require a custom Node.js server. Most hosting providers support Node.js, including Netlify, Cloudflare, and Vercel.

What are API Routes

API Routes are functions that are executed when a route is matched. They can be used to handle sensitive data, such as API keys securely, or implement custom server logic. API Routes should be executed in a WinterCG-compliant environment.

API Routes are defined by creating files in the app directory with the +api.js extension. For example, the following route handler is executed when the route /hello is matched.

Create an API route

import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export function GET(request: ExpoRequest) {
  return ExpoResponse.json({ hello: 'world' });
}

import { Button } from 'react-native';

async function fetchHello() {
  const response = await fetch('/hello');
  const data = await response.json();
  alert('Hello ' + data.hello);
}

export default function App() {
  return <Button onPress={() => fetchHello()} title="Fetch hello" />;
}

{
  "plugins": [
    [
      "expo-router",
      {
        "origin": "https://evanbacon.dev/"
      }
    ]
  ]
}

Requests

Requests use the global ExpoRequest object. It is a subclass of the standard Request object and provides additional functionality such as the expoUrl object — a URL that has access to query parameters according to the Expo Router file convention.

import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export async function GET(request: ExpoRequest, { post }: Record<string, string>) {
  // const postId = request.expoUrl.searchParams.get('post')
  // fetch data for 'post'
  return ExpoResponse.json({ ... });
}

Request body

Use the request.json() function to access the request body. It automatically parses the body and returns the result.

import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export async function POST(request: ExpoRequest) {
  const body = await request.json();

  return ExpoResponse.json({ ... });
}

Response

Responses use the global ExpoResponse object. It is a subclass of the standard Response object and provides additional functionality such as the ExpoResponse.json — an initializer which automatically stringifies the response body and returns status 200.

import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export function GET() {
  return ExpoResponse.json({ hello: 'universe' });
}

Errors

You can respond to server errors by using the ExpoResponse object.

import { ExpoRequest, ExpoResponse } from 'expo-router/server';

export async function GET(request: ExpoRequest, { post }: Record<string, string>) {
  if (!post) {
    return new ExpoResponse('No post found', {
      status: 404,
      headers: {
        'Content-Type': 'text/plain',
      },
    });
  }
  // fetch data for `post`
  return ExpoResponse.json({ ... });
}

Making requests with an undefined method will automatically return 405: Method not allowed. If an error is thrown during the request, it will automatically return 500: Internal server error.

Bundling

API Routes are bundled with Expo CLI and Metro bundler. They have access to all of the language features as your client code:

• TypeScript — types and tsconfig.json paths.
• Environment variables — server routes have access to all environment variables, not just the ones prefixed with EXPO_PUBLIC_.
• Node.js standard library — ensure that you are using the correct version of Node.js locally for your server environment.
• babel.config.js and metro.config.js support — settings work across both client and server code.

Security

Route handlers are executed in a sandboxed environment that is isolated from the client code. It means you can safely store sensitive data in the route handlers without exposing it to the client.

• Client code that imports code with a secret is included in the client bundle. It applies to all files in the app directory even though they are not a route handler file (such as suffixed with +api.js).
• If the secret is in a <...>+api.js file, it is not included in the client bundle. It applies to all files that are imported in the route handler.
• The secret stripping takes place in expo/metro-config and requires it to be used in the metro.config.js.

Deployment

This is experimental and subject to breaking changes. We have no continuous tests against this configuration.

Every cloud hosting provider needs a custom adapter to support the Expo server runtime. The following third-party providers have unofficial or experimental support from the Expo team.

Before deploying to these providers, it may be good to be familiar with the basics of npx expo export command:

• /dist is the default export directory for Expo CLI.
• Files in /public are copied to /dist on export.
• The @expo/server package is included with expo and delegates requests to the server routes.
• @expo/server does not inflate environment variables from .env files. They are expected to load either by the hosting provider or the user.
• Metro is not included in the server.

Express

#!/usr/bin/env node

const path = require('path');
const { createRequestHandler } = require('@expo/server/adapter/express');

const express = require('express');
const compression = require('compression');
const morgan = require('morgan');

const CLIENT_BUILD_DIR = path.join(process.cwd(), 'dist/client');
const SERVER_BUILD_DIR = path.join(process.cwd(), 'dist/server');

const app = express();

app.use(compression());

// http://expressjs.com/en/advanced/best-practice-security.html#at-a-minimum-disable-x-powered-by-header
app.disable('x-powered-by');

process.env.NODE_ENV = 'production';

app.use(
  express.static(CLIENT_BUILD_DIR, {
    maxAge: '1h',
    extensions: ['html'],
  })
);

app.use(morgan('tiny'));

app.all(
  '*',
  createRequestHandler({
    build: SERVER_BUILD_DIR,
  })
);
const port = process.env.PORT || 3000;

app.listen(port, () => {
  console.log(`Express server listening on port ${port}`);
});

Netlify

This is experimental and subject to breaking changes. We have no continuous tests against this configuration.

const { createRequestHandler } = require('@expo/server/adapter/netlify');

const handler = createRequestHandler({
  build: require('path').join(__dirname, '../../dist/server'),
  mode: process.env.NODE_ENV,
});

module.exports = { handler };

[build]
  command = "expo export -p web"
  functions = "netlify/functions"
  publish = "dist/client"

[[redirects]]
  from = "/*"
  to = "/.netlify/functions/server"
  status = 404

[functions]
  # Include everything to ensure dynamic routes can be used.
  included_files = ["dist/server/**/*"]

[[headers]]
  for = "/dist/server/_expo/functions/*"
  [headers.values]
    # Set to 60 seconds as an example.
    "Cache-Control" = "public, max-age=60, s-maxage=60"

Vercel

This is experimental and subject to breaking changes. We have no continuous tests against this configuration.

const { createRequestHandler } = require('@expo/server/adapter/vercel');

module.exports = createRequestHandler({
  build: require('path').join(__dirname, '../dist/server'),
  mode: process.env.NODE_ENV,
});

{
  "version": 2,
  "outputDirectory": "dist",
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "dist/client"
      }
    },
    {
      "src": "api/index.js",
      "use": "@vercel/node",
      "config": {
        "includeFiles": ["dist/server/**"]
      }
    }
  ],
  "routes": [
    {
      "handle": "filesystem"
    },
    {
      "src": "/(.*)",
      "dest": "/api/index.js"
    }
  ]
}

{
  "buildCommand": "expo export -p web",
  "outputDirectory": "dist/client",
  "functions": {
    "api/index.js": {
      "runtime": "@vercel/node@3.0.11",
      "includeFiles": "dist/server/**"
    }
  },
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/api/index.js"
    }
  ]
}

Known limitations

Several known features are not currently supported in the API Routes beta release.

No dynamic imports

API Routes currently work by bundling all code (minus the Node.js built-ins) into a single file. This means that you cannot use any external dependencies that are not bundled with the server. For example, a library such as sharp, which includes multiple platform binaries, cannot be used. This will be addressed in a future version.

ESM not supported

The current bundling implementation opts to be more unified than flexible. This means the limitation of native not supporting ESM is carried over to API Routes. All code will be transpiled down to Common JS (require/module.exports). However, we recommend you write API Routes using ESM regardless. This will be addressed in a future version.