This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Learn how to render routes to static HTML and CSS files with Expo Router.

To enable Search Engine Optimization (SEO) on the web you must statically render your app. This guide will walk you through the process of statically rendering your Expo Router app.

With static rendering, data loaders are executed during the build process and their results are embedded in the output HTML files.

Setup

{
  "expo": {
    %%placeholder-start%%... %%placeholder-end%%
    "web": {
      "output": "static"
    }
  }
}

Production

In SDK 58 and later, you can combine static rendering with API routes by setting apiRoutes: true in the expo-router config plugin. This exports prerendered HTML and API routes to dist/server, with client assets in dist/client, and requires a deployed server.

To bundle your static website for production, run the export command:

This will create a dist directory with your statically rendered website. If you have files in a local public directory, these will be copied over as well. When API routes are enabled, use npx expo serve to test the production build locally. Otherwise, run the following command and open the linked URL in your browser:

With API routes disabled, this project can be deployed to almost every hosting service. Note that this is not a single-page application, nor does it contain a custom server API. This means dynamic routes (for example, src/app/[id].tsx) will not arbitrarily work. You may need to build a serverless function to handle dynamic routes.

Dynamic Routes

The static output will generate HTML files for each route. This means dynamic routes (src/app/[id].tsx) will not work out of the box. You can generate known routes ahead of time using the generateStaticParams function.

import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';

export async function generateStaticParams(): Promise<Record<string, string>[]> {
  const posts = await getPosts();
  // Return an array of params to generate static HTML files for.
  // Each entry in the array will be a new page.
  return posts.map(post => ({ id: post.id }));
}

export default function Page() {
  const { id } = useLocalSearchParams();

  return <Text>Post {id}</Text>;
}

This will output a file for each post in the dist directory. For example, if the generateStaticParams method returned [{ id: "alpha" }, { id: "beta" }], the following files would be generated:

export async function generateStaticParams(): Promise<Record<string, string>[]> {
  console.log(process.cwd());

  return [];
}

export async function generateStaticParams(): Promise<Record<string, string>[]> {
  return [{ id: 'one' }, { id: 'two' }];
}

export async function generateStaticParams(params: {
  id: 'one' | 'two';
}): Promise<Record<string, string>[]> {
  const comments = await getComments(params.id);
  return comments.map(comment => ({
    ...params,
    comment: comment.id,
  }));
}

Read files using process.cwd()

Since Expo Router compiles your code into a separate directory you cannot use __dirname to form a path as its value will be different than expected.

Instead, use process.cwd(), which gives you the directory where the project is being compiled.

import fs from 'node:fs/promises';
import path from 'node:path';

export async function generateStaticParams(params: {
  id: string;
}): Promise<Record<string, string>[]> {
  const directory = await fs.readdir(path.join(process.cwd(), './posts/'));
  const posts = directory.filter(fileOrSubDirectory => return path.extname(fileOrSubDirectory) === '.md')

  return [{
    id,
    posts,
  }];
}

Root HTML

By default, every page is wrapped with some small HTML boilerplate, this is known as the root HTML.

You can customize the root HTML file by creating a src/app/+html.tsx file in your project. This file exports a React component that only ever runs in Node.js, which means global CSS cannot be imported inside of it. The component will wrap all routes in the app directory. This is useful for adding global <head> elements or disabling body scrolling.

Note: Global context providers should go in the Root Layout component, not the Root HTML component.

In SDK 58 and later, static rendering requires custom HTML components to render the values from useServerDocumentContext(). Render headNodes inside <head> and bodyNodes after children inside <body>.

import { ScrollViewStyleReset, useServerDocumentContext } from 'expo-router/html';
import { type PropsWithChildren } from 'react';

// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  const { headNodes, bodyNodes, htmlAttributes, bodyAttributes } = useServerDocumentContext();

  return (
    <html lang="en" {...htmlAttributes}>
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />

        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />

        {/* Add any additional <head> elements that you want globally available on web... */}
        {headNodes}
      </head>
      <body {...bodyAttributes}>
        {children}
        {bodyNodes}
      </body>
    </html>
  );
}

