Warning: Support for Next.js is experimental. Please open an issue at expo-cli/issues if you encountered any problems.

💡 Next.js can only be used with Expo for web, this doesn't provide Server-Side Rendering (SSR) for native apps.

TL;DR:

• Init: npx create-react-native-app -t with-nextjs (or npx create-next-app -e with-expo)
• Start: yarn next dev
• Open: http://localhost:3000/
• 🏁 Setup

  • Add Next.js to Expo projects
  • Add Expo to Next.js projects
  • Manual setup
• Guides

  • Deploy to Vercel
  • Image support
  • Font support
  • Offline support
  • Using a custom server
  • Handle server requests
  • Web push notifications support
• API

  • CLI

    • ⚙️ CLI Options
  • Babel
  • Config

    • withExpo
  • Document

    • Customizing the Document
  • Server

    • startServerAsync
    • createServerAsync
    • handleRequest
• Limitations
• Contributing

🏁 Setup

npx create-react-native-app -t with-nextjs

• Web: yarn next dev -- start the Next.js project
• Native: expo start -- start the Expo project

Add Next.js to Expo projects

This is for already existing Expo projects.

Add Expo to Next.js projects

This is for already existing Next.js projects.

Manual setup

Guides

Deploy to Vercel

• Add a build script to your package.json

  {
    "scripts": {
      "build": "next build"
    }
  }
  

• Install the Vercel CLI: npm i -g vercel
• Deploy to Vercel: vercel

Polyfill setImmediate

💡 Fixes setImmediate is not defined error.

• Install: yarn add setimmediate
• Import in pages/_app.js, at the top of the file:

  import 'setimmediate';
  

• Related issue and solution.

Image support

• Install the plugin - yarn add next-images

  • next-images injects a Webpack loader to handle fonts.
  • next-optimized-images is another good solution that you could check out.
• Wrap your Next.js configuration object with the the image method and the Expo method in your next.config.js:

  const { withExpo } = require('@expo/next-adapter');
  const withImages = require('next-images');
  
  module.exports = withExpo(
    withImages({
      projectRoot: __dirname,
    })
  );
  

• Now restart your project and you should be able to load images!

import React from 'react';
import { Image } from 'react-native';

export default function ImageDemo() {
  return <Image source={require('./assets/image.png')} style={{ flex: 1 }} />;
}

Font support

• Install the plugin - yarn add next-fonts

  • next-fonts injects a Webpack loader to handle fonts.
• Wrap the font method with the Expo method in your next.config.js:

  • The order is important because Expo can mix in the location of vector icons to the existing font loader.

  const { withExpo } = require('@expo/next-adapter');
  const withFonts = require('next-fonts');
  
  module.exports = withExpo(
    withFonts({
      projectRoot: __dirname,
    })
  );
  

• Now restart your project and you should be able to load fonts!

import React, { useEffect, useState } from 'react';
import * as Font from 'expo-font';
import { Text } from 'react-native';

export default function FontDemo() {
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    (async () => {
      try {
        await Font.loadAsync({
          // You can get this font on Github: https://shorturl.at/chEHS
          'space-mono': require('./assets/SpaceMono-Regular.ttf'),
        });
      } catch ({ message }) {
        // This will be called if something is broken
        console.log(`Error loading font: ${message}`);
      } finally {
        setLoaded(true);
      }
    })();
  }, []);

  if (!loaded) return <Text>Loading fonts...</Text>;

  return <Text style={{ fontFamily: 'space-mono' }}>Hello from Space Mono</Text>;
}

Offline support

Using a custom server

const { createServerAsync } = require('@expo/next-adapter');
const { parse } = require('url');

createServerAsync(projectRoot, {
  handleRequest(req, res) {
    const parsedUrl = parse(req.url, true);
    const { pathname } = parsedUrl;

    // handle GET request to /cool-file.png
    if (pathname === '/cool-file.png') {
      const filePath = join(__dirname, '.next', pathname);

      app.serveStatic(req, res, filePath);
      // Return true to prevent the default handler
      return true;
    }
  },
}).then(({ server, app }) => {
  const port = 3000;

  server.listen(port, () => {
    console.log(`> Ready on http://localhost:${port}`);
  });
});

