Expo Router v3: API Routes, bundle splitting, speed improvements, and more

JAN 23, 2024 by Evan Bacon

Welcome to Expo Router v3, our most powerful release yet! Today we're introducing beta support for the newest Expo platform: Servers. With this, Expo Router is now the first universal, full-stack React framework!

Key Features

• API Routes (beta): Build universal server endpoints for your app and website.
• Bundle splitting (web): Route-based bundle splitting on web for faster page loads.
• Speed improvements: 2x faster static web builds, 30% smaller base JS bundle, added .mjs support.
• Testing library: You can now test and reproduce complex navigation flows with Jest.
• Web Link props: Configure and style <Link /> components with the new target, push, and className props.

Get started with Expo Router v3 today in one line:

npx create-expo-app@latest -t tabs@50

Introducing API routes

Note: API Routes are still in beta during SDK 50.

API Routes are a zero-config system for creating server endpoints with a unified build process. Adding a +api.js extension to a route will ensure it's only rendered on the server. API routes are hosted from the same dev server as the website and app in development and must be deployed to a dynamic hosting service in production.

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

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

export function POST(request: ExpoRequest) {
  const { prompt } = await request.json();
  
  // Do something with the prompt
  return ExpoResponse.json({
    /* ... */
  });
}

You can export any of the following functions GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS from an API route. Unsupported methods will automatically return 405: Method not allowed.

The new server architecture will be used to render universal React Server Components in an upcoming release.

Relative Fetch requests

To better support API Routes, we've added the ability to perform relative fetch requests on native by setting the production server URL in the app.json:

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

This will enable making relative requests with the fetch API, in both development and production environments:

async function fetchHello() {
  // Requests from `http://localhost:8081/hello` in development and `https://my-app.dev/hello` in production.
  const response = await fetch('/hello');
  const data = await response.json();
  
  // Alerts "Hello world"
  alert('Hello ' + data.hello);
}

Supporting 404s with +not-found

API Routes are matched after standard routes. To account for API Routes, we've added an official convention to match all 404 / Not Found routes. By creating a +not-found.js route you can match all remaining requests after API routes have been processed. This is supported on all native platforms, and web in server-mode. A 404 status code will also be returned on web.

Route-based bundle splitting

Expo CLI now supports bundle splitting on async imports (e.g. await import("./route")) when bundling for the web platform. Expo Router automatically splits on routes in the app directory and eagerly loads chunks to prevent network waterfalls on initial requests.

Web-only support is available in Expo Router v3. Support for splitting bundles on native platforms will be included with React Server Component support in the future.

Configurable app directory

You can now change the /app directory to be any directory in your project. This is useful for testing and white-labeling projects with multiple sub-apps.

{
  "plugins": [["expo-router", { "root": "./routes" }]]
}

Avoid changing the root directory as this complicates the build process and may cause unexpected development issues. Opt to use the app and src/app directories instead.

Static font optimization

Fonts loaded with expo-font are now automatically extracted and preloaded on web when using static or server output. This enables fonts to start loading before the JavaScript has finished, leading to better initial styles. This system also enables you to statically render your app even if there's a top-level render guard.

import { useFonts } from 'expo-font';

export default function RootLayout() {
  // `loaded` will be `true` in static websites as the font was eagerly loaded with the HTML before this JS was executed.
  const [loaded] = useFonts({
    inter: require('@/fonts/inter.ttf'),
  });

  if (!loaded) {
    // This will no longer be called on static web, meaning the entire boundary will be statically rendered to searchable HTML.
    return null;
  }

  return <Stack />;
}

New push and navigate behaviors

To fix issues with pushing screens in complex routing scenarios, we've changed the router.push() API to always push new routes, whereas the previous version would pop occasionally. You can use the new router.navigate() API to obtain this previous behavior.

Expo Router testing library

We created a set of Jest utilities that could quickly emulate entire navigation structures.

import { renderRouter, screen } from 'expo-router/testing-library';

it('my-test', async () => {
  const MockComponent = jest.fn(() => <View />);

  renderRouter(
    {
      index: MockComponent,
      'folder/a': MockComponent,
      '(group)/b': MockComponent,
    },
    {
      initialUrl: '/folder/a',
    }
  );

  expect(screen).toHavePathname('/folder/a');
});

New Link props

The Link component now supports target, rel, and download props on web. Link also now has className support which works as-is on web and can be used with tools like Nativewind to add Tailwind support on all platforms.

<Link target="_blank" className="text-blue-300" href="/home" />

Link components currently navigate to the nearest route matching the href prop. You can now force them to always push a new route by passing the new push prop.

// Navigate to the closest route
<Link href="/" />

// Push "/" as a new route
<Link push href="/" />

Faster builds and smaller bundles

npx expo export -p web is over 2x faster for static websites. An average v2 project exported in ~23s, v3 exports in ~11s.

The base JS bundle size for production websites is now 30% smaller (from 1.48mb to 1.05mb). The initial bundle size is further decreased by enabling the new bundle splitting functionality on web.

