React Native Starter

A clean starter template for React Native with Expo Router, TypeScript, and file-based routing.

Quick Start

# Install dependencies (Node 24 from .nvmrc, or 22.13+)
npm ci

# Configure (enables the public demo backends)
cp .env.example .env

# Start development server
npm start

Then press a (Android), i (iOS), or w (web), or scan the QR code with Expo Go.

📖 For detailed setup instructions, see Getting Started Guide

Features

This starter includes everything you need to build a production-ready React Native app:

✅ React Native Paper - Material Design 3 components with dark/light mode
✅ Dark/Light Mode - Automatic system preference detection
✅ API Client - Axios with interceptors for authentication and error handling
✅ Storage Service - AsyncStorage wrapper with TypeScript support
✅ Custom Hooks - useFetch for data fetching with loading/error states
✅ Error Boundary - Global error handling component
✅ Loading States - Built-in loading screen component
✅ Authentication Example - Complete login flow with token management
✅ TypeScript - Full type safety throughout
✅ ESLint + Prettier - Code quality and formatting tools
✅ Example Screens - See features in action

State Management Options

This starter template provides multiple state management solutions to choose from. Each option is available as a separate branch with a corresponding pull request for easy review and integration:

🔴 Redux Toolkit

Branch: state-management/redux
Pull Request: #2

A complete Redux Toolkit implementation with typed hooks, auth slice, and todos slice. Perfect for large-scale applications requiring predictable state management.

Features:

Redux Toolkit with typed hooks
Auth slice for authentication state
Todos slice for todo management
Full TypeScript support

🔵 React Context API

Branch: state-management/react-context
Pull Request: #3

Built-in React Context API with useReducer for state management. No external dependencies required, perfect for smaller to medium-sized applications.

Features:

AuthContext and TodosContext
useReducer pattern for state updates
Zero external dependencies
Native React solution

🟢 Zustand

Branch: state-management/zustand
Pull Request: #4

Lightweight and simple state management library with minimal boilerplate. Great balance between simplicity and power.

Features:

Minimal boilerplate
Simple API
Small bundle size
Easy to learn

🟡 Jotai

Branch: state-management/jotai
Pull Request: #5

Atomic state management with fine-grained reactivity. Excellent for component-level state that needs to be shared across the app.

Features:

Atomic state composition
Fine-grained reactivity
Great performance
Flexible architecture

How to Use

To try out any of these state management solutions:

Checkout the branch:

git checkout state-management/redux  # or react-context, zustand, jotai

Install dependencies:
```
npm install
```
Review the Pull Request to see what changes were made
Merge or cherry-pick the changes you want into your project

Each branch includes complete implementation examples and updated documentation.

Getting Started

For detailed installation and setup instructions, see the Getting Started Guide.

Quick overview:

Prerequisites: Node.js 24 (.nvmrc) or 22.13+; iOS native builds also require Xcode 26.4+ for Expo SDK 57
Install: npm ci
Configure: cp .env.example .env
Run: npm start
Code: Start editing app/(tabs)/index.tsx

Authentication demo

The starter uses DummyJSON for the runnable login example, separately from the JSONPlaceholder Todos API. Sign in with username emilys and password emilyspass. The Home tab then shows "Signed in as …" with a Log out button; the session survives an app restart and logging out clears it. For a real backend, set EXPO_PUBLIC_AUTH_API_URL and adapt the request/response mapping in services/auth.ts to the backend contract.

Navigation

This project uses Expo Router for navigation, which is the recommended approach for Expo projects. Expo Router provides:

File-based routing - Files in the app directory automatically become routes
Built on React Navigation - Full access to React Navigation APIs when needed
Type-safe routes - Automatic TypeScript support for routes
Deep linking - Automatic deep linking configuration
Web support - Static rendering and optimized routing for web

React Native doesn't include built-in navigation, so you need a navigation library. Expo Router is built on top of React Navigation and integrates seamlessly with Expo CLI and bundling.

For more information, see:

Available Scripts

npm start - Start Expo dev server
npm run android - Run on Android emulator/device
npm run ios - Run on iOS simulator/device
npm run web - Run in web browser
npm run lint - Check code quality
npm run lint:fix - Fix linting issues automatically
npm run format - Format code with Prettier
npm run type-check - Check TypeScript types without emitting files
npm test - Run tests

Project Structure

react-native-starter/
├── app/              # Expo Router screens (file-based routing)
│   ├── (tabs)/       # Tab navigation screens
│   └── _layout.tsx   # Root layout with theme provider
├── components/       # Reusable UI components
│   ├── ErrorBoundary.tsx
│   └── LoadingScreen.tsx
├── hooks/            # Custom React hooks
│   └── useFetch.ts   # Data fetching hook
├── services/         # API & storage services
│   ├── api.ts        # Axios client with interceptors
│   └── storage.ts    # AsyncStorage wrapper
├── types/            # TypeScript type definitions
│   └── api.ts        # API response types
├── constants/        # App constants
│   ├── Colors.ts     # Color definitions
│   └── Theme.ts      # React Native Paper theme
├── assets/           # Images, fonts, static files
└── docs/             # Documentation