Web push notifications support

{
  "version": 2,
  "routes": [
    {
      "src": "/service-worker.js",
      "dest": "/public/service-worker.js",
      "headers": {
        "cache-control": "public, max-age=43200, immutable",
        "Service-Worker-Allowed": "/"
      }
    },
    // If you are using next-offline, change the object below according to their guide.
    {
      "src": "/workbox-service-worker.js",
      "dest": "/public/workbox-service-worker.js",
      "headers": {
        "cache-control": "public, max-age=43200, immutable",
        "Service-Worker-Allowed": "/"
      }
    }
  ]
}

API

CLI

⚙️ CLI Options

Babel

• Always use the universal babel-preset-expo

  • Provides React Native support for all platforms that Expo supports (web, iOS, Android)
• When running in the browser, also use next/babel preset.

Config

withExpo

• Defines a custom pageExtensions which makes Webpack resolve .web.js before .js, we call this feature "platform extensions".
• Wraps the Webpack config in withUnimodules from @expo/webpack-config

  • Makes Babel target all Expo, and React Native packages that you've installed
  • Aliases react-native to react-native-web in the browser
  • Defines the platform constants you get in React Native like __DEV__

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

module.exports = withExpo({
  /* next.config.js code */
});

Document

• Registers your app with AppRegistry from react-native-web to start your project.
• Implements the react-native-web CSS reset.

import Document, { style, getInitialProps } from '@expo/next-adapter/document';

Customizing the Document

import { getInitialProps } from '@expo/next-adapter/document';
import Document, { Head, Main, NextScript } from 'next/document';
import React from 'react';

class CustomDocument extends Document {
  render() {
    return (
      <html>
        <Head>
          <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </html>
    );
  }
}

// Import the getInitialProps method and assign it to your component to ensure the react-native-web styles are used.
CustomDocument.getInitialProps = getInitialProps;

// OR...

CustomDocument.getInitialProps = async props => {
  const result = await getInitialProps(props);
  // Mutate result...
  return result;
};

export default CustomDocument;

Server

import { createServerAsync, startServerAsync, handleRequest } from '@expo/next-adapter';

startServerAsync

• The easiest method for starting an HTTP server with Next.js support.
• Invokes createServerAsync with all of the defaults provided and starts listening.

  • port: 3000
• Returns all of the results createServerAsync (Next app, handle, and HTTP server)

function startServerAsync(
  projectRoot: string,
  {
    port,
  }?: {
    port?: number;
  }
): Promise<{
  app: App;
  handle: Function;
  server: Server;
}>;

createServerAsync

• Create an HTTP server and possibly a Next app, unless one is provided.
• Handle all requests internally, unless the handleRequest option is provided.
• Returns the Next.js app, handle (created with app.getRequestHandler()) and HTTP server.

function createServerAsync(
  projectRoot: string,
  {
    app,
    handleRequest,
  }: {
    app?: App;
    handleRequest?: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void;
  }
): Promise<{
  app: App;
  handle: Function;
  server: Server;
}>;

handleRequest

• Use this if you want to completely skip Expo's server but still ensure that the service-workers are hosted in the Next.js static folder.

handleRequest(
  { projectRoot, app, handle }: {
    projectRoot: string;
    app: App;
    handle: Function;
}, req: IncomingMessage, res: ServerResponse): void;

Limitations or differences comparing to the default Expo for Web

• Unlike the default Expo for Web, Workbox and PWA are not supported by default. Use Next.js plugins such as next-offline instead. Learn more here.
• You might need to use the next-transpile-modules plugin to transpile certain third-party modules in order for them to work (such as Emotion). An easy but fragile way to do this is by defining the package name in your app.json under expo.web.build.babel.include (it's experimental because that's a really deeply nested object).
• Only the Next.js default page-based routing is supported. You'll need to use a completely different routing solution to do native navigation. We strongly recommend react-navigation for this.

Contributing

• @expo/next-adapter

• Expo SDK packages

Learn more about Next.js