Skip to content

Commit 9f9c005

Browse files
maximcodingmaximcoding
authored
Revise README for clarity and additional details
Updated README with new features, project structure, and troubleshooting sections.
1 parent 3d60ba9 commit 9f9c005

File tree

1 file changed

+84
-144
lines changed

1 file changed

+84
-144
lines changed

‎README.md‎

Lines changed: 84 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
1-
```md
1+
# React Native Bare Starter
2+
3+
[![Use this template](https://img.shields.io/badge/Use%20this%20template-2ea44f?logo=github&logoColor=white)](https://github.com/maximcoding/react-native-starter/generate)
4+
![CI](https://github.com/maximcoding/react-native-starter/actions/workflows/ci.yml/badge.svg)
5+
![React Native](https://img.shields.io/badge/React%20Native-0.82.1-61DAFB?logo=react&logoColor=white)
6+
![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)
7+
![License](https://img.shields.io/badge/license-MIT-green)
8+
9+
A bare-workflow React Native starter for apps that need more than a demo.
10+
11+
Skip the weeks of boilerplate. Start with strict TypeScript, real navigation, offline-ready data flow, theming, i18n, and quality gates already wired — so you can ship features instead of rebuilding infrastructure.
212

313
---
414

5-
## Quick Start
15+
## 🚀 Quick Start
616

717
```bash
818
git clone https://github.com/maximcoding/react-native-starter.git
@@ -19,146 +29,77 @@ npm start # Metro bundler
1929
npm run ios # or: npm run android
2030
```
2131

22-
> Requires Node ≥ 20, Xcode (iOS), Android Studio + SDK (Android), CocoaPods (iOS).
32+
> **Prerequisites:** Node ≥ 20 · Xcode (iOS) · Android Studio + SDK (Android) · CocoaPods (iOS)
33+
>
2334
> If `npm install` fails on peer deps, try `npm install --legacy-peer-deps`.
2435
2536
---
2637

27-
--------
28-
## ✨ Features Included
29-
- **🧱 Bare React Native** — full native control, no Expo lock-in
30-
- **🧭 Navigation & State** — React Navigation (stacks, tabs, modals), Zustand for global state, TanStack Query for server state with caching, retries, and persistence.
31-
- **📦 TanStack Query** — caching, persistence, retries, and invalidation
32-
- **🪶 Zustand** — lightweight global state without Redux overhead
33-
- **⚡ MMKV Storage** — `react-native-mmkv` via Nitro Modules — up to 30× faster than AsyncStorage.
34-
- **📡 Offline-Ready** — Query persistence, queue/replay, cache restore, and transport-level offline mode for a solid experience on flaky networks.
35-
- **🔌 Pluggable Transport** — Adapters for REST, GraphQL, WebSocket, and Firebase. Swap your backend strategy without rewiring the app.
36-
- **🎨 Theming & i18n** — Light/dark mode with semantic tokens. `i18next` with typed `useT()` hook, ready from day one.
37-
- **🌍 Localization** — typed i18n support from day one
38-
- **🖼️ SVG via script** — easier icon generation and maintenance
39-
- **🚀 BootSplash included** — native splash screen setup already in place
40-
- **🧪 Developer Experience** — Biome linting, Jest tests, GitHub Actions CI, Maestro E2E, SVG icon generation, and native splash screen via BootSplash.
41-
42-
---
43-
44-
## 🧭 Project structure
45-
46-
The starter uses a **feature-first** layout under `src/features` with shared code in `src/shared`.
47-
48-
Use these docs for structure details:
49-
50-
- **Repository layout** → [docs/development.md#repository-layout](https://chatgpt.com/c/docs/development.md#repository-layout)
51-
52-
- **Code rules and ownership** → [AGENTS.md](https://chatgpt.com/c/AGENTS.md)
53-
54-
55-
----------
56-
57-
## 🛠️ Getting started
58-
59-
### Prerequisites
60-
61-
Standard bare React Native toolchain:
62-
63-
- Node.js ≥ 20
64-
65-
- Xcode for iOS
66-
67-
- Android Studio + SDK for Android
68-
69-
- CocoaPods for iOS
70-
71-
72-
### Install notes
73-
74-
If `npm install` fails because of peer dependency conflicts:
75-
76-
```bash
77-
npm install --legacy-peer-deps
78-
79-
```
80-
81-
### Running the app
82-
83-
Keep Metro running in one terminal, then run the native app from another:
84-
85-
```bash
86-
npm start
87-
npm run ios
88-
npm run android
38+
## ✨ Features
8939

