Expo Boilerplate

GitHub Repository

The Expo, React Native, and Dodo Payments boilerplate.

Overview

The Expo boilerplate is a working Expo app that sells a subscription plan through Dodo Payments hosted checkout. It has two parts: an Expo Router app in TypeScript, and a small Express server in server/ that creates checkout sessions with your API key. The app asks the server for a checkout URL, opens it in the system browser with expo-web-browser, and receives the result through a deep link.

The boilerplate uses Expo SDK 54, Expo Router, and TypeScript. The API key stays on the server. The app only knows the server’s URL.

Prerequisites

Node.js 18 or later.
Expo CLI or EAS CLI.
A Dodo Payments account with a product. Create the product under Products in the dashboard.
An iOS Simulator, an Android Emulator, or a physical device.

Quick Start

Clone the Repository

Clone the boilerplate repository and go to the project directory:

git clone https://github.com/dodopayments/expo-boilerplate.git
cd expo-boilerplate

Get Your API Credentials

Get your API key from the Dodo Payments dashboard in test mode:

API Key: Go to Developer → API Keys in your dashboard.

Build in test mode, which simulates payments without moving real money.

Configure Environment Variables

The app and the server each read their own .env file. Copy both example files:

cp .env.example .env
cp server/.env.example server/.env

In server/.env, add your API key. DODOPAYMENTS_RETURN_URL must use the scheme from app.json, which is dodoexpo in the boilerplate:

server/.env

DODOPAYMENTS_API_KEY=your_test_api_key_here
DODOPAYMENTS_ENVIRONMENT=test_mode
DODOPAYMENTS_RETURN_URL=dodoexpo://payment/result
PORT=3000

In the root .env, set EXPO_PUBLIC_BACKEND_URL to the server’s URL, for example http://localhost:3000. The app sends checkout requests to EXPO_PUBLIC_BACKEND_URL/checkout.Then open server/server.js and replace your-product-id with the ID of your product. Product IDs start with pdt_.

Never commit your .env files to version control. The root .gitignore already excludes .env.Never put a Dodo Payments API key in an EXPO_PUBLIC_* variable. Expo embeds these variables in the JavaScript bundle, so anyone who downloads your app can read them. Keep the key on your server, as the boilerplate does, and pass only the resulting checkout_url to the app. See Mobile Integration.

Install Dependencies

Install the packages for the app and for the server:

npm install
cd server && npm install && cd ..

Start the Development Server

Start the backend in one terminal, then start Expo in a second terminal:

# Terminal 1: the checkout server
cd server && npm run dev

# Terminal 2: the Expo app
npx expo start

Press i for the iOS Simulator or a for the Android Emulator, or scan the QR code on your device. The project includes expo-dev-client, and the dodoexpo:// return link needs your app’s own scheme, so run the app in a development build (npx expo run:ios or npx expo run:android) rather than Expo Go.A physical device can’t reach localhost on your computer. To test on a device, set EXPO_PUBLIC_BACKEND_URL to your computer’s local network address, for example http://192.168.1.10:3000.

The home screen shows a plan card with a checkout button. Tap it to open checkout, pay with the test card 4242 4242 4242 4242, and the app opens its payment result screen.

What’s Included

The boilerplate includes:

Checkout Integration

A demo server that creates checkout sessions, and an app service that requests and opens them.

Payment Handling

A result screen that reads the status from the dodoexpo://payment/result deep link and shows success or failure.

TypeScript Support

TypeScript configuration with types for the checkout request and response.

Expo Router

File-based navigation with Expo Router, including a tab layout and the payment result route.

Project Structure

These are the main files in the repository:

expo-boilerplate/
├── app/
│   ├── (tabs)/
│   │   ├── index.tsx          # Home screen with the plan card and checkout button
│   │   └── profile.tsx
│   ├── payment/
│   │   └── result.tsx         # Payment result screen (deep-link target)
│   └── _layout.tsx            # Root layout and deep-link handling
├── components/
│   └── payments/              # PaymentButton, ProductCard, and related UI
├── config/
│   ├── env.ts                 # Reads EXPO_PUBLIC_BACKEND_URL
│   └── product.ts             # Plan name, price text, and features
├── services/
│   └── dodo-payments.ts       # Requests a checkout URL and opens it
├── types/
│   └── dodo-payments.ts       # Checkout types
├── server/                    # Demo Express server that creates checkout sessions
│   ├── server.js
│   └── .env.example
├── .env.example               # App environment variables template
├── app.json                   # App name, scheme, and bundle identifiers
└── package.json

Next Steps

After the boilerplate runs:

Create Your Products

Add products in your Dodo Payments dashboard, and use their IDs in server/server.js.

Customize the Integration

Change the plan text in config/product.ts, and change the app name, scheme, and bundle identifiers in app.json. If you change the scheme, update DODOPAYMENTS_RETURN_URL to match.

Test on Real Devices

Test the payment flow and the deep-link return on physical iOS and Android devices.

Go Live

Replace the demo server with your own backend that authenticates users and grants access from webhooks. Then switch to a live mode API key and build your app for production.

Building for Production

Build store-ready binaries with EAS Build:

Install EAS CLI

npm install -g eas-cli

Configure EAS

The repository has no eas.json. This command creates one:

eas build:configure

Build Your App

For iOS:

eas build --platform ios

For Android:

eas build --platform android

Additional Resources

Mobile Integration Guide

The mobile checkout SDKs, deep-link setup, and mobile checkout settings.

Integration Guide

Checkout sessions, payment links, and webhooks.

API Reference

Every Dodo Payments API endpoint.

Support

For help with the boilerplate:

Ask questions in the Discord community.
Report issues in the GitHub repository.
Email the support team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Overview

Prerequisites

Quick Start

What’s Included

Checkout Integration

Payment Handling

TypeScript Support

Expo Router

Project Structure

Next Steps

Building for Production

Additional Resources

Mobile Integration Guide

Integration Guide

API Reference

Support

GitHub Repository

​Overview

​Prerequisites

​Quick Start

​What’s Included

Checkout Integration

Payment Handling

TypeScript Support

Expo Router

​Project Structure

​Next Steps

​Building for Production

​Additional Resources

Mobile Integration Guide

Integration Guide

API Reference

​Support

Overview

Prerequisites

Quick Start

What’s Included

Project Structure

Next Steps

Building for Production

Additional Resources

Support