Key directories:

app/ - All screens go here. Files automatically become routes (Expo Router).
components/ - Reusable UI components used across screens.
hooks/ - Custom React hooks for shared logic (e.g., useFetch).
services/ - API client and storage utilities.
constants/ - App-wide constants like colors and theme config.
types/ - TypeScript interfaces and types.

User Interface

Safe Areas

This project includes react-native-safe-area-context (installed with Expo Router) for handling safe areas on devices with notches and system bars.

Quick example:

import { SafeAreaView } from 'react-native-safe-area-context';

export default function Screen() {
  return <SafeAreaView style={{ flex: 1 }}>{/* Your content */}</SafeAreaView>;
}

See Safe Areas Guide for more information.

UI Components (React Native Paper)

This project includes React Native Paper, a Material Design 3 component library. Paper provides pre-built, accessible components that automatically adapt to light/dark mode.

Quick example:

import { Button, Card, Text } from 'react-native-paper';

export default function Screen() {
  return (
    <Card>
      <Card.Content>
        <Text variant="titleLarge">Card Title</Text>
        <Button mode="contained" onPress={() => console.log('Pressed')}>
          Press me
        </Button>
      </Card.Content>
    </Card>
  );
}

See UI Library Guide for more information on using React Native Paper components and customizing themes.

Assets

Assets (images, fonts, etc.) are stored in the assets/ directory. Import them directly:

import { Image } from 'react-native';

<Image source={require('./assets/icon.png')} />;

See Assets Guide for more information.

Environment Variables

Configuration comes from validated EXPO_PUBLIC_* variables (config/env.ts); a missing or invalid value shows a configuration error screen at startup. Copy .env.example to .env (it enables the public demo backends) and adjust:

cp .env.example .env

All environment variables used in JavaScript must be prefixed with EXPO_PUBLIC_. See Environment Variables Guide for more information.

Development Tools

Expo CLI

Expo CLI is installed automatically with the expo package. Common commands:

Command	Description
`npx expo start`	Start the development server
`npx expo prebuild`	Generate native Android and iOS directories
`npx expo run:android`	Compile and run on Android
`npx expo run:ios`	Compile and run on iOS
`npx expo install <package>`	Install a library with compatible versions
`npx expo lint`	Lint your project files

See Expo CLI documentation for more commands.

EAS CLI

EAS CLI is used for building, submitting, and managing your app. Install it globally:

npm install -g eas-cli

Common commands:

eas build --profile development|preview|production - Build a variant using the profiles in eas.json (requires your own Expo account)
eas submit - Submit your app to app stores
eas update - Create over-the-air (OTA) updates

See EAS CLI documentation for more information.

Expo Doctor

Diagnose issues in your Expo project:

npx expo-doctor

This command checks for common issues in app config, package.json, dependency compatibility, and overall project health.

Expo Tools for VS Code

Install the Expo Tools VS Code extension for:

Autocomplete and IntelliSense for app config files
Debugging with breakpoints and variable inspection

Orbit

Orbit is a macOS and Windows app for:

Installing and launching builds from EAS
Installing and launching updates
Testing on physical devices and emulators

Install with Homebrew (macOS):

brew install expo-orbit

Or download from GitHub releases.

Snack

Snack is an in-browser development environment for:

Sharing code snippets
Experimenting with React Native
Testing prototypes without local setup

Expo Go

Expo Go is a free app for testing your app on physical devices:

Download from App Store (iOS)
Download from Google Play (Android)

Note: Expo Go is great for learning and prototyping, but not recommended for production apps. Use development builds instead.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
__tests__		__tests__
app		app
assets		assets
components		components
config		config
constants		constants
docs		docs
hooks		hooks
scripts		scripts
services		services
types		types
utils		utils
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
app.config.ts		app.config.ts
eas.json		eas.json
eslint.config.js		eslint.config.js
index.ts		index.ts
jest.setup.env.js		jest.setup.env.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

React Native Starter

Quick Start

Features

State Management Options

🔴 Redux Toolkit

🔵 React Context API

🟢 Zustand

🟡 Jotai

How to Use

Getting Started

Authentication demo

Navigation

Available Scripts

Project Structure

User Interface

Safe Areas

UI Components (React Native Paper)

Assets

Environment Variables

Development Tools

Expo CLI

EAS CLI

Expo Doctor

Expo Tools for VS Code

Orbit

Snack

Expo Go

Documentation

Essential Guides

Feature Guides

Additional Guides

Resources

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages