React Native Bare Starter

React native starter project (no Expo) - modern state management, fast storage, and a production-minded foundation.

✨ Features Included

• 🧱 Bare React Native 0.82.1 — full native control, (no Expo lock-in)
• 🧭 React Navigation 7.x — stacks, tabs, modals, predefined presets and options
• 📦 TanStack Query 5.x — Framework agnostic powerful server data fetching library. Caching, updating, retries, invalidation, and persistence.
• 🪶 Zustand 5.x — A small 1KB size, fast state management hook-based API. Eliminating boilerplates and prop drilling.
• ⚡ MMKV Storage 4.3 — react-native-mmkv via Nitro Modules, commonly described as up to 30× faster than AsyncStorage
• 📡 Offline-ready — query persistence, queue/replay, cache restore, and transport-level offline mode for a solid experience on flaky networks
• 🔌 Pluggable transport — adapters for REST, GraphQL, WebSocket, and Firebase, so you can change backend strategy without rewiring the app
• 🎨 Theming — light/dark mode with semantic tokens, ThemeProvider and useTheme() hook.
• 🌍 i18next 25.x — typed translations with a typed useT() hook
• 🖼️ SVG via script — react-native-svg 15.x with scripted icon generation npm run gen:icons
• 🚀 BootSplash 6.x — Shows a splash screen, put your icon into assets/logo.png and execute npm run bootsplash:generate.
• 🧪 Developer experience — Biome 2.x, Jest 29.x, GitHub Actions CI, and Maestro E2E
• AI / agent workflow docs — includes .claude agents and repo rules for more consistent AI-assisted changes

demo-starter.mov

🧭 Project structure

Feature-first structure with clear boundaries.

src/
├── config/       # Env, constants, feature flags
├── navigation/   # App navigation, it's persistence and helpers
├── session/      # App bootstrap and session flow
├── i18n/         # Localization setup and typed translations
├── shared/       # Cross-app code used by multiple features
│   ├── components/
│   ├── hooks/
│   ├── services/
│   ├── stores/   # Global UI state only
│   ├── theme/    # context, provider , tokens
│   ├── types/    
│   └── utils/   
└── features/     # auth, home, settings, user

assets/
├── svgs/                # Source SVGs
├── logo.png             # BootSplash source of truth (`npm run bootsplash:generate`)
├── bootsplash/          # Splash PNGs + manifest (`npm run bootsplash:generate`)
└── icons.ts             # Auto-generated icon registry

• Repository layout → docs/development.md#repository-layout
• Code rules & ownership → AGENTS.md

🛠️ Getting started

Prerequisites

Standard bare react native toolchain:

• Node.js ≥ 20
• Xcode for iOS
• Android Studio + SDK for Android
• CocoaPods for iOS

git clone https://github.com/maximcoding/react-native-starter.git
cd react-native-starter
npm install
npx pod-install ios
cp .env.example .env

Launcher icon (optional): npm run gen:app-icon is independent from splash generation and uses assets/app-icon.png. See docs/development.md.

Edit .env as needed, then:

npm start       # Metro bundler
npm run ios     # or: npm run android

🔐 Environment variables

Values are read at build time via react-native-config. See .env.example. Rebuild the app after changing .env.

Variable	Required	Purpose
API_URL	For real API	Backend base URL
USE_MOCK_API	No	true / 1 uses the mock transport in dev
WS_URL	No	WebSocket base URL
ENV	No	Runtime label: development, staging, production
SENTRY_DSN	No	Enables Sentry when non-empty
SENTRY_ENABLE_IN_DEV	No	1 sends Sentry events from __DEV__
SENTRY_TRACES_SAMPLE_RATE	No	Performance sampling value from 0 to 1
CODEPUSH_KEY_IOS / CODEPUSH_KEY_ANDROID	No	Reserved for OTA; no CodePush SDK ships by default

Useful docs:

• Sentry setup
• OTA / updates policy
• Publishing / discoverability

---

⌨️ Key Commands

Command	What it does
npm start	Start Metro (cache reset)
npm run ios / npm run android	Run on simulator or device
npm run lint	Biome check (read-only)
npm run format	Biome format + safe fixes
npm test	Jest
npx tsc --noEmit	Typecheck
npm run i18n:all	Extract i18n keys + generate types
npm run gen:icons	Regenerate SVG icon registry
npm run android:clean	Clean Android build artifacts

Full command reference: docs/development.md#key-commands

---

🔐 Permissions (A gift pack)

List of full existing native permissions for IOS, and Android , declare only what you actually use. Full catalog: docs/permissions-bare-rn.md

---

📚 Documentation

Topic	Location
Rules, structure & contribution flow	AGENTS.md
Developer reference	docs/development.md
Offline behavior	docs/OFFLINE.md
Permissions catalog	docs/permissions-bare-rn.md
Roadmap	docs/TODO.md
Changelog	CHANGELOG.md

---

🤝 Contributing

Contributions welcome — see CONTRIBUTING.md for branch/PR rules, quality checks, and PR checklist.

---

🚢 CI/CD & Release

GitHub Actions, local release builds, store secrets, Sentry, Maestro, OTA policy, and publishing notes: docs/OPERATIONS.md

Version history: CHANGELOG.md