{"id":48114036,"url":"https://github.com/maximcoding/react-native-cli-starter","last_synced_at":"2026-04-04T16:13:28.493Z","repository":{"id":333739568,"uuid":"1127741788","full_name":"maximcoding/react-native-cli-starter","owner":"maximcoding","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-20T19:34:57.000Z","size":2952,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-21T04:35:55.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximcoding.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T14:04:47.000Z","updated_at":"2026-01-20T19:34:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximcoding/react-native-cli-starter","commit_stats":null,"previous_names":["maximcoding/react-native-cli-starter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maximcoding/react-native-cli-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximcoding%2Freact-native-cli-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximcoding%2Freact-native-cli-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximcoding%2Freact-native-cli-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximcoding%2Freact-native-cli-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximcoding","download_url":"https://codeload.github.com/maximcoding/react-native-cli-starter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximcoding%2Freact-native-cli-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T16:13:27.964Z","updated_at":"2026-04-04T16:13:28.480Z","avatar_url":"https://github.com/maximcoding.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nFILE: README.md\nPURPOSE: High-level, human-readable overview + quick start for CliMobile (RNS).\n         Explains the product model (Base App + Plugins) and links to /docs for the canonical contracts and workflow.\n         This is the root README.md for GitHub. The canonical version is in docs/README.md.\nOWNERSHIP: CLI\n--\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# 🚀 CliMobile (RNS)\n\n**Universal React Native \"LEGO Platform\" CLI**  \nGenerate a clean **Base App** (Expo or Bare RN) and then install **Capabilities (Plugins)** safely — *zero manual setup, permission-aware, conflict-aware, idempotent.*\n\n[![Node.js](https://img.shields.io/badge/Node.js-≥18-green.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)\n[![npm version](https://img.shields.io/npm/v/climobile.svg)](https://www.npmjs.com/package/climobile)\n\n[Quick Start](#-quick-start) • [Key Features](#-key-features) • [Generated App Structure](#-generated-app-structure) • [Plugin Catalog](#-plugins-optional---full-catalog) • [Docs](#-documentation) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ What is CliMobile?\n\nCliMobile is a **React Native project generator + expander** built around a strict model:\n\n- **Base App**: `rns init` creates a runnable project (**Expo** or **Bare React Native**) that boots immediately.\n- **Plugins (Capabilities)**: `rns plugin add \u003cid...\u003e` installs infrastructure capabilities end‑to‑end (**deps + runtime wiring + native/config patch ops + permissions + manifest update**).\n- **Modulator Engine**: the deterministic installer pipeline (**Plan → Apply → Verify**) that makes installs repeatable.\n\n### Why it exists\n\nReact Native projects become brittle when infrastructure is added manually:\n\n- \"paste this provider into App.tsx\"\n- \"edit AndroidManifest / Info.plist / Gradle / Podfile\"\n- \"this package conflicts with that package\"\n- \"upgrade broke wiring again\"\n\nCliMobile solves this by enforcing **ownership zones** and using **data-driven plugin descriptors** + **idempotent patch operations**.\n\n### The Problem vs The Solution\n\n| Traditional RN Setup | With CliMobile |\n|---|---|\n| ⏱️ Manual config edits | ⚡ **Automated generation** |\n| 🧩 Copy/paste glue code | 🧱 **Plugins install end-to-end** |\n| 🧨 Native config conflicts | ✅ **Conflict-aware installs** |\n| 🔄 Repeating starter work | ♻️ **Reusable CORE + plugins** |\n| 😵 Late conflict discovery | 🧭 **Slot-based conflict model** |\n| 🔐 Permission tribal knowledge | 📋 **Permission IDs → mapped** |\n\n---\n\n## 🎯 Non‑negotiables (Platform rules)\n\n- **Base first, then plugins.** Base App is always runnable.\n- **Zero manual setup for shipped plugins.** If we ship it, the CLI installs it fully.\n- **Idempotent operations.** Run the same command twice → **NO duplicates**.\n- **No user-zone edits.** Your business code (`src/**`) stays clean by default.\n- **Block only real conflicts.** Slot conflicts (single vs multi) prevent only true incompatibilities.\n- **Docs-first contracts.** If code and `docs/cli-interface-and-types.md` diverge → treat as a bug.\n\n---\n\n## 🚀 Quick Start\n\n### 1) Install\n\n```bash\nnpm i -g climobile\n# or: pnpm add -g climobile\n# or: yarn global add climobile\n```\n\nVerify:\n\n```bash\nrns --help\nrns --version\n```\n\n### 2) Preflight (MANDATORY)\n\nValidate your machine before generating a project:\n\n```bash\nrns doctor --env\n```\n\n### 3) Create a Base App\n\nExpo:\n\n```bash\nrns init MyApp --target expo --lang ts --pm pnpm\ncd MyApp\npnpm start\n```\n\nBare RN:\n\n```bash\nrns init MyApp --target bare --lang ts --pm pnpm --platforms ios,android\ncd MyApp\npnpm ios\npnpm android\n```\n\n### 4) Add capabilities (Plugins)\n\n```bash\nrns plugin list\nrns plugin add data.react-query storage.mmkv state.zustand --dry-run\nrns plugin add data.react-query storage.mmkv state.zustand\nrns doctor\n```\n\n---\n\n## 💡 Key Features\n\n### 🧱 Base App (CORE) — always included\n\nThe Base App is designed to be a stable foundation for **any app archetype** (online, offline-first, marketplace, chat, real-estate, etc.):\n\n- **Ownership zones** (System vs User) enforced\n- **Workspace packages layout** under `packages/@rns/**`\n- **Runtime composition layer** under `packages/@rns/runtime/**`\n- **Kernel contracts + safe defaults** under `packages/@rns/core/**`\n- **DX baseline**: aliases (`@/`), SVG, fonts, env pipeline (no manual setup)\n- **Project manifest** `.rns/rn-init.json` (single source of truth)\n- **Doctor tooling**: environment + project validation gates\n- **Navigation infrastructure** (Bare RN): React Navigation presets with registry-based screen registration (see `docs/navigation.md`)\n\n\u003e CORE provides *contracts and defaults*. Concrete capabilities (auth, adapters, payments, etc.) come from plugins.\n\n### 🔌 Plugin system (Capabilities)\n\nEach plugin is a **declarative blueprint** (descriptor) that can express:\n\n- support rules (Expo/Bare + Expo runtime constraints)\n- slot conflicts (single vs multi)\n- permission IDs (resolved via dataset)\n- runtime contributions (AST‑only; ts‑morph; symbol references)\n- patch operations (native/config edits; anchored; idempotent; backed up)\n- required npm deps (pm-aware install)\n\n### 🛡️ Safety \u0026 repeatability\n\n- **Plan first** (`--dry-run`) → see exactly what will change\n- **Backups** before patching under `.rns/backups/\u003ctimestamp\u003e/...`\n- **Re-run safe**: apply twice is either a NO‑OP or a clean reconcile\n- **Doctor gates** to prevent half‑applied / broken states\n\n---\n\n## 🎨 Generated App Structure\n\n\u003e **User Zone** = your business code (`src/**`)  \n\u003e **System Zone** = CLI-managed (`packages/@rns/**` + `.rns/**`)\n\n```txt\nMyApp/\n├── .rns/                       # SYSTEM: manifest, logs, backups\n│   └── rn-init.json            # Project Manifest (source of truth)\n├── index.js                    # Bare only: Metro entry (main); imports App, AppRegistry\n├── src/                        # USER: your business code (CLI must not edit)\n├── packages/                   # SYSTEM: CLI-managed workspace packages\n│   └── @rns/\n│       ├── core/               # kernel contracts + safe defaults\n│       ├── runtime/            # runtime composition + wiring (entry index.tsx)\n│       └── plugin-*/           # installed plugins as local packages\n└── ...                         # Expo/Bare native scaffolding (target-specific)\n```\n\n**Bare entry:** `index.js` is the Metro entry; `package.json` has `\"main\": \"index.js\"`. Expo uses `index.ts`/`index.js` per template.\n\n**Key principle:** plugins integrate via `packages/@rns/runtime/**`, not by patching your `src/**`.\n\n**Navigation (Bare RN):** The CORE navigation system (`packages/@rns/navigation/**`) includes React Navigation with preset support (stack, tabs, drawer, modals). Users can register their own screens from User Zone via a registry file (`src/app/navigation/registry.ts`) without modifying System Zone. See [`docs/navigation.md`](docs/navigation.md) for complete guide.\n\n---\n\n## 📋 Capabilities Matrix\n\n### CORE (Always Installed)\n\n| Capability | Targets | Notes |\n|---|---|---|\n| Workspace packages (`packages/@rns/**`) | Expo + Bare | Isolation and maintainability |\n| Runtime composition (`@rns/runtime`) | Expo + Bare | Single wiring hub |\n| Kernel contracts (`@rns/core`) | Expo + Bare | Stable, additive contracts + defaults |\n| Ownership zones | Expo + Bare | CLI edits System Zone only |\n| Manifest (`.rns/rn-init.json`) | Expo + Bare | Project passport + migrations |\n| Doctor (`doctor --env`, `doctor`) | Expo + Bare | Safety gate for changes |\n| DX baseline (alias/SVG/fonts/env) | Expo + Bare | Zero manual setup |\n| CI/CD Workflows (GitHub Actions templates) | Expo + Bare | ⚠️ PLANNED - Implementation in TODO Section 24 |\n| Theme System (dark/light) | Expo + Bare | Theme provider + tokens |\n| Splash Screen | Expo + Bare | Boot splash screen |\n| Feature Flags Registry | Expo + Bare | Local feature flags (extendable by plugins) |\n| Code Quality Tools (Prettier, Husky, ESLint) | Expo + Bare | Formatting, git hooks, linting |\n| Navigation Infrastructure | Expo + Bare | React Navigation presets (Bare RN). Registry-based screen registration (see `docs/navigation.md`) |\n| Cache Engine | Expo + Bare | Snapshot cache contract + in-memory default |\n| UI Components | Expo + Bare | Minimal UI components (MinimalUI, basic components) |\n| Development Scripts | Expo + Bare | Clean, and other dev scripts (beyond doctor) |\n\n### Plugins (Optional - Full Catalog)\n\n\u003e This is a **capability catalog**. Concrete shipped plugin IDs and their exact support rules live in the plugin catalog \u0026 docs.\n\n| Category | Examples (IDs) | Slot mode |\n|---|---|---|\n| Navigation root | `nav.react-navigation`, `nav.expo-router` | **single** |\n| UI framework | `ui.paper`, `ui.tamagui`, `ui.nativebase` | **single** |\n| Animations | `animation.reanimated`, `animation.lottie` | multi |\n| State | **`state.zustand`**, `state.xstate`, `state.mobx` | multi |\n| Data fetching / cache | `data.react-query`, `data.apollo`, `data.swr` | multi |\n| Network transport | `transport.axios`, `transport.fetch`, `transport.graphql`, `transport.websocket`, `transport.firebase` | **multi** |\n| Auth | `auth.firebase`, `auth.cognito`, `auth.auth0`, `auth.custom-jwt` | multi |\n| AWS Services | `aws.amplify`, `aws.appsync`, `aws.dynamodb`, `aws.s3` | multi |\n| Storage | `storage.mmkv`, `storage.sqlite`, `storage.secure`, `storage.filesystem` | multi |\n| Firebase Products | `firebase.firestore`, `firebase.realtime-database`, `firebase.storage`, `firebase.remote-config` | multi |\n| Offline-first | `offline.netinfo`, `offline.outbox`, `offline.sync` | multi |\n| Notifications | `notify.expo`, `notify.fcm`, `notify.onesignal` | multi |\n| Maps / location | `geo.location`, `maps.google` | multi |\n| Camera / media | `media.camera`, `media.vision-camera`, `media.picker` | multi |\n| Payments | `pay.stripe` | multi |\n| Subscriptions / IAP | `iap.revenuecat`, `iap.adapty`, `iap.app-store`, `iap.play-billing` | **single** |\n| Analytics / observability | `analytics.firebase`, `analytics.amplitude`, `obs.sentry`, `obs.bugsnag` | multi |\n| i18n | `i18n.i18next`, `i18n.lingui` | multi |\n| Search | `search.algolia`, `search.local-index` | multi |\n| OTA Updates | `ota.expo-updates`, `ota.code-push` | **single** |\n| Background Tasks | `background.tasks`, `background.geofencing`, `background.fetch` | multi |\n| Privacy \u0026 Consent | `privacy.att`, `privacy.consent`, `privacy.gdpr` | multi |\n| Device / Hardware | `device.biometrics`, `device.bluetooth` | multi |\n| Testing | `test.detox` | multi |\n\n---\n\n## 🧭 Expo vs Bare support rules\n\nEvery plugin declares support:\n\n- **Targets**: `expo | bare | both`\n- **Expo runtime**: `expo-go | dev-client | standalone` (when relevant)\n- **Platforms**: `ios | android | web` (optional)\n\nThe CLI must refuse incompatible installs early with clear errors.\n\n---\n\n## 🔐 Permissions model (IDs + mapping)\n\nPlugins declare **permission IDs**, not raw platform strings.\n\n- Dataset: `docs/plugins-permissions.md`\n- The CLI resolves IDs into:\n  - iOS `Info.plist` keys (+ notes)\n  - Android `AndroidManifest` permissions/features (+ notes)\n  - provider SDK notes (Expo module vs bare provider)\n\n---\n\n## 🧠 How it works (Modulator Engine)\n\nWhen you run `rns plugin add \u003cid\u003e`, the engine executes:\n\n1. **Doctor gate** (project initialized + env sane)\n2. **Plan** (deps, slots, permissions, patch ops, runtime ops)\n3. **Scaffold** (ensure plugin packages exist in System Zone)\n4. **Link** (workspace + pm-aware installs)\n5. **Wire runtime** (AST edits only; ts-morph; symbol refs)\n6. **Patch native/config** (declarative ops; idempotent; backed up)\n7. **Update manifest** (single source of truth)\n8. **Verify** (no duplicates; markers/anchors intact)\n\n---\n\n## 💼 Example Use Cases\n\n### E-commerce App\n```bash\nrns init ShopApp --target expo --lang ts\nrns plugin add pay.stripe auth.firebase storage.mmkv state.zustand\n```\n**Result**: Full payment processing, authentication, fast storage, and state management — zero manual wiring.\n\n### Social Media App\n```bash\nrns init SocialApp --target bare --lang ts\nrns plugin add notify.fcm media.camera geo.location data.react-query\n```\n**Result**: Push notifications, camera access, location services, and data fetching — all configured automatically.\n\n### Offline-First App\n```bash\nrns init OfflineApp --target expo --lang ts\nrns plugin add offline.netinfo offline.outbox storage.sqlite\n```\n**Result**: Connectivity detection, offline queue, and local database — ready for sync logic.\n\n---\n\n## 🗺️ Project Status\n\n- ✅ **Core Features**: Base app generation (Expo/Bare), plugin system foundation, CORE baseline\n- ✅ **Completed**: CLI foundation, init pipeline, DX baseline, docs contract\n- 🚧 **In Progress**: Template packs system, dynamic attachment engine, marker patcher\n- 📋 **Roadmap**: See `docs/TODO.md` for detailed work order (23 sections total)\n\n---\n\n## 📚 Documentation\n\nAll canonical documentation lives under `docs/`:\n\n- **`docs/README.md`** — high-level product model + quick start (canonical version)\n- **`docs/TODO.md`** — single work-order (execute top-to-bottom)\n- **`docs/WORKFLOW.md`** — repo execution rules (run/verify/commit/no regressions)\n- **`docs/AGENT.md`** — AI agent rules (scope control + acceptance checks)\n- **`docs/cli-interface-and-types.md`** — canonical contracts/types (**no duplicated schema elsewhere**)\n- **`docs/plugins-permissions.md`** — permission IDs dataset + platform mapping\n- **`docs/navigation.md`** — navigation registry system guide (Bare RN projects)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 Canonical Docs Contract\u003c/b\u003e (for maintainers)\u003c/summary\u003e\n\nThe following six documents form the **canonical, non-duplicated** documentation set. This contract ensures work can be delegated safely without schema duplication or intent loss.\n\n1. **`docs/README.md`** — high-level product model + quick start\n2. **`docs/TODO.md`** — single work-order (execute top-to-bottom)\n3. **`docs/WORKFLOW.md`** — repo execution rules (run/verify/commit/no regressions)\n4. **`docs/AGENT.md`** — AI agent rules (scope control + acceptance checks)\n5. **`docs/cli-interface-and-types.md`** — canonical type names/shapes index (**no duplicated schema elsewhere**)\n6. **`docs/plugins-permissions.md`** — permission IDs dataset + platform mapping\n\n**Documentation Rules:**\n- **Do not shrink or delete intent** — if content is too long, move it to a dedicated doc instead of removing it\n- **No schema duplication** — type definitions live in `cli-interface-and-types.md`; other docs reference it\n- **Cross-reference, don't duplicate** — docs should reference each other, not copy content\n- **Source of truth** — TypeScript code is authoritative; docs describe the contracts\n\n\u003c/details\u003e\n\n---\n\n## 🤝 Contributing\n\nCanonical dev runner (must behave like released CLI):\n\n```bash\nnpm run cli -- --help\nnpm run cli -- doctor --env\nnpm run cli -- init MyApp --target expo\n```\n\nWorkflow rules (mandatory):\n- Work strictly top‑to‑bottom from the first unchecked section in `docs/TODO.md`\n- Unit of work = one TODO section = one commit\n- No drive‑by refactors, no scope creep, no regressions\n\nSee: `docs/WORKFLOW.md`.\n\n---\n\n## 📄 License\n\nISC\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximcoding%2Freact-native-cli-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximcoding%2Freact-native-cli-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximcoding%2Freact-native-cli-starter/lists"}