React Native Starter

Expo + Expo Router + GitHub Actions CI/CD + App Store & Play Store deploy.

Build your app. Push to deploy.

English | 한국어

---

Part of Starter Series — Stop explaining CI/CD to your AI every time. Clone and start.

Docker Deploy · Discord Bot · Telegram Bot · Browser Extension · Electron App · npm Package · React Native · VS Code Extension · MCP Server · Python MCP Server · Cloudflare Pages

---

Quick Start

Via create-starter (recommended):

npx @starter-series/create my-app --template react-native
cd my-app && npm install && npx expo start

Or clone directly:

git clone https://github.com/starter-series/react-native-starter my-app
cd my-app && npm install && npx expo start

Then scan the QR code with Expo Go (or press a for Android / i for iOS).

What's Included

├── app/                        # Expo Router app directory
│   ├── _layout.js              # Root layout — wraps everything in <AuthProvider>
│   ├── (app)/                  # Auth-gated group (redirects to /login if signed out)
│   │   ├── _layout.js          # Guard layout
│   │   ├── index.js            # Home screen
│   │   ├── about.js            # Example second screen
│   │   └── profile.js          # Signed-in user info + sign-out
│   └── (auth)/
│       ├── _layout.js          # Bounces to / if already signed in
│       └── login.js            # "Continue with Google" screen
├── lib/
│   ├── auth-context.js         # AuthProvider + useAuth + handleAuthResult
│   └── env.js                  # Reads EXPO_PUBLIC_GOOGLE_* client IDs
├── assets/                     # App icon, splash, adaptive icon
├── tests/                      # Jest tests (auth-context, screens, structure)
├── .env.example                # Google OAuth client ID placeholders
├── .github/
│   ├── workflows/
│   │   ├── ci.yml              # Lint, test, audit
│   │   ├── cd-android.yml      # Build + submit to Play Store via EAS
│   │   ├── cd-ios.yml          # Build + submit to App Store via EAS
│   │   └── setup.yml           # Auto setup checklist on first use
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/
│   ├── EXPO_SETUP.md           # Expo account + EAS setup
│   ├── APP_STORE_SETUP.md      # Apple Developer + App Store Connect
│   ├── PLAY_STORE_SETUP.md     # Google Play Console setup
│   └── PRIVACY_MANIFEST.md     # iOS PrivacyInfo.xcprivacy + Android photo picker permission
├── scripts/
│   └── bump-version.js         # Bumps version in app.json + package.json
├── eas-hooks/
│   └── eas-build-pre-install.sh  # Example EAS Build hook
├── eslint.config.js            # ESLint v9 flat config
├── app.json                    # Expo config
├── eas.json                    # EAS Build profiles
└── package.json

Features

• Expo + Expo Router -- file-based routing, no native toolchain required locally
• CI Pipeline -- security audit, lint, test on every push and PR
• CD Pipeline -- one-click deploy to App Store and Play Store via EAS Build
• Cloud builds -- EAS compiles native binaries in the cloud (no local Xcode/Android Studio needed)
• Version management -- npm run version:patch/minor/major to bump app.json
• Starter code -- Home + About + Profile screens, Google OAuth login wired in
• Store setup guides -- step-by-step docs for Apple Developer, Google Play Console, and EAS
• Template setup -- auto-creates setup checklist issue on first use

CI/CD

CI (every PR + push to main)

Step	What it does
Security audit	npm audit for dependency vulnerabilities
Lint	ESLint on app and component code
Test	Jest with React Native Testing Library

Security & Maintenance

Workflow	What it does
CodeQL (codeql.yml)	Static analysis for security vulnerabilities (push/PR + weekly)
Maintenance (maintenance.yml)	Weekly CI health check — auto-creates issue on failure
Stale (stale.yml)	Labels inactive issues/PRs after 30 days, auto-closes after 7 more
CHANGELOG (update-changelog.yml)	Appends merged-PR entries to CHANGELOG.md automatically

CD Android (manual trigger via Actions tab)

Step	What it does
CI	Runs full CI first
Version guard	Fails if git tag already exists for this version
EAS Build	eas build --platform android --profile production
EAS Submit	Uploads AAB to Play Store (internal track)
GitHub Release	Creates a tagged release

CD iOS (manual trigger via Actions tab)

Step	What it does
CI	Runs full CI first
Version guard	Fails if git tag already exists for this version
EAS Build	eas build --platform ios --profile production
EAS Submit	Uploads to App Store Connect
GitHub Release	Creates a tagged release

How to deploy:

