# RNStarterKit

**A CLI that scaffolds production-ready React Native apps with clean architecture and sensible defaults.**

Not a replacement for Expo or React Native CLI — it sits on top of them and structures your project correctly from day one.

```bash
npx @highbeek/create-rnstarterkit myApp
```

---

## Why This Exists

Every serious React Native project ends up making the same decisions:

- Where do API calls live?
- How is auth state managed and persisted?
- What's the folder structure when the app scales?
- How are environment variables typed?

This tool answers those questions upfront. You get a complete, typed, linted project with your chosen stack — ready to build on, not fight against.

---

## Quick Start

```bash
npx @highbeek/create-rnstarterkit myApp
# or
yarn dlx @highbeek/create-rnstarterkit myApp

# Skip prompts with a preset
npx @highbeek/create-rnstarterkit myApp --preset fintech
npx @highbeek/create-rnstarterkit myApp --preset social
npx @highbeek/create-rnstarterkit myApp --preset indie
npx @highbeek/create-rnstarterkit myApp --preset minimal
```

### After scaffolding — React Native CLI projects

Native dependencies need linking via CocoaPods before you can run on iOS:

```bash
cd myApp
npm install
cd ios && pod install && cd ..

# Then run
npx react-native run-ios
npx react-native run-android
```

### After scaffolding — Expo projects

```bash
cd myApp
npx expo start
```

---

## Presets

Presets bundle the most common stack combinations so you can skip all prompts:

| Preset | Platform | State | Auth | Data | Storage | Extras |
|---|---|---|---|---|---|---|
| `minimal` | Expo | None | No | None | None | Bare structure |
| `indie` | Expo | Context API | Yes | React Query | AsyncStorage | Husky |
| `social` | Expo | Zustand | Yes | SWR | AsyncStorage | Sentry, i18n, CI |
| `fintech` | RN CLI | Redux Toolkit | Yes | React Query | MMKV | Sentry, i18n, Maestro, CI |

---

## Interactive Setup

When run without a preset, the CLI walks you through your stack:

```
? Project name:
? Platform:                Expo / React Native CLI
? TypeScript:              Yes / No
? Absolute imports (@/*):  Yes / No
? State management:        None / Context API / Redux Toolkit / Zustand
? Data fetching:           None / React Query / SWR
? Validation:              Formik / React Hook Form / Yup
? Storage:                 AsyncStorage / MMKV / None
? Auth scaffold:           Yes / No
? API client:              Yes / No  →  Fetch / Axios
? Sentry:                  Yes / No
? i18n (i18next):          Yes / No
? Maestro E2E flows:       Yes / No
? NativeWind (Tailwind):   Yes / No
? CI (GitHub Actions):     Yes / No
? Husky pre-commit hooks:  Yes / No
```

---

## Generator Commands

After scaffolding, use the `generate` subcommand to add code that matches your project's setup:

```bash
npx @highbeek/create-rnstarterkit generate screen Dashboard
npx @highbeek/create-rnstarterkit generate component Avatar
npx @highbeek/create-rnstarterkit generate hook useDebounce
npx @highbeek/create-rnstarterkit generate slice cart
```

Generators are context-aware — they read your project's config from `package.json` and produce files with the correct imports for your state manager, platform, and auth setup.

| Command | Output |
|---|---|
| `generate screen Name` | `src/screens/NameScreen.tsx` with correct state hook |
| `generate component Name` | `src/components/Name.tsx` with typed props + StyleSheet |
| `generate hook useName` | `src/hooks/useName.ts` with loading/error boilerplate |
| `generate slice name` | `src/store/nameSlice.ts` + auto-patches `store.ts` |

> `generate slice` only works in Redux Toolkit projects. It automatically adds the reducer to your store.

---

## What Gets Generated

```
<project>/
├── src/
│   ├── api/              # API client + endpoints
│   ├── components/       # Shared UI components + ErrorBoundary
│   ├── config/           # Typed env config
│   ├── context/          # Context API providers (if selected)
│   ├── hooks/            # Shared custom hooks
│   ├── i18n/             # i18next config + locales (if selected)
│   ├── navigation/       # Navigation setup (RN CLI)
│   ├── providers/        # App-level providers
│   ├── screens/          # App screens
│   ├── services/         # Query clients, external services
│   ├── store/            # Redux / Zustand store (if selected)
│   ├── theme/            # Color tokens, spacing, typography
│   ├── types/            # Shared TypeScript types
│   └── utils/            # Shared utilities + Sentry (if selected)
├── .env.example          # Environment variable template
├── .husky/               # Pre-commit hooks (if selected)
├── .maestro/             # E2E flows (if selected)
├── .vscode/              # Editor config + extension recommendations
└── .github/workflows/    # CI pipeline (if selected)
```

