It's day one on a new React Native project. You clone a "starter," run it, and get a spinning logo. Two weeks later, three developers have three different ways to style a button, someone has quietly imported AsyncStorage, and nobody knows why CI is red.
I've lived that, so I built the starter I wished I'd had. RN Boilerplate Latest is a runnable product shell with login, tabs, notifications and settings, plus the guardrails that keep a codebase tidy once more than one person touches it: 33 Jest suites, ESLint rules that enforce the architecture, one CI script that works on GitHub and GitLab, and docs good enough to onboard a new hire without a workshop.
Repo: github.com/Ajmal0197/react-native-boilerplate-latest
This post is the full tour. For each piece, I'll tell you what it is and, more importantly, why it's there.
The 60-second version
- Modern base: React Native 0.88.1, React 19.3, TypeScript 6, New Architecture and Hermes on by default.
- Real app, not a demo: auth, tabs, a virtualized photo feed, notifications, settings, three languages (including RTL Arabic).
- Rules that bite: the linter refuses AsyncStorage, deep
../../imports,any, and raw color values. - Quality gate: one command,
yarn ci, runs typecheck, lint, formatting, tests with coverage, and dead-code detection. - Three environments: dev, staging and production, on both Android and iOS.
- MIT licensed. Take it, fork it, argue with it.
Table of contents
- At a glance
- Runtime stack
- Native platform & build pipeline
- Multi-environment config & secrets
- App architecture you inherit
- Path aliases & import discipline
- TypeScript strictness
- ESLint rules
- Prettier, EditorConfig, VS Code
- Git hooks
- Babel setup
- Jest & React Native Testing Library
- Knip
- CI
- SonarQube (local, optional)
- SonarLint
- patch-package
- Reactotron
- Codegen & New Architecture specs
- Security
- NPM scripts cheat sheet
- Docs & contributing workflow
- Who gets what, by role
- Clone checklist
At a glance
| Area | What you get |
|---|---|
| Framework | React Native 0.88.1, React 19.3.0, New Architecture on, Hermes on |
| Language | TypeScript 6, strict plus unused locals/params |
| App features | Auth (mock/real), tabs, photo list, notifications, settings, i18n, Features Lab, BugBubble (non-prod) |
| Tests | 33 test files, coverage thresholds of 80% statements/lines, 60% branches, 75% functions |
| Lint | ESLint 9 flat config: RN, hooks, import order, bans AsyncStorage, bans ../../ imports |
| CI | bash scripts/ci.sh: typecheck, lint, format, tests with coverage, Knip |
| Sonar | Docker Compose community server plus the scanner (local only, not in CI) |
| Tooling | Husky, lint-staged, Conventional Commits, Knip, Prettier, patch-package |
| Envs | Dev / Staging / Production flavors (Android) and schemes (iOS) |
| Docs | README.md, an 848-line docs/DOCUMENTATION.md, and CONTRIBUTING.md |
Runtime stack (what ships in the app)
Everything below is already installed and wired up. Nothing here is a "you should add this later" bullet in a README. I picked each library to answer one question: what will every real app need within the first month?
UI, layout, motion
| Library | Role in this repo |
|---|---|
| react-native-unistyles v3 | The only styling system; theme tokens; Babel plugin for compile-time extraction |
| react-native-reanimated v4 + worklets | UI-thread animations (its Babel plugin goes last in the chain) |
| react-native-gesture-handler | Root wrapper in App.tsx; needed for sheets and navigation |
| react-native-safe-area-context | Safe areas on notched devices |
| react-native-svg + transformer | Icon assets in src/assets/svgs/ |
| @swmansion/react-native-bottom-sheet | Stacked and keyboard sheets in src/components/organisms/ |
| react-native-keyboard-controller | KeyboardProvider; edge-to-edge keyboard handling on forms |
| react-native-toast-message | Themed toasts; API errors surface here by default |
| react-native-root-siblings | Global fullscreen loader overlay |
| react-native-error-boundary | Root crash UI, hooked into the crashReporting facade |
| @legendapp/list | Virtualized home photo feed (PhotoList) |
| react-native-tab-view + pager-view | Features Lab tab demos |
Navigation
| Library | Role |
|---|---|
React Navigation v7 (@react-navigation/native) | NavigationContainer, linking, colors driven by Unistyles |
| native-stack | Auth stack, main stack, modal routes |
| bottom-tabs | Home / Alerts / Settings |
Data, network, storage
| Library | Role |
|---|---|
| axios | A single apiClient, interceptors, 401 refresh, a silent flag |
| Redux Toolkit + react-redux | Server-ish shared state (e.g. homeSlice) |
| zustand | Auth session and theme mode (light/dark/system) |
| react-native-mmkv + nitro-modules | Fast key-value storage with encryption, via @services/storage |
| dayjs | Date formatting service |
Forms, validation, i18n
| Library | Role |
|---|---|
| react-hook-form + @hookform/resolvers | Login and Register screens |
| yup | Schemas under src/features/auth/validation/ |
| i18next + react-i18next + react-native-localize | en, es, ar, with RTL for Arabic |
Notifications & config
| Library | Role |
|---|---|
| @notifee/react-native | Local notifications tab |
| react-native-keys | Per-flavor keys, secure/public split, native JSI config |
| react-native-restart | Restart for RTL or locale switches when needed |
Dev-only in the app binary
| Library | Role |
|---|---|
| @lokal-dev/react-native-bugbubble | In-app network/console debugger, gated by Config.APP_ENV !== 'production' |
Native platform & build pipeline
| Setting | Value |
|---|---|
| New Architecture | newArchEnabled=true in android/gradle.properties |
| Hermes | On; release flags include optimization and source maps |
| Android | Product flavors (development, staging, production), SDK 37, R8 minify and shrinkResources on release |
| iOS | Schemes: Dev, Staging, Production (yarn ios, :staging, :prod) |
| Codegen | package.json → codegenConfig → specs/ (AppSpecs, type all) |
| Release signing | Documented in the README and CONTRIBUTING; CI fails a release build without the Gradle secrets |
A release build here isn't just "debug with a different icon." android/app/proguard-rules.pro keeps React Native, Hermes, Reanimated and the key native classes, so R8 can shrink aggressively without breaking your app at runtime.
One small win: transform-remove-console strips console.log from production builds but leaves warn and error alone. Your debug chatter never reaches users, and real problems still show up.
Multi-environment config & secrets
Almost every team needs dev, staging and production to talk to different servers. Here the committed template is keys.example.json, and the real files (keys.development.json, keys.staging.json, keys.production.json, keys.json) are gitignored.
{ "secure": { "API_BASE_URL": "https://jsonplaceholder.typicode.com", "SECRET_KEY": "REPLACE_WITH_SECRET_KEY", "MMKV_ENCRYPTION_KEY": "REPLACE_16_CHARS" }, "public": { "APP_NAME": "RNBoilerplate (Dev)", "APP_ENV": "development", "USE_MOCK_API": "true", "TIMEOUT_MS": "15000" } } In TypeScript you read it through src/config/env.ts:
-
Config.APP_ENV,Config.API_BASE_URL,Config.USE_MOCK_API -
Config.secureFor('SECRET_KEY')for sensitive values - Production throws if
API_BASE_URLis missing, so you can't accidentally ship a build pointing nowhere. Debug can fall back to JSONPlaceholder.
| Command | Environment |
|---|---|
yarn android / yarn ios | Development |
yarn android:staging / yarn ios:staging | Staging |
yarn android:prod / yarn ios:prod | Production |
App architecture you inherit
The big idea is simple: organize by feature, not by file type. When you work on login, everything about login lives in one folder.
src/features/<name>/ api/ | components/ | hooks/ | screens/ | store/ | types/ | validation/ index.ts ← the only public export surface The sample features are auth, home, notifications and settings. Shared code lives in src/components (atoms → molecules → organisms), src/api, src/services, src/navigation, src/theme, src/hooks and src/native.
That index.ts matters. Other features can only import what it exports, so a feature can change its insides without breaking the rest of the app.
Root app composition (src/App.tsx)
The root is already wrapped with gestures, an error boundary, safe area, keyboard handling, bottom sheets, a global loader, Redux, navigation with deep linking, a toast host, a themed status bar, and BugBubble when not in production. That's the plumbing most apps spend their first sprint on.
Navigation graph
- The auth gate lives in
RootNavigator, driven by Zustand'sisAuthenticated - Tabs when logged in, with stack overlays for
ProductDetail,LanguageSelectandTabViewDemo -
RootStackParamListis typed insrc/navigation/types.ts, so a wrong route name fails at compile time - Deep linking is configured in
src/navigation/linking.ts
State: who owns what
| Layer | Tool | Example |
|---|---|---|
| API-backed shared data | Redux Toolkit | homeSlice, photos |
| Session & UI prefs | Zustand | useAuthStore, useAppStore |
| Persistence | MMKV | via storage in @services/storage |
A handy rule of thumb: if the data came from a server and many screens need it, it's Redux. If it's about this user's session or preferences, it's Zustand. If it must survive an app restart, it goes through MMKV.
The HTTP layer (src/api/)
This is the part I'm proudest of, because it handles the annoying cases for you:
- Bearer token injection and a timeout from config
- Normalized errors (
normalizeApiError), so screens never parse raw axios failures - On a 401: one refresh attempt, then logout if it fails
- Toasts on network/5xx errors unless you pass
{ silent: true } - A
useApiCancellation()hook that aborts requests when a screen unmounts -
AppConstant.cancelAllRequests()on logout, so nothing from the old session leaks into the next
Cross-cutting services
- Global loader and toasts:
AppConstant,Toast,GlobalLoader - Crash reporting: a
setCrashReporter()facade. Plug in Sentry or Crashlytics once, and no screen has to change. - i18n: initialized as an import side effect in
App.tsx - Notifications: a Notifee service plus the Alerts screen
Features Lab
My favorite screen. TabViewDemoScreen is a live playground for tab view, stacked sheets, the keyboard sheet, toasts, forced API errors and cancellation. Open it from Home or Settings on a real device, and you'll understand what the shell can do in about five minutes.
Path aliases & import discipline
Ever seen import x from '../../../../components/Button'? Move a file and it all breaks. Here, TypeScript (tsconfig.json) and Babel (babel-plugin-module-resolver) share the same aliases:
@components, @features, @hooks, @locales, @navigation, @services, @store, @theme, @utils, @api, @assets, @native, @appTypes, @config, @test-utils
ESLint backs it up:
- No imports matching
../../**(type-only imports are allowed) -
import/order:typefirst, then React, React Native, externals, internals, alphabetized - Internal packages are matched by regex (
@api,@components,@features, and so on)
Jest mirrors the same moduleNameMapper in jest.config.js, so tests resolve imports exactly like the app does.
TypeScript strictness
The config extends @react-native/typescript-config and turns the dial up:
| Flag | Effect |
|---|---|
strict: true | Full strict mode |
noUnusedLocals / noUnusedParameters | Dead code fails typecheck |
noImplicitReturns | Every code path must return |
forceConsistentCasingInFileNames | Imports that work on your Mac won't break on Linux CI |
The team rules, written in CONTRIBUTING and enforced by lint:
- No
any(no-explicit-anyis an error) - No
enum; use unions oras const - Typed navigation, typed env, typed i18n keys where configured
ESLint — the rules that protect your architecture
Most lint configs catch typos. This one catches architectural drift. It uses ESLint's flat config in eslint.config.mjs, with typescript-eslint, eslint-plugin-react, react-hooks, eslint-plugin-react-native, import and unused-imports. Prettier conflicts are switched off with eslint-config-prettier.
React Native–specific
| Rule | Level | What it means |
|---|---|---|
react-native/no-inline-styles | warn | Push styles into Unistyles |
react-native/no-color-literals | warn | No raw #fff in components; use theme tokens |
react-native/no-unused-styles | warn | Delete dead style keys |
react-native/split-platform-components | error | Use .ios.tsx / .android.tsx when needed |
react-native/no-single-element-style-arrays | error | Skip the [styles.a] noise |
React & hooks
| Rule | Level |
|---|---|
react-hooks/rules-of-hooks | error |
react-hooks/exhaustive-deps | warn |
react/jsx-no-useless-fragment | warn |
react/self-closing-comp | warn |
TypeScript & architecture
| Rule | Level | What it means |
|---|---|---|
@typescript-eslint/no-explicit-any | error | No escape hatches |
@typescript-eslint/no-restricted-imports | error | Blocks AsyncStorage (the error message points you to MMKV) and blocks ../../ paths (the message points you to aliases) |
unused-imports/no-unused-imports | error | Auto-fixed on save and in lint-staged |
The nice thing about those restricted-import rules is that the error message teaches. A new developer who types the wrong import is told what to use instead.
Code quality
| Rule | Level |
|---|---|
no-console | warn (only warn/error allowed) |
no-debugger / no-alert | error |
prefer-const, no-var, eqeqeq, object-shorthand, prefer-template | error |
no-duplicate-imports | error |
max-lines | warn at 400 lines (blanks and comments excluded) |
Test files (__tests__/ and *.test.tsx) get relaxed rules for any, console and inline styles, since tests are allowed to be scrappy.
Run it with yarn lint or yarn lint:fix.
Prettier, EditorConfig, VS Code
Nobody should debate semicolons in a code review. So:
Prettier (.prettierrc.js): single quotes, trailing commas, semicolons, 2-space tabs, arrowParens: 'avoid'. CI runs yarn format:check on src, __tests__ and specs.
EditorConfig: UTF-8, LF, 2 spaces for JS/TS, 4 for Kotlin/Java/Swift/Gradle, trailing whitespace trimmed (except in Markdown).
VS Code (.vscode/):
- Format on save with Prettier as the default formatter
-
eslint --fixon save (source.fixAll.eslint: always) - Workspace TypeScript SDK from
node_modules - Non-relative, single-quote import preferences
- Recommended extensions: Prettier, ESLint, EditorConfig
- SonarLint rule toggles for noisy rules (more below)
Git hooks: stop bad commits at the door
| Hook | File | Action |
|---|---|---|
| pre-commit | .husky/pre-commit | yarn lint-staged |
| commit-msg | .husky/commit-msg | commitlint conventional check |
lint-staged only touches files you changed, so commits stay fast:
-
*.{ts,tsx,js,jsx,mjs}→eslint --fixthenprettier --write -
*.{json,md,yml,yaml}→prettier --write
commitlint extends @commitlint/config-conventional, so a commit looks like feat(auth): add refresh token rotation. Your git history becomes readable, and changelogs become possible.
Babel: order matters
This is the kind of thing that costs people an afternoon. The plugin order in babel.config.js is deliberate:
-
react-native-unistyles/plugingoes first, for compile-time styles rooted atsrc -
module-resolveruses the same aliases as TypeScript -
transform-remove-consoleruns in production only (error/warnkept) -
react-native-reanimated/pluginmust be last (see the Reanimated docs)
Jest & React Native Testing Library
You get 33 real test files to copy from, not an empty __tests__ folder.
Config highlights (jest.config.js)
- Preset:
@react-native/jest-preset - Setup:
react-native-unistyles/mocksplus__tests__/setup.ts - Coverage is collected from
src/**/*.{ts,tsx}(excludingindex.tsbarrels and.d.ts) - Thresholds: 80% statements/lines, 60% branches, 75% functions. Drop below them and CI fails.
What's tested (33 files)
| Area | Examples |
|---|---|
| App root | App.test.tsx |
| Features | Login, Register, Home, ProductDetail, TabViewDemo, Settings, Notifications |
| API | client.test.ts, errors.test.ts, authApi.test.ts |
| Store | homeSlice, Redux store/hooks, Zustand auth/app stores |
| Components | Button, Text, Toast, GlobalLoader, Stacked/Keyboard sheets |
| Hooks | useApiCancellation, useDebounce, useAppState |
| Services | AppConstant, crashReporting, notification, Config |
| Utils | logger, validators, formatters, platform |
Test infrastructure
-
__tests__/test-utils.tsxis a customrender()that already includes Redux, SafeArea and NavigationContainer, built on React Native Testing Library. Writing a screen test takes a few lines. -
__tests__/setup.tsholds mocks for Reanimated, MMKV, localize, keys, native modules, BugBubble and more - An SVG mock for Jest
Commands: yarn test, yarn test:coverage, and yarn check for the full local gate. Background reading: Jest and the React Native testing guide.
Knip — find the code nobody uses
Every codebase collects dead weight: an unused file here, a forgotten dependency there. Knip (configured in knip.json) scans src/** and specs/** and points it out. It finds unused files, exports and dependencies. The exports rule is set to warn, and known binaries (pod, adb, docker-compose, xed) are ignored.
CI runs yarn knip:check after the tests. An unused dependency still costs you bundle size and widens your attack surface, so catching it early is cheap insurance.
CI: one script, two platforms
The trick is that the logic lives in one shell script instead of being copy-pasted into YAML.
bash scripts/ci.sh # quality (default) bash scripts/ci.sh audit # yarn npm audit --environment production Quality mode does this:
- Corepack → Yarn 3.6.4
yarn install --immutable- Copies
keys.example.jsoninto any missing key files (CI agents need keys to compile) yarn typecheckyarn lintyarn format:checkyarn test --coverage --ciyarn knip:check
Run yarn ci locally and you get the same gates, so there are no "works on my machine, fails in CI" surprises.
GitHub Actions (.github/workflows/ci.yml)
- Triggers on
pushtomainand on all PRs - Concurrency is grouped per commit SHA
- Node version from
.nvmrc, Yarn cache via Corepack - Jobs: quality (required) and audit (
continue-on-error: true)
See the GitHub Actions docs if you want to adapt it.
GitLab CI (.gitlab-ci.yml)
- Runs the same
bash scripts/ci.sh, plus an audit job withallow_failure: true - Yarn cache keyed on
yarn.lock - GitLab CI docs
Using Jenkins, CircleCI or Bitbucket? Run the same shell script and you're done.
SonarQube (local, optional)
This is not part of CI. It's there for teams that want code-smell and security dashboards on their own machine.
| Piece | Purpose |
|---|---|
docker-compose.yml | SonarQube Community on port 9000 |
sonar-project.properties | Project key RN_Boilerplate_Latest, sources in src/, TS language |
@sonar/scan | Host scanner, run with yarn sonar |
yarn sonar:start # Docker up export SONAR_TOKEN=... # Global Analysis Token, never commit it yarn sonar # coverage + upload yarn sonar:open # browser dashboard The token is read from the environment (SONAR_TOKEN), never from git. Coverage upload is skipped in the properties file (sonar.skipCoverage=true), and the tests still run through the Jest thresholds in CI.
SonarLint in the editor
.vscode/settings.json includes SonarLint rule overrides (complexity, empty functions, duplicate strings and so on) toned down for React Native patterns. The goal is for your editor to warn about what you actually care about, instead of nagging you all day.
patch-package
Sometimes a dependency has a bug and the fix hasn't shipped. postinstall runs patch-package to apply small fixes automatically.
| Patch | Why |
|---|---|
@lokal-dev/react-native-bugbubble | React 19-safe async debugger notifications (queueMicrotask) |
react-native-keys | Project-specific native/JS fixes |
The patches live in patches/. If you upgrade either dependency, re-validate its patch first.
Reactotron (dev debugging)
The devDependencies include reactotron-react-native, reactotron-redux and reactotron-plugin-zustand. They're there for Redux/Zustand inspection and action logging without shipping any of it to production. It's a team convention and not mounted in the production App.tsx, so wire it up through optional config.
Codegen & New Architecture specs
If you're coming from the old bridge, this is where the new way of writing native code shows up. The specs/ folder holds:
-
NativeAppDeviceInfo.ts, a TurboModule sample (Settings shows device info) -
NativeBatteryViewNativeComponent.ts, a Fabric view sample
In package.json, codegenConfig sets the name to AppSpecs, type all, and jsSrcsDir to ./specs (more on Codegen).
The native implementations are Kotlin on Android (DeviceInfoModule.kt) and ObjC++/Swift on iOS, with JS wrappers in src/native/.
The rule: any new native surface starts with a spec, not a legacy RCTBridgeModule.
Security: release builds, MMKV, keys
| Topic | Standard |
|---|---|
| Storage | MMKV only; ESLint blocks AsyncStorage imports |
| Keys | react-native-keys secure vs public buckets, with the MMKV encryption key in secure |
| Secrets in git | keys.*.json is ignored; CI uses placeholders |
| Android release | R8 minify and resource shrink; ProGuard rules maintained |
| API keys | Treat the client as hostile and use a backend for privileged operations (see the OWASP Mobile Top 10) |
| Crash reports | Facade pattern, so you can swap vendors without rewiring screens |
A reminder worth repeating: anything inside a mobile app can be extracted by a determined person. Keep truly privileged operations on your server.
NPM scripts cheat sheet
| Script | What you get |
|---|---|
yarn install:all | JS dependencies plus CocoaPods |
yarn start | Metro with reset cache |
yarn android / ios (+ staging/prod) | Flavor/scheme runs |
yarn build:android, bundle:android, build:ios | Store artifacts |
yarn clean:install | Nuclear reinstall |
yarn typecheck / lint / format | Local fixes |
yarn test / test:coverage | Unit and component tests |
yarn check | Full pre-PR gate |
yarn ci | What CI runs, locally |
yarn knip:check | Dead code scan |
yarn sonar:* | Local SonarQube lifecycle |
yarn adb | Port reverse for device debugging |
yarn open:ios / open:android | Open the native IDEs |
The full table is in the README.
Docs & contributing workflow
| Document | Contents |
|---|---|
| README.md | Quick start, commands, how to use theme/i18n/state/API, Sonar troubleshooting |
| docs/DOCUMENTATION.md | Deep dives: Android/iOS mapping tables, TurboModules, sheets, TabView lab, testing |
| CONTRIBUTING.md | Branch naming, yarn ci, commit format, code standards |
Branches follow feat/, fix/ or chore/, cut from main.
When you add a feature, the checklist is:
- Create
src/features/<name>/with anindex.ts - Register it in navigation
- Add locales for en, es and ar
- Write tests under
__tests__/features/<name>/
Reviewers enforce this one, and so does the culture of the repo.
Who gets what, by role
| Role | Day-one wins |
|---|---|
| Junior RN dev | A runnable app, format-on-save, aliases, Features Lab, mock API |
| Mid-level | The Redux/Zustand split, API client patterns, RHF + Yup + i18n forms, 33 tests to copy from |
| Senior / lead | A portable CI script, coverage thresholds, ESLint as law, Knip, multi-env keys, the Codegen native path |
| Android native | The Activity → Screen mapping table in DOCUMENTATION, a Kotlin TurboModule sample |
| iOS native | UIViewController → Screen mapping, an iOS TurboModule sample |
| QA-minded dev | RNTL tests per screen, the error boundary, normalized API errors |
Clone checklist
git clone https://github.com/Ajmal0197/react-native-boilerplate-latest.git cd react-native-boilerplate-latest nvm use && corepack enable yarn install:all cp keys.example.json keys.{development,staging,production,json} # edit SECRET_KEY + MMKV_ENCRYPTION_KEY yarn ci # prove your machine matches CI yarn start # terminal 1 yarn ios # or yarn android You'll need nvm and a working React Native environment. Log in with the mock API, poke around Features Lab, then open eslint.config.mjs and jest.config.js once. That way you'll know what the repo will reject before your reviewer does.
Closing
RN Boilerplate Latest isn't a tutorial app. Think of it as an agreement with your future team: these libraries, these folders, these lint rules, these tests, this CI script. Delete the photo feed and JSONPlaceholder when you're ready, but keep the gates. They're what keep the project pleasant at developer number ten.
If it saves you a week of setup, a star helps other people find it:
⭐ github.com/Ajmal0197/react-native-boilerplate-latest
📖 Deep guide: docs/DOCUMENTATION.md
MIT licensed. Fork it, and if you disagree with a default, open an issue and tell me why. Just know exactly what you're arguing with first.
Last aligned with: RN 0.88.1, React 19.3, 33 Jest suites, README coverage claims, eslint.config.mjs, jest.config.js, scripts/ci.sh.