90-
```
40+
### 🧱 Core
9141

92-
### Android troubleshooting
42+
- **Bare React Native 0.82** with Hermes — full native control, no Expo lock-in
43+
- **Strict TypeScript** across the entire codebase
44+
- **Feature-first project structure** that scales past the first few screens
9345

94-
- **No connected devices** — start an emulator or connect a device, then run `npm run android:devices`
95-
96-
- **Missing `codegen/jni` / CMake errors** — run `npm run android:clean`, then `npm run android`
97-
98-
- **Still failing** — try `rm -rf node_modules/*/android/build`, reinstall dependencies, and rebuild
99-
100-
- **Need Gradle clean without broken native tasks** — use `npm run android:clean:gradle`
101-
46+
### 🧭 Navigation & State
10247

103-
Full detail: [docs/development.md#android-build](https://chatgpt.com/c/docs/development.md#android-build)
48+
- **React Navigation** — stacks, bottom tabs, and modals already wired
49+
- **TanStack Query** — server state with caching, persistence, retries, and tag-based invalidation
50+
- **Zustand** — lightweight global state without Redux boilerplate
10451

105-
----------
52+
### 📡 Data & Networking
10653

107-
## 🔐 Environment variables
108-
Values are read at build time via react-native-config.
109-
See .env.example. Rebuild the app after changing .env.
54+
- **MMKV Storage** via Nitro Modules — up to 30× faster than AsyncStorage
55+
- **Offline-ready flow** — query persistence, queue/replay, cache restore, transport-level offline mode
56+
- **Pluggable transport layer** — adapters for REST, GraphQL, WebSocket, and Firebase; swap backends without rewiring
11057

111-
| Variable | Required | Purpose |
112-
| ------------------------------------------- | ------------ | ----------------------------------------------------- |
113-
| `API_URL` | For real API | Backend base URL |
114-
| `USE_MOCK_API` | No | `true` / `1` uses the mock transport in dev |
115-
| `WS_URL` | No | WebSocket base URL |
116-
| `ENV` | No | Runtime label: `development`, `staging`, `production` |
117-
| `SENTRY_DSN` | No | Enables Sentry when non-empty |
118-
| `SENTRY_ENABLE_IN_DEV` | No | `1` sends Sentry events from `__DEV__` |
119-
| `SENTRY_TRACES_SAMPLE_RATE` | No | Performance sampling value from `0` to `1` |
120-
| `CODEPUSH_KEY_IOS` / `CODEPUSH_KEY_ANDROID` | No | Reserved for OTA; no CodePush SDK ships by default |
58+
### 🎨 UI & Localization
12159

122-
Useful docs:
60+
- **Theme tokens** — light/dark mode with semantic design tokens, no magic values
61+
- **i18next** — typed `useT()` hook with key extraction and type generation
62+
- **SVG icon pipeline** — scripted generation via `npm run gen:icons`
63+
- **BootSplash** — native splash screen included and ready to customize
12364

124-
Sentry setup
125-
OTA / updates policy
126-
Publishing / discoverability
65+
### 🧪 Quality & CI
12766

128-
----------
67+
- **Biome** for linting and formatting
68+
- **Jest** for unit tests
69+
- **Maestro** for E2E flows
70+
- **GitHub Actions** CI pipeline out of the box
12971

130-
# React Native Bare Starter
72+
---
13173

132-
[![Use this template](https://img.shields.io/badge/Use%20this%20template-2ea44f?logo=github&logoColor=white)](https://github.com/maximcoding/react-native-starter/generate)
133-
![CI](https://github.com/maximcoding/react-native-starter/actions/workflows/ci.yml/badge.svg)
134-
![React Native](https://img.shields.io/badge/React%20Native-0.82.1-61DAFB?logo=react&logoColor=white)
135-
![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)
136-
![License](https://img.shields.io/badge/license-MIT-green)
74+
## 🧭 Project Structure
13775

138-
A bare-workflow React Native starter for apps that need more than a demo.
76+
Feature-first layout under `src/features`, shared code in `src/shared`.
13977

140-
Clean foundation from day one: strict TypeScript, feature-first structure, theme tokens, i18n, offline-ready behavior, and solid quality gates — with room to grow without rebuilding the same setup again.
78+
- **Repository layout** → [docs/development.md#repository-layout](docs/development.md#repository-layout)
79+
- **Code rules & ownership** → [AGENTS.md](AGENTS.md)
14180

14281
---
14382

144-
## Environment Variables
83+
## 🔐 Environment Variables
14584

146-
Values are read at build time via `react-native-config`. See `.env.example` for the full list.
85+
Read at build time via `react-native-config`. See [`.env.example`](.env.example) for defaults. Rebuild the app after any change.
14786

148-
| Variable | Purpose |
149-
|---|---|
150-
| `API_URL` | Backend base URL |
151-
| `USE_MOCK_API` | `true` uses the mock transport; login pre-fills demo credentials |
152-
| `WS_URL` | WebSocket base URL |
153-
| `ENV` | `development` / `staging` / `production` |
154-
| `SENTRY_DSN` | Enables Sentry error tracking |
155-
| `CODEPUSH_KEY_IOS` / `CODEPUSH_KEY_ANDROID` | Reserved for OTA updates |
87+
| Variable | Required | Purpose |
88+
|---|---|---|
89+
| `API_URL` | For real API | Backend base URL |
90+
| `USE_MOCK_API` | No | `true` uses mock transport; login pre-fills demo credentials |
91+
| `WS_URL` | No | WebSocket base URL |
92+
| `ENV` | No | `development` / `staging` / `production` |
93+
| `SENTRY_DSN` | No | Enables Sentry error tracking |
94+
| `SENTRY_ENABLE_IN_DEV` | No | `1` sends Sentry events from `__DEV__` |
95+
| `SENTRY_TRACES_SAMPLE_RATE` | No | Performance sampling (`0`–`1`) |
96+
| `CODEPUSH_KEY_IOS` / `CODEPUSH_KEY_ANDROID` | No | Reserved for OTA (no CodePush SDK ships by default) |
15697

157-
After changing `.env`, rebuild the app.
98+
Related: [Sentry setup](docs/OPERATIONS.md#sentry) · [OTA policy](docs/OPERATIONS.md#over-the-air-updates)
15899

159100
---
160101

161-
## Key Commands
102+
## ⌨️ Key Commands
162103

163104
| Command | What it does |
164105
|---|---|
@@ -172,14 +113,33 @@ After changing `.env`, rebuild the app.
172113
| `npm run gen:icons` | Regenerate SVG icon registry |
173114
| `npm run android:clean` | Clean Android build artifacts |
174115

116+
Full command reference: [docs/development.md#key-commands](docs/development.md#key-commands)
117+
118+
---
119+
120+
## 🛠️ Android Troubleshooting
121+
122+
- **No connected devices** — start an emulator or connect via USB, then `npm run android:devices`
123+
- **CMake / missing `codegen/jni`** — run `npm run android:clean`, then `npm run android`
124+
- **Still failing** — `rm -rf node_modules/*/android/build`, reinstall, rebuild
125+
- **Gradle clean without broken native tasks** — `npm run android:clean:gradle`
126+
127+
Full detail: [docs/development.md#android-build](docs/development.md#android-build)
128+
129+
---
130+
131+
## 🔐 Permissions
132+
133+
Declare only what you actually use. Full catalog: [docs/permissions-bare-rn.md](docs/permissions-bare-rn.md)
134+
175135
---
176136

177137
## 📚 Documentation
178138

179139
| Topic | Location |
180140
|---|---|
181141
| Rules, structure & contribution flow | [AGENTS.md](AGENTS.md) |
182-
| Deep developer reference | [docs/development.md](docs/development.md) |
142+
| Developer reference | [docs/development.md](docs/development.md) |
183143
| Offline behavior | [docs/OFFLINE.md](docs/OFFLINE.md) |
184144
| Operations, CI, releases, Sentry | [docs/OPERATIONS.md](docs/OPERATIONS.md) |
185145
| Permissions catalog | [docs/permissions-bare-rn.md](docs/permissions-bare-rn.md) |
@@ -188,40 +148,20 @@ After changing `.env`, rebuild the app.
188148

189149
---
190150

191-
----------
192-
193-
## 🔐 Permissions
194-
195-
Declare only what you actually use.
196-
197-
Full catalog:
198-
[docs/permissions-bare-rn.md](https://chatgpt.com/c/docs/permissions-bare-rn.md)
199-
200-
----------
201-
202151
## 🤝 Contributing
203152

204-
Contributions are welcome.
153+
Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for branch/PR rules, quality checks, and PR checklist.
205154

206-
See [CONTRIBUTING.md](https://chatgpt.com/c/CONTRIBUTING.md) for:
155+
---
207156

208-
- branch and PR rules
209-
210-
- quality checks
211-
212-
- contribution workflow
213-
214-
- PR checklist
215-
157+
## 🚢 CI/CD & Release
216158

217-
----------
159+
GitHub Actions, local release builds, store secrets, Sentry, Maestro, OTA policy, and publishing notes: [docs/OPERATIONS.md](docs/OPERATIONS.md)
218160

219-
## 🚢 CI/CD & release
161+
Version history: [CHANGELOG.md](CHANGELOG.md)
220162

221-
Operational details:
222-
[docs/OPERATIONS.md](https://chatgpt.com/c/docs/OPERATIONS.md)
163+
---
223164

224-
Version history:
225-
[CHANGELOG.md](https://chatgpt.com/c/CHANGELOG.md)
165+
## License
226166

227-
This covers GitHub Actions, local release builds, optional store secrets, Sentry, Maestro, OTA policy, and publishing notes.
167+
MIT

0 commit comments

Comments
 (0)