---
modificationDate: July 29, 2026
title: Using Next.js with Expo for web
description: A guide for integrating Next.js with Expo for the web.
---

<AgentInstructions>

## Submitting Feedback

If you encounter errors, misleading or outdated information, report it so Expo can be improved:

Preferred command:
npx --yes submit-expo-feedback@latest --category docs --subject "/guides/using-nextjs/" "<actionable feedback>"

Direct HTTP fallback:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/using-nextjs/","feedback":"🤖 Agent feedback for docs: <specific, actionable description> (<model>, <harness>)"}'

Only submit when you have something specific and actionable to report. Try to give the most context.

## Navigation

When answering a related or follow-up question, fetch the relevant page below as Markdown (.md) instead of guessing; use llms.txt for the full map.

You are here: Guides > Integrations > Web apps
Pages in this section:
- [Using Next.js](https://docs.expo.dev/guides/using-nextjs.md) (this page)
Full documentation tree: [llms.txt](https://docs.expo.dev/llms.txt)

</AgentInstructions>

This documentation is available as Markdown for AI agents and LLMs. See the [full Markdown index](/llms.txt) or append .md to any documentation URL.

# Using Next.js with Expo for web

A guide for integrating Next.js with Expo for the web.

> Using Next.js is not an official part of Expo's universal app development workflow.

[Next.js](https://nextjs.org/) is a React framework that provides simple page-based routing as well as server-side rendering. To use Next.js with the Expo SDK, we recommend using [`@expo/next-adapter`](https://github.com/expo/expo-cli/tree/main/packages/next-adapter) library to handle the configuration.

Using Expo with Next.js means you can share some of your existing components and APIs across your mobile and web app. Next.js has its own CLI that you'll need to use when developing for the web platform, so **you'll need to start your web projects with the Next.js CLI and not with `npx expo start`**.

> Next.js can only be used with Expo for web as there is no support for Server-Side Rendering (SSR) for native apps.

## Automatic setup

To quickly get started, create a new project using [with-nextjs](https://github.com/expo/examples/tree/master/with-nextjs) template:

```sh
# npm
npx create-expo-app -e with-nextjs

# yarn
yarn create expo-app -e with-nextjs

# pnpm
pnpm create expo-app -e with-nextjs

# bun
bun create expo -e with-nextjs
```

-   **Native**: `npx expo start` — start the Expo project
-   **Web**: `npx next dev` — start the Next.js project

## Manual setup

### Install dependencies

Ensure you have `expo`, `next`, `@expo/next-adapter` installed in your project:

```sh
# npm
npm install expo next @expo/next-adapter

# yarn
yarn add expo next @expo/next-adapter

# pnpm
pnpm add expo next @expo/next-adapter

# bun
bun add expo next @expo/next-adapter
```

### Transpilation

Configure Next.js to transform language features:

#### Next.js with swc. (Recommended)

Using Next.js with SWC is recommended. You can configure the [**babel.config.js**](/versions/latest/config/babel.md) to only account for native:

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

You will also have to [force Next.js to use SWC](https://nextjs.org/docs/messages/swc-disabled) by adding the following to your **next.config.js**:

```js
module.exports = {
  experimental: {
    forceSwcTransforms: true,
  },
};
```

#### Next.js with Babel. (Not recommended)

Adjust your **babel.config.js** to conditionally add `next/babel` when bundling with webpack for web:

```js
module.exports = function (api) {
  // Detect web usage (this may change in the future if Next.js changes the loader)
  const isWeb = api.caller(
    caller =>
      caller && (caller.name === 'babel-loader' || caller.name === 'next-babel-turbo-loader')
  );
  return {
    presets: [
      // Only use next in the browser, it'll break your native project
      isWeb && require('next/babel'),
      'babel-preset-expo',
    ].filter(Boolean),
  };
};
```

### Next.js configuration

Add the following to your **next.config.js**:

```js
const { withExpo } = require('@expo/next-adapter');

module.exports = withExpo({
  // transpilePackages is a Next.js +13.1 feature.
  // older versions can use next-transpile-modules
  transpilePackages: [
    'react-native',
    'react-native-web',
    'expo',
    // Add more React Native/Expo packages here...
  ],
});
```

The fully qualified Next.js config may look like:

```js
const { withExpo } = require('@expo/next-adapter');

/** @type {import('next').NextConfig} */
const nextConfig = withExpo({
  reactStrictMode: true,
  swcMinify: true,
  transpilePackages: [
    'react-native',
    'react-native-web',
    'expo',
    // Add more React Native/Expo packages here...
  ],
  experimental: {
    forceSwcTransforms: true,
  },
});

module.exports = nextConfig;
```

### React Native Web styling

The package `react-native-web` builds on the assumption of reset CSS styles. Here's how you reset styles in Next.js using the **pages** directory.

```jsx
import { Children } from 'react';
import Document, { Html, Head, Main, NextScript } from 'next/document';
import { AppRegistry } from 'react-native';

// Follows the setup for react-native-web:
// https://necolas.github.io/react-native-web/docs/setup/#root-element
// Plus additional React Native scroll and text parity styles for various
// browsers.
// Force Next-generated DOM elements to fill their parent's height
const style = `
html, body, #__next {
  -webkit-overflow-scrolling: touch;
}
#__next {
  display: flex;
  flex-direction: column;
  height: 100%;
}
html {
  scroll-behavior: smooth;
  -webkit-text-size-adjust: 100%;
}
body {
  /* Allows you to scroll below the viewport; default value is visible */
  overflow-y: auto;
  overscroll-behavior-y: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -ms-overflow-style: scrollbar;
}
`;

export default class MyDocument extends Document {
  static async getInitialProps({ renderPage }) {
    AppRegistry.registerComponent('main', () => Main);
    const { getStyleElement } = AppRegistry.getApplication('main');
    const page = await renderPage();
    const styles = [
      <style key="react-native-style" dangerouslySetInnerHTML={{ __html: style }} />,
      getStyleElement(),
    ];
    return { ...page, styles: Children.toArray(styles) };
  }

  render() {
    return (
      <Html style={{ height: '100%' }}>
        <Head />
        <body style={{ height: '100%', overflow: 'hidden' }}>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
```

```jsx
import Head from 'next/head';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Head>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </Head>
      <Component {...pageProps} />
    </>
  );
}
```

## Transpiling modules

By default, modules in the React Native ecosystem are not transpiled to run in web browsers. React Native relies on advanced caching in Metro to reload quickly. Next.js uses webpack, which does not have the same level of caching, so no node modules are transpiled by default. You will have to manually mark every module you want to transpile with the `transpilePackages` option in **next.config.js**:

```js
const { withExpo } = require('@expo/next-adapter');

module.exports = withExpo({
  experimental: {
    transpilePackages: [
      // NOTE: Even though `react-native` is never used in Next.js,
      // you need to list `react-native` because `react-native-web`
      // is aliased to `react-native`.
      'react-native',
      'react-native-web',
      'expo',
      // Add more React Native/Expo packages here...
    ],
  },
});
```

## Deploy to Vercel

This is Vercel's preferred method for deploying Next.js projects to production.

Add a `build` script to your **package.json**:

```json
{
  "scripts": {
    "build": "next build"
  }
}
```

Install the Vercel CLI:

```sh
# npm
npm install --global vercel

# yarn
yarn global add vercel

# pnpm
pnpm add --global vercel

# bun
bun add --global vercel
```

Deploy to Vercel:

```sh
vercel
```

## Limitations or differences compared to the default Expo for Web

Using Next.js for the web means you will be bundling with the Next.js webpack config. This will lead to some core differences in how you develop your app vs your website.

-   Expo Next.js adapter does not support the experimental **app** directory.
-   For file-based routing on native, we recommend using [Expo Router](https://github.com/expo/router).

## Contributing

If you would like to help make Next.js support in Expo better, feel free to open a PR or submit an issue:

-   [@expo/next-adapter](https://github.com/expo/expo-cli/tree/main/packages/next-adapter)

## Troubleshooting

### Cannot use import statement outside a module

Figure out which module has the import statement and add it to the `transpilePackages` option in **next.config.js**:

```js
const { withExpo } = require('@expo/next-adapter');

module.exports = withExpo({
  experimental: {
    transpilePackages: [
      'react-native',
      'react-native-web',
      'expo',
      // Add the failing package here, and restart the server...
    ],
  },
});
```