---

## Optional Modules

### Auth Scaffold

Three implementations — all include Login/Register screens, protected routes, token persistence, and a ScreenLayout wrapper:

| Option | State | Best For |
|---|---|---|
| Context API | Built-in React | Most apps |
| Redux Toolkit | `@reduxjs/toolkit` | Complex global state |
| Zustand | `zustand` | Minimal, no boilerplate |

### API Client

| Option | Description |
|---|---|
| Fetch | Zero deps — typed wrapper with request/response interceptors |
| Axios | Full Axios instance with error normalisation + typed helpers |

### Data Fetching

| Option | Setup |
|---|---|
| React Query | QueryClient pre-configured with retry + stale time defaults |
| SWR | SWRConfig provider + typed `useSWRFetch` hook |

### Storage

| Option | Description |
|---|---|
| AsyncStorage | Default — async token persistence |
| MMKV | Synchronous, 10x faster, drop-in replacement |

### NativeWind (Tailwind CSS)

Adds `nativewind` + `tailwindcss` and wires everything up for your platform:

| Step | Expo | React Native CLI |
|---|---|---|
| `tailwind.config.js` | content globs for `app/` + `src/` | content globs for `App.tsx` + `src/` |
| `global.css` | created, imported in `app/_layout.tsx` | created, imported in `index.js` |
| `metro.config.js` | wrapped with `withNativeWind` (expo/metro-config) | wrapped with `withNativeWind` (@react-native/metro-config) |
| `babel.config.js` | `jsxImportSource: 'nativewind'` in babel-preset-expo | `nativewind/babel` plugin added |
| `tsconfig.json` | `"nativewind/types"` added to types | same |

After generation, use `className` props directly on React Native components — no extra setup needed.

### Sentry

Adds `@sentry/react-native`, initialises in the app entry point, and exports `captureException` + `addBreadcrumb` helpers. The DSN is read from your environment variables — set `EXPO_PUBLIC_SENTRY_DSN` (Expo) or `SENTRY_DSN` (RN CLI) in your `.env` file.

### i18n

Adds `i18next` + `react-i18next` with:
- Language auto-detection via `react-native-localize`
- English + Spanish locale files as a starting point
- Typed `useAppTranslation` hook

### Maestro E2E

Generates `.maestro/flows/` with welcome, login, and logout flows. Automatically adds a Maestro job to the CI workflow when both are selected.

### CI

GitHub Actions workflow with lint and test jobs on push/PR to `main` and `develop`.

---

## Tooling (Always Included)

| Tool | Config |
|---|---|
| TypeScript | `strict: true`, platform-native tsconfig |
| ESLint | `@react-native` ruleset, `--max-warnings 0` |
| Prettier | `format` script wired to `package.json` |
| Jest | RTL setup, `transformIgnorePatterns` for RN modules |
| VSCode | `extensions.json` + `settings.json` (format on save) |
| `.env.example` | Environment variable template + `.gitignore` entry |
| Theme | `colors.ts`, `spacing.ts`, `typography.ts` tokens |
| ErrorBoundary | Class component with reset, ready to wrap your app |
| Navigation types | `AuthStackParamList`, `MainTabParamList` (RN CLI + auth) |

---

## Architecture

**Typed from the start.** TypeScript strict mode on by default. API responses, environment variables, and navigation params are all typed.

**Thin screens, fat hooks.** Screens handle UI. Business logic, API calls, and state live in hooks and services. Screens don't call APIs directly.

**Non-destructive generation.** `writeIfMissing` is used throughout — the generator never overwrites files you've already customised.

---

## Contributing

```bash
git clone https://github.com/highbeek/rnstarterkit
cd rnstarterkit
npm install
npm run build
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development workflow, testing, and PR guidelines.

---

## Status

Current version: `1.1.0`

Core scaffolding, presets, and generators are stable. Feedback and contributions welcome.

---

## License

MIT