The URL and URLSearchParams standards are built-in. It was previously necessary to polyfill the web standard URL API. We now ship our own implementation in the expo package, enabling removal of duplicate helper libraries and further reducing bundle size.

Stability and support

In Expo Router v3, we've moved the source code and issue tracking to the expo/expo monorepo. During the migration, we fixed and addressed the majority of issues and bugs regarding Expo Router and added lots more documentation and tests.

Configuration requirements like the Babel plugin have been folded into babel-preset-expo and Expo CLI. Additional Expo Router functionality has been integrated across the SDK with packages like Splash Screen, Linking, and Font.

Expo Router is now more powerful, reliable, and seamless than ever before.

Other Highlights

• Server-hosted dynamic routes on web. The new server output mode supports server navigation to dynamic routes on web. Previously, you could only perform client-side navigation to routes like app/[id].tsx.
• Universal Fast Refresh. Fixed universal Fast Refresh upstream so you no longer need resolutions on react-refresh. The same Fast Refresh implementation now works across all platforms universally and is far more reliable.
• Experimental base URL support. Expo Router now supports deploying to subdomains with experiments.baseUrl. You can now deploy static Expo Router websites to GitHub Pages. This API will be stabilized in SDK 51.
• Improved Tailwind/PostCSS on web. PostCSS with Expo's Metro web will no longer be blocked on caching. Metro CSS is now enabled by default. You can integrate with fantastic UI packages like Shadcn UI (web-only).
• Support for system links. You can now link to popular external URLs like mailto: and sms: which don't follow the standard :// convention.
• Added mjs and cjs support. You can now import .mjs modules as expected without modifying the metro.config.js.
• Custom Metro resolvers and transforms. Users can now extend the Metro resolver and modify the transformer using the Babel caller, enabling better control over the bundling process.
• Improved Typed Routes. You can now generate types in CI with npx expo customize tsconfig.json.
• Improved monorepo support. Projects no longer need expo-yarn-workspaces to enable monorepo support.
• Better source maps. Source map exports in production web are now supported. The npx expo export flag --dump-sourcemap has been renamed to --source-maps. Hermes source maps now work more reliably.
• Improved error messages and code removal. Expo CLI now provides full stack traces for component-based errors, tree shakes all unused platform-specific code, and transforms faster when bundling for Hermes.
• @expo/webpack-config is deprecated in favor of Expo CLI's Metro web. Webpack support will continue to work in SDK 50, but it will not be actively developed, and it will be removed in a future release.
• CSS is enabled by default with Metro web. CSS is not supported on Android and iOS, but on web you can use all CSS features by importing CSS files.
• tsconfigPaths is now enabled in @expo/metro-config by default: Configure the paths property in your tsconfig.json to add path aliases. For example, "@/*": ["src/*"] will allow you to write code like import Button from '@/components/Button';.

Notable breaking changes

• expo-router/babel has been removed. Delete this plugin from your babel.config.js file, and be sure to clear the Metro cache before restarting your dev server.
• router.push default behavior changed. router.push is now router.navigate and the new router.push will always push routes. This is technically a bug fix, but it may cause unexpected changes in complex navigation behavior.
• react-native-gesture-handler is no longer added automatically. You can now choose to optionally add gesture handler if you wish to use the <Drawer /> navigator.
• src directory changed to build. We now ship transpiled JavaScript to production in the expo-router/build/* directory. This is a breaking change if you were imported internals from Expo Router.

Known issues

• API Routes will remain in beta throughout v3. See the list of known limitations for more info.
• Snack does not support Expo Router or API routes.

Upgrading your app

Here's how to upgrade your app to Expo Router v3 from v2:

1. Upgrade your app to SDK 50: Follow the instructions in the SDK 50 release notes.

2. Update the babel.config.js:

   • Remove the expo-router/babel plugin in favor of babel-preset-expo preset.

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    // Remove: plugins: ['expo-router/babel']
  };
};

3. Clear the Metro cache before restarting your dev server:

npx expo start --clear

4. router.push is now router.navigate and the new router.push will always push routes.

5. react-native-gesture-handler is no longer added automatically and must be injected if you wish to use the <Drawer /> navigator.

6. Enable Async Routes to use the new bundle splitting functionality on web.

7. If you have a top-level catch-all route like [...missing].js, rename it to +not-found.js if you plan to use API Routes.

8. If you have custom splash screen handling, change the import of SplashScreen in expo-router to expo-splash-screen.

9. If you were using the hrefAttrs prop on the Link component for adding additional web props, migrate to top-level props by the same name.

10. If you're using the react-native-web style escape hatch to set className on Link components for web, migrate to the top-level className prop.

Compatibility

Ensure you use libraries that are versioned to work with Expo SDK 50:

• expo@^50.0.0
• expo-router@^3.0.0
• react@18.2.0
• react-native@~0.73.2
• react-native-web@~0.19.6
• @react-navigation/native@^6.0.2

You can validate versions automatically with Expo CLI:

npx expo install --check