create-mobile-app 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevMinds Technologies <contact@devminds.in>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,491 @@
-# Temporary Holding Version
+# 🚀 create-mobile-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Create a production-ready React Native + TypeScript mobile application in one command.**  
+> Powered by **Expo SDK 57 (Default)**, modern **Node.js 20+**, dynamic responsive scaling via **[`react-native-dynamic-responsive`](https://www.npmjs.com/package/react-native-dynamic-responsive)**, enterprise modular architecture, and zero-headache setup.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/create-mobile-app">
+    <img src="https://img.shields.io/npm/v/create-mobile-app.svg?style=flat-square&color=cb3837&label=npm" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/create-mobile-app">
+    <img src="https://img.shields.io/npm/dw/create-mobile-app.svg?style=flat-square&color=44cc11&label=downloads" alt="downloads" />
+  </a>
+  <a href="https://github.com/officialdevforge/create-mobile-app/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" />
+  </a>
+  <a href="https://www.typescriptlang.org/">
+    <img src="https://img.shields.io/badge/typescript-ready-3178c6.svg?style=flat-square&logo=typescript&logoColor=white" alt="typescript" />
+  </a>
+  <a href="https://expo.dev/">
+    <img src="https://img.shields.io/badge/expo-compatible-8547c6.svg?style=flat-square&logo=expo&logoColor=white" alt="expo" />
+  </a>
+  <a href="https://reactnative.dev/">
+    <img src="https://img.shields.io/badge/react--native-compatible-2088ff.svg?style=flat-square&logo=react&logoColor=white" alt="react-native" />
+  </a>
+  <a href="https://nodejs.org/">
+    <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-339933.svg?style=flat-square&logo=node.js&logoColor=white" alt="node" />
+  </a>
+  <a href="https://devminds.in">
+    <img src="https://img.shields.io/badge/Maintained%20by-DevMinds%20Technologies-6366f1?style=flat-square" alt="DevMinds Technologies" />
+  </a>
+</p>
+
+---
+
+## 📑 Table of Contents
+
+- [Why create-mobile-app?](#-why-create-mobile-app)
+- [Ecosystem & Best Packages Used](#-ecosystem--best-packages-used)
+- [Quick Start](#-quick-start)
+- [Interactive Prompts](#-interactive-prompts)
+- [CLI Options & Flags](#-cli-options--flags)
+- [Enterprise Architecture & Folder Structure](#-enterprise-architecture--folder-structure)
+- [Code Examples & Architecture Guides](#-code-examples--architecture-guides)
+  - [1. Dynamic Responsive UI & Layouts](#1-dynamic-responsive-ui--layouts)
+  - [2. Light, Dark & System Theme Engine](#2-light-dark--system-theme-engine)
+  - [3. Production UI Component Library](#3-production-ui-component-library)
+  - [4. Typed Navigation (Stack, 5 Tabs & Drawer)](#4-typed-navigation-stack-5-tabs--drawer)
+  - [5. Centralized API Client & TanStack Query v5](#5-centralized-api-client--tanstack-query-v5)
+  - [6. Authentication & Guest Mode](#6-authentication--guest-mode)
+- [Developer & Contribution Guide](#-developer--contribution-guide)
+- [Troubleshooting & FAQ](#-troubleshooting--faq)
+- [Credits & Author](#-credits--author)
+- [License](#-license)
+
+---
+
+## 💡 Why `create-mobile-app`?
+
+Starting a production-grade React Native app usually takes days of repetitive boilerplate work: configuring navigation stacks, setting up dark/light themes, solving tablet/foldable responsive layouts, creating reusable inputs and buttons, wiring API interceptors, setting up caching with TanStack React Query, and fixing native SDK dependency mismatch warnings.
+
+`create-mobile-app` eliminates all this setup friction:
+- ⚡ **Zero-to-Running in 30 Seconds**: Run one command and start building features immediately.
+- 📐 **First-Class Responsive Engine**: Built-in support for phones, landscape, tablets, and foldable screens with `react-native-dynamic-responsive`.
+- 🛡️ **Zero Version-Mismatch Doctor Warnings**: Downloads the official template for your target Expo SDK, aligning `expo`, `react`, and `react-native` versions perfectly.
+- 🔒 **Zero Obfuscation or Hidden Binaries**: Fully inspectable, MIT-licensed open-source TypeScript code conforming to GitHub and GitLab security standards.
+
+---
+
+## 📦 Ecosystem & Best Packages Used
+
+Every generated application integrates industry-standard, battle-tested packages:
+
+| Purpose | Package | Why It's the Best Choice |
+| :--- | :--- | :--- |
+| **Responsive Design** | [`react-native-dynamic-responsive`](https://www.npmjs.com/package/react-native-dynamic-responsive) | Zero-runtime dependency, reactive to orientation, foldables & tablets with `useStyles`. |
+| **State & API Cache** | [`@tanstack/react-query`](https://tanstack.com/query/latest) v5 | Industry standard for async state, pagination, caching, and retry logic. |
+| **Navigation** | [`@react-navigation/native`](https://reactnavigation.org/) v7 | Declarative, typed routing with Native Stack, 5 Bottom Tabs, and Slide-out Drawer. |
+| **Persistent Storage** | [`@react-native-async-storage/async-storage`](https://react-native-async-storage.github.io/async-storage/) | Reliable key-value persistence for tokens, preferences, and offline caching. |
+| **Mobile Runtime** | [`expo`](https://expo.dev/) (SDK 57 default) | Modern developer experience, EAS build support, and web/iOS/Android universal runtimes. |
+| **Language & Tooling** | `TypeScript` 5+ & `Node.js` 20+ | Strict type safety, auto-completion, and error-free build execution. |
+
+---
+
+## 🚀 Quick Start
+
+Generate your app in any directory with `npx`:
+
+```bash
+npx create-mobile-app my-app
+```
+
+### ⚡ Instant Setup with Production Defaults (`--yes`)
+Skip questions and immediately scaffold an enterprise app with Expo SDK 57:
+
+```bash
+npx create-mobile-app my-app --yes
+```
+
+### 🎯 Target Specific Expo SDK Version
+Supports any modern Expo SDK:
+
+```bash
+# Expo SDK 57 (Recommended Default)
+npx create-mobile-app my-app --sdk 57
+
+# Latest Expo SDK 58
+npx create-mobile-app my-app --sdk 58
+
+# Earlier versions (e.g., 54, 52 LTS)
+npx create-mobile-app my-app --sdk 54
+```
+
+### 📦 Specify Preferred Package Manager
+```bash
+# npm, yarn, pnpm, or bun
+npx create-mobile-app my-app --pm pnpm
+```
+
+---
+
+## 📋 Interactive Prompts
+
+When run without flags, `create-mobile-app` guides you through an intuitive, interactive setup:
+
+```text
+? Project name: my-app
+? Select Platform: Expo (Recommended) / React Native CLI
+? Select Expo SDK Version: SDK 57 (Recommended)
+? Include dynamic responsive system (react-native-dynamic-responsive)? Yes
+? Include Theme system (Light/Dark/System)? Yes
+? Include Reusable UI Component library (CText, CBox, CButton, CInput, CDropdown)? Yes
+? Include Navigation (Stack, 5 Tabs, Drawer)? Yes
+? Include Centralized API Client (Axios/Fetch with interceptors)? Yes
+? Include TanStack React Query v5? Yes
+? Include Domain Service architecture (Auth, User, Home, Profile)? Yes
+? Include Authentication Context & Session State? Yes
+? Enable Guest Mode support? Yes
+? Include Async Storage layer? Yes
+? Include Husky, Prettier, and Lint-Staged pre-commit checks? Yes
+? Include Demo Screen examples? Yes
+? Select Package Manager: auto (detects npm, pnpm, yarn, bun)
+```
+
+---
+
+## 🎛️ CLI Options & Flags
+
+| Flag | Type | Default | Description |
+| :--- | :---: | :---: | :--- |
+| `-y, --yes` | `boolean` | `false` | Generate immediately using production defaults |
+| `--platform <type>` | `string` | `expo` | Target platform (`expo` or `cli`) |
+| `--sdk <version>` | `string` | `~57.0.0` | Target Expo SDK version (`57`, `58`, `54`, `52`) |
+| `--responsive / --no-responsive` | `boolean` | `true` | Include `react-native-dynamic-responsive` system |
+| `--theme / --no-theme` | `boolean` | `true` | Include Light / Dark / System theme engine |
+| `--components / --no-components` | `boolean` | `true` | Include UI library (`CText`, `CBox`, `CButton`, etc.) |
+| `--navigation / --no-navigation` | `boolean` | `true` | Include Navigation Architecture |
+| `--tabs / --no-tabs` | `boolean` | `true` | Include 5 Bottom Tabs Navigation |
+| `--drawer / --no-drawer` | `boolean` | `true` | Include Drawer Navigation |
+| `--api / --no-api` | `boolean` | `true` | Include API Client Architecture |
+| `--query / --no-query` | `boolean` | `true` | Include TanStack React Query v5 layer |
+| `--service / --no-service` | `boolean` | `true` | Include Domain Service architecture |
+| `--auth / --no-auth` | `boolean` | `true` | Include Auth Context & Session Management |
+| `--guest / --no-guest` | `boolean` | `true` | Include Guest Mode support |
+| `--storage / --no-storage` | `boolean` | `true` | Include AsyncStorage key-value abstraction |
+| `--husky / --no-husky` | `boolean` | `true` | Include Husky, Prettier & Lint-Staged git hooks |
+| `--examples / --no-examples` | `boolean` | `true` | Include sample screens (Home, Profile, Search, etc.) |
+| `--pm <manager>` | `string` | `auto` | Package manager: `npm`, `yarn`, `pnpm`, or `bun` |
+| `-V, --version` | `boolean` | - | Display current version |
+| `-h, --help` | `boolean` | - | Display help documentation |
+
+---
+
+## 📁 Enterprise Architecture & Folder Structure
+
+Every generated project uses a clean modular structure designed for enterprise scale:
+
+```text
+my-app/
+├── assets/                    # App Icon, Splash Screen, Adaptive Icon, Favicon
+├── app.json                   # Expo application config & splash branding
+├── App.tsx                    # Root provider composition (Theme, Auth, Query, Navigation)
+├── babel.config.js            # Path alias configuration (@/ -> src/)
+├── tsconfig.json              # Strict TypeScript config with root aliases
+└── src/
+    ├── api/                   # Centralized HTTP client, interceptors & error handlers
+    │   ├── client.ts          # Generic client with auth headers and normalized errors
+    │   └── queryKeys.ts       # Type-safe TanStack Query key factory
+    ├── auth/                  # Authentication & Session Management
+    │   ├── AuthContext.tsx    # Auth provider, token storage, login/logout, guest mode
+    │   └── useAuth.ts         # Hook to access user session and guest flags
+    ├── components/            # Reusable UI component library
+    │   ├── common/            # CText, CBox, CInput, CButton, CDropdown
+    │   └── alert/             # Global AlertProvider and useAlert hook
+    ├── config/                # Environment variables & constants
+    ├── constant/              # Spacing, Font families, and Layout metrics
+    ├── hooks/                 # Custom React hooks (useDebounce, useNetworkStatus)
+    ├── navigations/           # Typed navigation architecture
+    │   ├── RootNavigator.tsx  # Auth vs Main app conditional routing
+    │   ├── BottomTabNavigator.tsx # 5 Configured Bottom Tabs with icons & badges
+    │   └── DrawerNavigator.tsx    # Slide-out Drawer navigation
+    ├── screen/                # Screen views
+    │   ├── HomeScreen.tsx     # Home feed screen
+    │   ├── SearchScreen.tsx   # Search & filter view
+    │   ├── NotificationScreen.tsx # Notifications list
+    │   ├── ProfileScreen.tsx  # User profile & theme settings
+    │   ├── SettingsScreen.tsx # App settings & preferences
+    │   └── LoginScreen.tsx    # Sign In & Guest Mode screen
+    ├── service/               # Domain API services
+    │   ├── authService.ts     # Login, Register, Refresh Token
+    │   ├── userService.ts     # Profile and user queries
+    │   └── homeService.ts     # Dashboard & feed queries
+    ├── storage/               # AsyncStorage persistent key-value abstraction layer
+    ├── theme/                 # Light / Dark / System theme engine & color tokens
+    ├── types/                 # Shared TypeScript models and navigation contracts
+    └── utils/                 # Utilities (Date, Mobile Number, Currency, Validation)
+```
+
+---
+
+## 💻 Code Examples & Architecture Guides
+
+### 1. Dynamic Responsive UI & Layouts
+
+Using [`react-native-dynamic-responsive`](https://www.npmjs.com/package/react-native-dynamic-responsive), styles dynamically adapt to screen size changes, rotation, tablets, and foldables:
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { useStyles, useResponsive } from 'react-native-dynamic-responsive';
+import { CText } from '@/components/common/CText';
+
+export const AdaptiveCard = () => {
+  const { isTablet, isLandscape } = useResponsive();
+  const styles = useStyles(createStyles);
+
+  return (
+    <View style={styles.card}>
+      <CText variant="header">
+        {isTablet ? 'Tablet Viewport' : 'Mobile Viewport'}
+      </CText>
+      <CText variant="caption">
+        Orientation: {isLandscape ? 'Landscape' : 'Portrait'}
+      </CText>
+    </View>
+  );
+};
+
+const createStyles = (r: any) => ({
+  card: {
+    width: r.isTablet ? r.wp(45) : r.wp(90),
+    padding: r.ms(16),
+    borderRadius: r.s(12),
+    backgroundColor: '#ffffff',
+  },
+});
+```
+
+---
+
+### 2. Light, Dark & System Theme Engine
+
+Synchronize styles with system preference or manually toggle themes:
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { useStyles } from 'react-native-dynamic-responsive';
+import { useTheme } from '@/theme';
+import { CText } from '@/components/common/CText';
+import { CButton } from '@/components/common/CButton';
+
+export const ThemeSwitcherCard = () => {
+  const { theme, isDark, toggleTheme } = useTheme();
+  const styles = useStyles(createStyles, theme);
+
+  return (
+    <View style={styles.container}>
+      <CText variant="title">Current Theme: {isDark ? 'Dark' : 'Light'}</CText>
+      <CButton
+        title="Toggle Theme"
+        variant="primary"
+        onPress={toggleTheme}
+      />
+    </View>
+  );
+};
+
+const createStyles = (r: any, theme: any) => ({
+  container: {
+    backgroundColor: theme.colors.card,
+    padding: r.ms(16),
+    borderRadius: r.s(12),
+  },
+});
+```
+
+---
+
+### 3. Production UI Component Library
+
+Pre-configured components ready for production use:
+
+```tsx
+import React, { useState } from 'react';
+import { CBox } from '@/components/common/CBox';
+import { CText } from '@/components/common/CText';
+import { CInput } from '@/components/common/CInput';
+import { CButton } from '@/components/common/CButton';
+import { useAlert } from '@/components/alert/AlertProvider';
+
+export const RegistrationForm = () => {
+  const [email, setEmail] = useState('');
+  const { showAlert } = useAlert();
+
+  const handleSave = () => {
+    showAlert({
+      title: 'Success',
+      message: 'User profile registered successfully!',
+      type: 'success',
+    });
+  };
+
+  return (
+    <CBox padding={16} borderRadius={12} backgroundColor="#F8FAFC">
+      <CText variant="header">Create Account</CText>
+      <CInput
+        label="Email Address"
+        placeholder="user@example.com"
+        value={email}
+        onChangeText={setEmail}
+      />
+      <CButton title="Submit" variant="primary" onPress={handleSave} />
+    </CBox>
+  );
+};
+```
+
+---
+
+### 4. Typed Navigation (Stack, 5 Tabs & Drawer)
+
+Pre-wired navigation setup with strictly typed parameters:
+
+```tsx
+import { NativeStackScreenProps } from '@react-navigation/native-stack';
+import { RootStackParamList } from '@/types/navigation';
+
+type Props = NativeStackScreenProps<RootStackParamList, 'Profile'>;
+
+export const ProfileScreen = ({ navigation, route }: Props) => {
+  return (
+    <CBox flex={1} padding={16}>
+      <CText variant="title">User Profile</CText>
+      <CButton
+        title="Open Settings"
+        onPress={() => navigation.navigate('Settings')}
+      />
+    </CBox>
+  );
+};
+```
+
+---
+
+### 5. Centralized API Client & TanStack Query v5
+
+Fetch data cleanly with automatic caching, normalized error handling, and type safety:
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { queryKeys } from '@/api/queryKeys';
+import { homeService } from '@/service/homeService';
+import { CText } from '@/components/common/CText';
+import { CBox } from '@/components/common/CBox';
+
+export const DashboardFeed = () => {
+  const { data, isLoading, error } = useQuery({
+    queryKey: queryKeys.home.dashboard(),
+    queryFn: () => homeService.getDashboardData(),
+  });
+
+  if (isLoading) return <CText>Loading feed...</CText>;
+  if (error) return <CText color="red">Failed to load feed</CText>;
+
+  return (
+    <CBox>
+      <CText variant="subtitle">{data?.title}</CText>
+    </CBox>
+  );
+};
+```
+
+---
+
+### 6. Authentication & Guest Mode
+
+Authenticate users, store tokens safely in AsyncStorage, and support guest access:
+
+```tsx
+import React from 'react';
+import { useAuth } from '@/auth/useAuth';
+import { CBox } from '@/components/common/CBox';
+import { CText } from '@/components/common/CText';
+import { CButton } from '@/components/common/CButton';
+
+export const SessionStatus = () => {
+  const { user, isGuest, isAuthenticated, loginAsGuest, logout } = useAuth();
+
+  return (
+    <CBox padding={16}>
+      {isAuthenticated ? (
+        <>
+          <CText>{isGuest ? 'Logged in as Guest' : `Welcome, ${user?.email}`}</CText>
+          <CButton title="Logout" variant="outline" onPress={logout} />
+        </>
+      ) : (
+        <CButton title="Continue as Guest" variant="secondary" onPress={loginAsGuest} />
+      )}
+    </CBox>
+  );
+};
+```
+
+---
+
+## 🛠️ Developer & Contribution Guide
+
+### Local Development Setup
+
+To contribute to or modify `create-mobile-app`:
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/officialdevforge/create-mobile-app.git
+   cd create-mobile-app
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Build the CLI**:
+   ```bash
+   npm run build
+   ```
+
+4. **Run the Vitest test suite**:
+   ```bash
+   npm test
+   ```
+
+5. **Test the CLI locally**:
+   ```bash
+   npm start my-test-app
+   ```
+
+---
+
+## 💡 Troubleshooting & FAQ
+
+#### Q: How does Expo dependency alignment work?
+`create-mobile-app` downloads the official Expo blank template matching your target SDK (default SDK 57). It keeps the native package versions (`expo`, `react`, `react-native`, `expo-status-bar`) completely intact, guaranteeing **zero version mismatch warnings** when running `npx expo-doctor`.
+
+#### Q: Which Node.js version is required?
+Node.js **`>=20.0.0`** is required. We recommend the latest LTS release of Node 20 or Node 22.
+
+#### Q: Can I use this with React Native CLI instead of Expo?
+Yes! Pass `--platform cli` to scaffold a React Native Community CLI foundation:
+```bash
+npx create-mobile-app my-app --platform cli
+```
+
+---
+
+## 👨‍💻 Credits & Author
+
+Developed and maintained with ❤️ by **[DevMinds Technologies](https://devminds.in)**.
+
+- 🏢 **Organization**: **DevMinds Technologies** *(WEB · MOBILE · CLOUD · DESIGN)*
+- 🌐 **Website**: [devminds.in](https://devminds.in)
+- 💼 **Portfolio**: [devminds.in/portfolio](https://devminds.in/portfolio)
+- 👨‍💻 **Lead Architect**: **[Dharmendra (Dev) kumar](https://www.linkedin.com/in/dharmendra-appdeveloper)** *(Mobile & Full Stack Architect)*
+- ✉️ **Inquiries & Custom Software**: [contact@devminds.in](mailto:contact@devminds.in)
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** &mdash; see the [LICENSE](LICENSE) file for details.  
+Copyright (c) 2026 **DevMinds Technologies** & **Dharmendra (Dev) kumar**.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+declare function runCli(): Promise<void>;
+
+export { runCli };