1. Set up EXPO_TOKEN secret (see below)
2. Configure store accounts (see docs/)
3. Run eas submit:configure once to populate the submit block in eas.json with your Apple/Google credentials
4. Bump version: npm run version:patch
5. Go to Actions tab -> Deploy to Play Store or Deploy to App Store -> Run workflow

GitHub Secrets

Secret	Description
EXPO_TOKEN	Expo access token for EAS CLI authentication

See docs/EXPO_SETUP.md for how to generate the token.

Store credentials are configured through eas.json and eas credentials -- not GitHub Secrets. See:

• docs/APP_STORE_SETUP.md for iOS
• docs/PLAY_STORE_SETUP.md for Android

EAS Build Hooks

Run custom scripts at different stages of the EAS Build lifecycle. Scripts at eas-hooks/<name>.sh are auto-discovered by EAS CLI — no eas.json config needed. An example eas-build-pre-install.sh is included to get you started.

Hook	When it runs	Use for
eas-build-pre-install.sh	Before npm install	Inject env vars, validate required secrets, write .env files
eas-build-post-install.sh	After npm install, before prebuild	patch-package, native module config, Ruby/CocoaPods tweaks
eas-build-on-success.sh	After successful build	Notifications, uploading extra artifacts
eas-build-on-error.sh	On build failure	Error reporting, debugging output
eas-build-on-cancel.sh	On cancellation	Cleanup

Scripts must be executable (chmod +x) and committed with the executable bit set. Use eas secret:create to expose secrets to hooks as env vars.

Docs: Run custom scripts with npm hooks

Development

# Start dev server
npx expo start

# Run on specific platform
npm run android
npm run ios

# Bump version (updates app.json + package.json)
npm run version:patch   # 1.0.0 -> 1.0.1
npm run version:minor   # 1.0.0 -> 1.1.0
npm run version:major   # 1.0.0 -> 2.0.0

# Lint & test
npm run lint
npm test

Why This Over Manual Setup?

	This template	Starting from scratch
CI/CD	Full pipeline included	Set up yourself
EAS config	Pre-configured build profiles	Read docs, trial and error
Store deployment	One-click via GitHub Actions	Manual eas build + eas submit each time
Version management	npm run version:patch auto-bumps	Edit app.json by hand
Setup guides	Step-by-step docs included	Scattered across Expo docs, Apple docs, Google docs
AI/vibe-coding	LLMs generate clean Expo code	LLMs must understand your custom setup
Time to first deploy	Minutes (after store account setup)	Hours of configuration

The key insight: EAS handles native builds in the cloud -- no local Xcode or Android Studio needed for CI/CD. This template wires that up to GitHub Actions so you get one-click deploys from day one.

Auth (Google OAuth, wired up)

Google sign-in is built in with expo-auth-session + expo-secure-store. Routes under app/(app)/ are gated — signed-out users get bounced to /login. Tokens live in the iOS Keychain / Android Keystore, never AsyncStorage.

Setup:

1. Google Cloud Console → Credentials → Create OAuth client ID. Create three:
   • Web application (required — used by the Expo AuthSession proxy in dev)
   • iOS — bundle ID = ios.bundleIdentifier from app.json
   • Android — package = android.package, SHA-1 from your keystore (eas credentials will show it)
2. cp .env.example .env and paste the client IDs:

   EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=...
   EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=...
   EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID=...
   

3. npx expo start and tap Continue with Google.

Without client IDs, the login button surfaces a clear error message — it won't crash. Swap providers by replacing expo-auth-session/providers/google inside lib/auth-context.js.

Docs: Expo Google authentication guide.

What about TypeScript?

This template uses JavaScript to stay lightweight. To add TypeScript:

1. Add typescript and @types/react to devDependencies
2. Add a tsconfig.json
3. Rename .js files to .tsx

Expo supports TypeScript out of the box -- no extra configuration needed.

Design Intent

• Cloud-native builds. EAS compiles native binaries off-device so CI/CD runs without local Xcode or Android Studio.
• Auth gating via route groups. app/(app)/ is the protected zone — there is no "auth check" scattered across screens.
• Secrets in the OS keychain. Tokens go to iOS Keychain / Android Keystore through expo-secure-store, never AsyncStorage.
• Lint, test, audit on every push. Supply-chain hardening (--ignore-scripts, pinned gitleaks, CodeQL) is on by default — not an afterthought.

Non-Goals

• TypeScript by default. Stays JS to keep the template small; opt-in steps are documented above.
• Custom native modules. Anything requiring expo prebuild + native code is out of scope. Use a bare workflow if you need it.
• Backend. This is the client only. Pair with a separate API repo.
• State management library. No Redux/Zustand/etc. — the auth context is the only global state shipped.

Contributing

PRs welcome. Please use the PR template.

License

MIT