# RNStarterKit

**A CLI tool 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 the right way from day one.

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

---

## Why This Exists

Every serious React Native project eventually ends up with the same architecture 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?
- Where does validation logic go?

This tool answers those questions upfront. You get a clean, feature-based structure with your chosen stack — ready to build on, not fight against.

---

## What It Generates

The CLI walks you through a set of prompts and generates a complete project:

```
src/
  app/                   # App entry, shell, providers
  features/
    auth/                # Login, Register screens + auth flow (optional)
  screens/               # Additional screens
  navigation/            # React Navigation or Expo Router setup
  api/                   # Axios/Fetch client + interceptors (optional)
  services/              # React Query client setup (optional)
  store/                 # Redux / Zustand store (optional)
  config/                # Typed environment config
  hooks/                 # Shared custom hooks
  utils/                 # Shared utilities
  components/            # Shared UI components
  constants/             # App-wide constants
  types/                 # TypeScript types and interfaces
  assets/
    images/
    fonts/
```

---

## Installation

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

Or install globally:

```bash
npm install -g @highbeek/create-rnstarterkit
create-rnstarterkit myApp
```

---

## Interactive Setup

The CLI prompts you to configure your stack:

```
? Project name: myApp
? 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
? Form validation: None / Formik / React Hook Form + Yup
? Storage: AsyncStorage / MMKV / None
? Include auth scaffold: Yes / No
? Include API client: Yes / No (Fetch / Axios)
? Include CI setup: Yes / No
```

---

## What's Included

### Platform Templates

| Feature | Expo | React Native CLI |
|---|---|---|
| File-based routing | expo-router | — |
| React Navigation | — | Native Stack v7 |
| TypeScript | Default | Default |
| Babel absolute imports | Optional | Optional |
| ESLint + Prettier | Configured | Configured |
| Jest | Configured | Configured |
| Native iOS/Android | Managed | Full native project |

### Auth Scaffold (Optional)

Three implementations — pick one:

**Context API** — Recommended for most apps. Lightweight, no extra dependencies.

**Redux Toolkit** — If you're using Redux for global state. Comes with auth slice + persistence.

**Zustand** — Minimal API, no boilerplate. Zustand store with AsyncStorage hydration.

All three include:
- Login + Register screens
- Protected route stack
- Token persistence via AsyncStorage
- ScreenLayout wrapper component

### API Client (Optional)

**Fetch** — Zero dependencies, typed wrapper with interceptors.

**Axios** — Full Axios instance with request/response interceptors, error normalisation, and typed response helpers.

### Environment Config

Typed environment variables with platform-aware setup:

```typescript
// config/env.ts
export const ENV = {
  API_BASE_URL: process.env.API_BASE_URL ?? "https://api.example.com",
};
```

Expo uses `EXPO_PUBLIC_*` variables. CLI uses `react-native-dotenv`.

### Data Fetching (Optional)

**React Query** — QueryClient pre-configured, ready to wrap your app.

**SWR** — Installed and ready to use.

### State Management (Optional)

| Option | Package | Use When |
|---|---|---|
| None | — | App state is local |
| Context API | Built-in React | Simple global state |
| Redux Toolkit | @reduxjs/toolkit | Complex state, devtools |
| Zustand | zustand | Minimal, fast, no boilerplate |

### Validation (Optional)

| Option | Packages |
|---|---|
| Formik | formik |
| React Hook Form + Yup | react-hook-form + yup |

### Config / Tooling

- **ESLint** — Extends `@react-native` config
- **Prettier** — Single quotes, trailing commas, arrow parens
- **Babel** — Configured with optional dotenv + module-resolver plugins
- **Jest** — `react-native` preset with example test

---

## Architecture Philosophy

**Feature-based, not layer-based.**

Rather than grouping files by type (all screens together, all hooks together), related code lives together by feature. This scales better as the app grows.

```
features/
  auth/
    screens/
      LoginScreen.tsx
      RegisterScreen.tsx
    hooks/
      useLogin.ts
    api/
      authApi.ts
```

Shared code (components, utils, hooks used across features) lives in `shared/` or `components/` at the top level.

**Thin screens, fat services.**

Screens handle UI and user interaction. Business logic, API calls, and state live in services/hooks. Screens don't call APIs directly.

**Typed from the start.**

TypeScript is on by default. Environment variables are typed. API responses are typed. No `any` defaults.

---

## Roadmap

**In Progress**

- [ ] MMKV storage integration (directory scaffolded, wiring in progress)
- [ ] Theming system (color tokens, typography scale, theme provider)
- [ ] Pre-commit hooks with Husky + lint-staged

**Planned**

- [ ] `@testing-library/react-native` setup
- [ ] GitHub Actions CI workflow template
- [ ] Dark mode support
- [ ] Error boundary scaffold
- [ ] i18n setup (react-i18next)

**Not Planned (Intentionally)**

- Custom UI component library — use your own or NativeBase, Tamagui, etc.
- Analytics or tracking — too opinionated, too many options
- Monorepo setup — out of scope for v1

---

## Status

Current version: `1.0.1-beta.3`

This is a beta release. The core scaffolding (folder structure, auth, API client, state management) is working. Some optional modules (MMKV, theming) are scaffolded but not yet wired.

Feedback and contributions welcome.

---

## Contributing

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

Templates live in `src/templates/`. The generator logic is in `src/generators/appGenerator.ts`. Optional modules are in `src/templates/optional/`.

To test the CLI locally:

```bash
node dist/bin/create-rnstarterkit.js myTestApp
```

---

## License

MIT
