Using Gatsby with Expo for Web

Please open any issues related to Gatsby with Expo at expo-cli/issues.

Gatsby is a React framework that helps you perform pre-rendering on your websites. Using Gatsby with Expo will enable you to pre-render the web part of your Expo app. You'll also be able to use the web-enabled Expo SDK libraries (eg: Permissions, GestureHandler, Camera) with the Gatsby toolchain!

This guide will show you how to use the Gatsby CLI to develop your websites with the Expo web.

Example

If you'd like to jump right into a working project then check out expo/examples: with-gatsby.

🏁 Setup

We put all of the features for Expo web in the plugin gatsby-plugin-react-native-web so setup would be as easy as possible. This guide will show you how to install and use it. Under the hood it's basically doing what expo start --web or the Expo + Next.js workflows are doing.

Expo projects with Gatsby

For using the Gatsby tools in a universal app with the Expo SDK.

Create a new Expo project: yarn create expo-app
Install Gatsby and the plugin
- using yarn - yarn add gatsby gatsby-plugin-react-native-web
- using npm - npm install --save gatsby gatsby-plugin-react-native-web
Create a gatsby-config.js and use the plugin - touch gatsby-config.js

gatsby-config.js

module.exports = {
  plugins: [
    `gatsby-plugin-react-native-web`,
    /* ... */
  ],
};

Add /.cache and /public to your .gitignore
Run yarn gatsby develop to try it out!
- Open the project in the browser http://localhost:8000/

Gatsby projects with Expo

For using the Expo SDK in a web-only Gatsby project.

Create a new Gatsby project
- Install the CLI - npm install -g gatsby-cli
- Bootstrap - gatsby new gatsby-site
Install the plugin
- using yarn - yarn add react-native-web gatsby-plugin-react-native-web
- using npm - npm install --save react-native-web gatsby-plugin-react-native-web
Create a gatsby-config.js and use the plugin - touch gatsby-config.js

gatsby-config.js

module.exports = {
  plugins: [
    `gatsby-plugin-react-native-web`,
    /* ... */
  ],
};

Install the babel preset
- using yarn - yarn add -D babel-preset-expo
- using npm - npm install --save-dev babel-preset-expo

Create a babel.config.js and use the Babel preset - touch babel.config.js

babel.config.js

module.exports = {
  presets: ['babel-preset-expo'],
};

Add /.expo and /web-build to your .gitignore
Run yarn gatsby develop to try it out!
[optional] You can now install other Expo modules:
- Core packages: yarn add expo
- Gestures: yarn add react-native-gesture-handler
- hooks: yarn add react-native-web-hooks

⌨️ New Commands

You'll want to use the Gatsby CLI to develop the web part of your app now. You should still use expo-cli to run on iOS, and Android.

Starting web
- 🚫 expo start --web
- ✅ yarn gatsby develop
Building web
- 🚫 expo build:web
- ✅ yarn gatsby build
Serving your static project
- 🚫 serve web-build
- ✅ yarn gatsby serve

📁 File Structure

Here is the recommended file structure for a Expo project with Gatsby support.

Expo Gatsby
├── src
│   └── pages ➡️ Routes
│       └── index.tsx ➡️ Entry Point for Gatsby
├── .cache ➡️ Generated Gatsby files (should be ignored)
├── public ➡️ Generated Gatsby files (should be ignored)
├── assets ➡️ All static assets for your project
├── App.tsx ➡️ Entry Point for Mobile apps
├── app.json ➡️ Expo config file
├── gatsby-config.js ➡️ Gatsby config file
└── babel.config.js ➡️ Babel config (should be using `babel-preset-expo`)

Contributing

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

Expo CLI

If you have any problems rendering a certain component with pre-rendering then you can submit fixes to the expo/expo repo:

Expo SDK packages

If you're curious how Expo support works under the hood, you can refer to this pull request:

Expo/Gatsby support PR

Learn more about Gatsby

Learn more about how to use Gatsby in their docs.