• The children prop comes with the root <div id="root" /> tag included inside.
• The pathname and params props contain the rendered route's pathname and URL parameters. Available in SDK 58 and later.
• headNodes contains generated metadata and styles, such as React Native web styles.
• bodyNodes includes font resources and JavaScript bundles.
• Global CSS should not be imported into this file. Instead, use the Root Layout. Expo Router traverses the dependency graph starting from the root layout, so importing CSS elsewhere can cause unexpected loading order where node_modules CSS takes precedence over your custom styles.
• Browser APIs like window.location are unavailable in this component as it only runs in Node.js during static rendering.

expo-router/html

The exports from expo-router/html are related to the Root HTML component.

• useServerDocumentContext: Returns the generated head and body nodes and document attributes for your root HTML component to render.
• ScrollViewStyleReset: Root style-reset for full-screen React Native web apps with a root <ScrollView /> should use the following styles to ensure native parity.

Meta tags

In SDK 58 and later, export a generateMetadata() function from a route to include metadata in its generated HTML. Expo CLI resolves this function at build time for each static path.

import type { Metadata } from 'expo-router/server';
import { Text } from 'react-native';

export function generateMetadata(): Metadata {
  return {
    title: 'My Blog Website',
    description: 'This is my blog.',
  };
}

export default function Page() {
  return <Text>About my blog</Text>;
}

The function can be asynchronous and receives undefined as its first argument and the route's parameters as its second argument. Static rendering does not provide a request, including during development. See metadata with server rendering for supported fields and dynamic examples.

Use generateMetadata() for metadata that must be present before JavaScript runs. The <Head> component from expo-router/head can update metadata after hydration, but its tags are not included in the initial static HTML. In SDK 57 and earlier, use <Head> for initial static metadata.

When upgrading from SDK 57, follow Migrate static page metadata to move existing Head tags and document attributes.

Static files

Expo CLI supports a root public directory that gets copied to the dist directory during static rendering. This is useful for adding static files like images, fonts, and other assets.

Some paths such as /assets are reserved by Metro. Avoid placing files in public/assets/ or other reserved paths. See Reserved paths for the complete list.

These files will be copied to the dist directory during static rendering:

Web only: Static assets can be accessed in runtime code using relative paths. For example, the logo.png can be accessed at /logo.png:

import { Image } from 'react-native';

export default function Page() {
  return <Image source={{ uri: '/logo.png' }} />;
}

Fonts

Expo Font has automatic static optimization for font loading in Expo Router. When you load a font with expo-font, Expo CLI will automatically extract the font resource and embed it in the page's HTML, enabling preloading, faster hydration, and reduced layout shift.

The following snippet will load Inter into the namespace and statically optimize on web:

import { Text } from 'react-native';
import { useFonts } from 'expo-font';

export default function App() {
  const [isLoaded] = useFonts({
    inter: require('@/assets/inter.ttf'),
  });

  if (!isLoaded) {
    return null;
  }

  return <Text style={{ fontFamily: 'inter' }}>Hello Universe</Text>;
}

This generates the following static HTML:

/* @info preload the font before the JavaScript loads. */
<link rel="preload" href="/assets/inter.ttf" as="font" crossorigin />
/* @end */
<style id="expo-generated-fonts" type="text/css">
  @font-face {
    font-family: inter;
    src: url(/assets/inter.ttf);
    font-display: auto;
  }
</style>

• Static font optimization requires the font to be loaded synchronously. If the font isn't statically optimized, it could be because it was loaded inside a useEffect, deferred component, or async function.
• Static optimization is only supported with Font.loadAsync and Font.useFonts from expo-font. Wrapper functions are supported as long as the wrappers are synchronous.

Common questions

How do I add a custom server?

There is no prescriptive way to add a custom server. You can use any server you want. However, you will need to handle dynamic routes yourself. You can use the generateStaticParams function to generate static HTML files for known routes.

In SDK 58 and later, set apiRoutes: true in the expo-router config plugin to add API routes alongside your static HTML. To render pages at request time, use server rendering.

Server-side rendering

Rendering at request-time is not supported with web.output: 'static'. To render pages dynamically on each request, use server rendering with web.output: 'server' instead.

Where can I deploy statically rendered websites?

You can deploy your statically rendered website to any static hosting service. Here are some popular options:

• EAS Hosting
• Netlify
• Cloudflare Pages
• AWS Amplify
• Vercel
• GitHub Pages
• Render
• Surge

Note: You don't need to add Single-Page Application styled redirects to your static hosting service. The static website is not a single-page application. It is a collection of static HTML files.