Say goodbye to time-consuming setup tasks like restructuring files, installing libraries, and crafting reusable components. Our project boilerplate is your solution to eliminate redundant work when starting from scratch. Built with the latest Expo SDK 54, React 19.1, and modern development practices, it includes only the most commonly-used libraries, so you can hit the ground running with a fully configured setup.

🎯 Pre-configured Features

• 📱 Expo SDK 54 with React 19.1 and React Native 0.81.4
• 🏗️ New Architecture enabled by default for optimal performance
• 🧭 Expo Router v6 with flat config for file-based routing
• 🎨 Light/Dark theme support with automatic detection
• 🔄 Redux Toolkit for predictable state management
• 📦 Environment configuration with dotenvx for dev/staging/prod
• 🚀 CI/CD workflows with EAS Build and Preview channels
• 🛠️ Modern tooling: ESLint 9 (flat config), Prettier, Jest
• 🌐 Multi-platform: iOS, Android, and Web distribution
• 📝 AI-friendly: Claude.md and Cursor rules for AI development
• 🧪 Testing ready: React Native Testing Library setup
• 🔒 Type-safe: Strict TypeScript configuration

🗒️ Requirements

• Node: 20.x or higher
• Expo CLI
• EAS CLI (for builds and deployment)

🚀 Quick Start

1. Download zip or click "Use this template"
2. Install packages with npm install or yarn install
3. Spin up dev environment with npm run dev or yarn run dev

🤖 What's included

File-based Router

The project uses Expo Router with a pre-configured navigation structure which has updated from react-navigation. The navigation structure is based on file-based routing, making it easier to manage and navigate between screens. The project has a pre-configured navigation structure with a drawer and tab navigation. You can easily add new screens and navigations by following the existing structure:

Root (Drawer)
├── Home Tab
│   └── Stack
│       ├── Home Screen
│       └── Details Screen
└── Profile Tab
    └── Stack
        ├── Profile Screen
        └── Details Screen

Global State Management

State Management with Redux Toolkit

---

This project uses Redux Toolkit for global state management, pre-configured with Redux Hooks for immediate use.

Getting Started

1. Explore existing slices in the /slices directory
2. See usage examples in /app/_layout.tsx

Adding New State

1. Copy /slices/app.slice.ts
2. Rename and modify for your needs
3. Add your slice to /utils/store.ts

Development

Redux logger is enabled by default. To disable, remove the logger from /utils/store.ts.

Theme Management

The project simplifies asset and theme management through a centralized /theme directory that handles images, icons, fonts, and colors, with built-in asset preloading and SVG support for optimal performance, while also providing a custom useColorScheme hook (located in /hooks/useColorScheme.ts) that automatically detects and adapts colors based on the current theme across both mobile and web platforms - making it easy to implement dynamic theming by returning the current color scheme name and flags (isDark, isLight) for conditional styling.

Environment Variables

Environment Variables Management

---

The project uses dotenvx to handle environment variables across both Expo CLI and EAS CLI builds. Here's how it works:

Setup Structure

• .env.dev.example - Development environment template
• .env.prod.example - Production environment template
• Configuration in app.config.ts and utils/config.ts

Getting Started with Your Expo Account

1. Rename .env.dev.example to .env.dev
2. Update owner in app.json with your Expo username
3. Set your EXPO_SLUG and EXPO_PROJECT_ID in .env.dev

Adding New Environment Variables

1. Add variables to both .env.dev and .env.prod
2. Include them in app.config.ts under the extra object
3. Define them in utils/config.ts

Verify Configuration

• Check variables in the app's bottom sheet OR...
• Run npm run dev:config:public to view loaded variables in console

Environment Variables & Security

---

The project intentionally avoids using EXPO_PUBLIC_ prefix for environment variables, instead utilizing EAS secrets for enhanced security. Here's why:

Current Approach

• Variables are uploaded to EAS servers as secrets
• Securely accessible only during EAS build and submit processes
• Use npm run dev:secret:push to automatically upload variables from .env.dev and .env.prod

Alternative Approach

If you prefer direct access via process.env:

