⚛️ RN Full-Stack Template

A production-ready React Native + Expo SDK 52 starter template for full-stack mobile apps. Includes file-based routing with Expo Router, type-safe forms, JWT auth, TanStack Query, Zustand state, Tamagui UI, and Jest testing — all wired for development builds.

🚀 Skip the boilerplate. Ship faster with a clean, scalable architecture.

---

✨ Features

Feature	Implementation
📱 Cross-platform mobile	Expo SDK 52 + React Native 0.76
🗂️ File-based routing	Expo Router v4 with typed routes
🎨 Design system	Tamagui 1.120 with light/dark themes
🔐 Authentication	JWT flow with secure token storage
🌐 Server state	TanStack Query v5 + Axios interceptors
🧠 Local state	Zustand stores
📝 Forms	React Hook Form + Zod validation
🖼️ Fast images	react-native-fast-image
🧪 Testing	Jest + React Native Testing Library
🤖 E2E testing	Maestro flows ready
🛠️ DevOps ready	EAS Build + prebuild scripts

---

🛠 Tech Stack

Expo SDK 52 • React Native 0.76 • TypeScript 5.7
Expo Router 4 • Tamagui • TanStack Query • Zustand
React Hook Form • Zod • Axios • MMKV • Keychain
Reanimated • Jest • Maestro

---

📋 System Requirements

• Node.js >= 18
• npm >= 9
• Git
• Android Studio (for Android builds)
• Xcode + macOS (for iOS builds)
• Expo account (optional, for EAS Build)

Verify Node:

node -v
npm -v

---

🚀 Installation

1. Clone the repository

git clone https://github.com/your-username/rn-fullstack-template.git
cd rn-fullstack-template

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Edit .env:

EXPO_PUBLIC_API_URL=https://api.example.com
EXPO_PUBLIC_APP_NAME=RN Full-Stack Template

Variables must start with EXPO_PUBLIC_ to be accessible in the app.

4. Generate native projects

npx expo prebuild --clean

---

💻 Usage

Run on Android

npm run android

Run on iOS

npm run ios

Start Metro only

npm run dev

⚠️ This project uses native modules and is not compatible with Expo Go. Use npm run android / npm run ios or a custom development build.

---

📂 Project Structure

.
├── android/              # Native Android project (generated)
├── ios/                  # Native iOS project (generated)
├── src/
│   ├── api/              # Axios clients, interceptors, endpoints
│   ├── app/              # Expo Router screens and layouts
│   ├── components/       # Reusable UI and screen components
│   ├── hooks/            # Custom React hooks
│   ├── providers/        # App providers
│   ├── services/         # Business logic (auth, storage, theme)
│   ├── store/            # Zustand stores
│   ├── tamagui/          # Tamagui config, tokens, themes
│   ├── tests/            # Test utilities and setup
│   └── utils/            # Helpers and constants
├── maestro/              # E2E test flows
├── app.json              # Expo configuration
├── eas.json              # EAS Build configuration
└── package.json

---

📜 Available Scripts

Script	Description
npm run dev	Start Metro bundler
npm run android	Build and run on Android
npm run ios	Build and run on iOS
npm run web	Start web version
npm run typecheck	Run TypeScript type checking
npm run lint	Run ESLint
npm run lint:fix	Fix ESLint issues automatically
npm run format	Format code with Prettier
npm run test	Run Jest in watch mode
npm run test:ci	Run Jest with coverage report
npm run test:e2e	Run Maestro E2E tests
npm run prebuild	Generate native Android/iOS projects
npm run build:android	Build Android with EAS
npm run build:ios	Build iOS with EAS

---

🧪 Running Tests

# Unit & integration tests
npm run test:ci

# E2E tests (requires running app)
npm run test:e2e

---

🏗️ Build for Production

Using EAS Build

# Android
npm run build:android

# iOS
npm run build:ios

Make sure your app.json and eas.json are configured and your Expo account is logged in.

---

📈 Commit Strategy

To keep the project active and maintain a clean history, follow this commit rhythm:

Frequency	Type of commit	Example
Daily	Small, working changes	feat: add password visibility toggle
Every 2-3 days	Refactor or test improvements	refactor: simplify auth hook
Weekly	Dependency updates or docs	chore: update expo dependencies
Per feature	Squash & merge when complete	feat: complete user profile screen

Use Conventional Commits:

feat:     new feature
fix:      bug fix
refactor: code change without new feature or fix
test:     adding or updating tests
docs:     documentation changes
chore:    maintenance tasks

---

🤝 Contributing

Contributions are welcome. Before submitting a pull request, please run:

npm run typecheck
npm run lint
npm run test:ci

---

📄 License

This project is licensed under the MIT License.

Why MIT? It is the most permissive and widely adopted license for open-source React Native templates. It allows anyone to use, modify, distribute, and even build commercial products from this code with minimal restrictions.

---

🌟 Show Your Support

If this template helps you, please give it a ⭐ on GitHub and share it with other React Native developers.