Setup
Project-Specific Setup

Setting Up NativeExpress

Prerequisites

Before you begin, ensure you have the following installed on your system:

Setup Options

Quick Start Wizard

Complete the following steps to configure your app. The wizard will generate a single CLI command with all your configurations included.

Enter App Details
Create Supabase Project

Go to Supabase and follow the steps below.

1
Navigate to Dashboard
2
Press New Project
3
Choose organization
4
Enter project details like organization name, project name, database password and region.
5
Press Create new project
6
Paste the Supabase Project URL and Anon Key into the fields below.
Create a new project
Register new Bundle Identifier

Go to your Apple Developer Account.

1
Navigate to Identifiers
2
Press +
3
Press Continue twice
4
Enter your description and bundle identifier (e.g., com.company.nativeexpress)
5
Press Register
6
Paste the Bundle Identifier into the field below.
Create a new app identifier
Run Setup Command
1
Open your terminal
2
Navigate to the directory where you want to create your app
3
Run the following command:
npx nativeexpress create-app "undefined" \ --slug "undefined" \ --android-package-name "undefined" \ --scheme "undefined" \ --supabase-url "undefined" \ --supabase-key "undefined" \ --ios-bundle-identifier "undefined"

Interactive CLI

Alternatively, if you prefer to configure everything step by step through the CLI prompts, you can use:

npx nativeexpress create-app my-app-name

This will guide you through various configuration options interactively.

Run the Development Server

Create a prebuild for iOS

Run the following command in your terminal (remove the --platform flag if you want to build for both platforms):

npx expo prebuild --platform ios

Install Pods

Run the following command in your terminal:

cd ios && pod install

Configure Xcode Signing & Capabilities

After installing pods, you need to set up the signing capability in Xcode:

  1. Open Xcode
  2. Click on "Open"
  3. Navigate to the generated iOS folder and open the .xcworkspace file
  4. In the left sidebar, click on the project name
  5. Go to the "Signing & Capabilities" tab
  6. Select your development team
  7. Follow the prompts to complete the signing setup
  8. Be careful to not have any app groups checked that are not intentional

Create a development build for iOS

Run the following command in your terminal:

npx expo run:ios

Start the development server

You can now start and ran the app on the simulator any time you want Run the following command in your terminal:

npx expo start -d

You are now ready to explore the other features of NativeExpress and start building your application!

Database Setup

When you first set up your app, the database will be empty. If you want to populate it with example data and apply initial migrations, you'll need to set up the database. If you prefer to start with an empty database, you can skip this step.

💡

For more detailed information about database management, please refer to the Database Guide.

Run Database Migrations and Seed Data

To initialize your database with migrations and seed data, use one of the following commands in your terminal:

For a linked Supabase project:

supabase db reset --linked

This command will reset your database, apply all migrations, and run the seed.sql file for the linked project.

For a local Supabase project:

supabase db reset

If you're using a local setup, make sure to adjust your .env.local file to connect with the local database before running this command.

Supabase Bucket Setup

💡

This step is optional and can be completed later. However, it is required for avatar image uploads to work in the app.

Create a Supabase Bucket

  1. Go to your Supabase (opens in a new tab) project dashboard
  2. Navigate to the Storage section in the sidebar
  3. Click "Create new bucket"
  4. Name your bucket (e.g., "nativeexpress")
  5. Configure bucket permissions as needed
💡

Depending on your needs, you can:

  • Make the bucket public (anyone can read files)
  • Set up specific access policies (e.g., only authenticated users can upload)
  • Configure RLS policies for fine-grained access control

Configure Environment Variable

Add the bucket name to your .env.local file:

EXPO_PUBLIC_SUPABASE_BUCKET_NAME="your-bucket-name"
Tooling & General SetupTroubleshooting