• Use EXPO_PUBLIC_ prefix for non-sensitive data
• Warning: Never store sensitive information with EXPO_PUBLIC_ prefix as it exposes data to clients
• For sensitive data handling, follow React Native's security guidelines for storing sensitive information

Simplified Distribution

The project streamlines deployment with simple commands - use npm run dev:build:mobile to generate iOS (IPA) and Android (APK) distributions, and npm run dev:deploy:web to deploy the web version to EAS Hosting.

Development and Build Scripts

Development:

• npm run dev - Run on all platforms
• npm run dev:ios - Run iOS only
• npm run dev:android - Run Android only
• npm run dev:web - Run web only

Building:

• npm run dev:build:mobile - Build mobile apps
• npm run dev:build:web - Build web app
• npm run dev:deploy:web - Deploy web app to EAS Hosting

Testing:

• npm run lint - Run ESLint
• npm run format - Run Prettier
• npm run test - Run Jest tests

Code formatting, linting and testing on pre-commit

The project maintains code quality through integrated Eslint, Prettier, and Jest configurations - code is automatically scanned and formatted during development (especially with 'Format on Save' enabled), while pre-commit hooks verify, format, and test your code to ensure all commits meet quality standards.

Release preview channel on Pull-Request (only mobile)

• When you've completed your work and need to share a preview with the QA team, our boilerplate automates the distribution process for you. Here's how it works:

1. Whenever you create a pull request (PR) or merge, it automatically generates a preview channel in your Expo account.
2. You don't need to run 'eas' commands every time you create a PR; the process is streamlined for you.
3. The continuous delivery (CD) process is managed through the preview.yml configuration file, which utilizes expo-github-action.

To set up the CD workflow, follow these steps:

1. Create an EXPO_TOKEN in your Expo account. You can do this by visiting this link.
2. In your GitHub repository, go to Settings, then navigate to Secrets and variables -> Actions -> Add new repository secret. Make sure to name the secret as EXPO_TOKEN.
3. Update name, slug, owner, projectId and url in app.json:
4. Update in name, slug, projectId, ios, android in app.config.ts
5. After you push changes to the main branch, a new preview will be created automatically.

🔧 Available Scripts

The project includes comprehensive development, building, testing, and deployment scripts to streamline your workflow.

Development Commands

• npm run dev - Start Expo development server for all platforms with cache cleared
• npm run dev:ios - Start development server for iOS simulator only
• npm run dev:android - Start development server for Android emulator only
• npm run dev:web - Start development server for web browser only
• npm run dev:doctor - Run Expo diagnostics to check project health

Building & Deployment

• npm run dev:build:mobile - Build iOS (IPA) and Android (APK) using EAS Build for development
• npm run dev:build:web - Export static web application to dist/ directory
• npm run dev:serve:web - Serve the built web app locally (run after dev:build:web)
• npm run dev:deploy:web - Build and deploy web app to EAS Hosting

Environment & Configuration

• npm run dev:secret:push - Upload environment variables from .env.dev to EAS secrets
• npm run dev:secret:list - List all environment variables stored in EAS
• npm run dev:config:public - Display current Expo configuration for debugging

Code Quality & Testing

• npm run lint - Run ESLint to check code quality and style
• npm run lint:staged - Run linting only on staged Git files (used in pre-commit)
• npm run format - Format code using Prettier
• npm run test - Run Jest unit tests
• npm run test:watch - Run Jest tests in watch mode for development
• npm run prepare - Set up Husky Git hooks for pre-commit quality checks

Common Usage Examples

Start development:

npm run dev                    # All platforms
npm run dev:web               # Web only

Build and deploy web:

npm run dev:build:web         # Build static files
npm run dev:serve:web         # Test locally
npm run dev:deploy:web        # Deploy to EAS Hosting

Code quality:

npm run lint                  # Check code
npm run format               # Format code
npm run test                 # Run tests

☀️ Icons

Expo provides a popular set of vector icons. Please search icons from here

🧑‍💻 Need native code?

To generate iOS and Android native code, you can run npx expo prebuild in the project's root directory. For more details and specific instructions, please refer to the Expo documentation page.

📓 License

This project is available under the MIT license. See the LICENSE file for more info.