create-rn-clean-architecture 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khizar
+
+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

@@ -0,0 +1,369 @@
+# create-rn-clean-architecture
+
+🏗️ **Instantly create a complete, production-ready React Native app with Clean Architecture**
+
+Transform your empty React Native project into a fully functional app with navigation, sample screens, and clean architecture patterns - all in under a minute!
+
+## ✨ Features
+
+- 🚀 **Complete Working App**: Creates a fully functional app with 4 screens ready to run
+- 📱 **Full Navigation Setup**: Stack navigation + Bottom tabs pre-configured
+- 📁 **Clean Architecture**: Organized directory structure with proper separation of concerns
+- 🎨 **Design System**: Pre-configured colors, sizings, and styling constants
+- 📝 **Sample Screens**: Splash, Home, Profile, and Settings screens with clean patterns
+- 🔧 **Automatic Dependencies**: Checks and installs required navigation packages
+- 📖 **Comprehensive Guide**: Detailed PROJECT_ARCHITECTURE.md with best practices
+- ✅ **Type-Safe**: Full TypeScript support with proper navigation types
+- 🎯 **Zero Configuration**: Works immediately after scaffolding
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 14.0.0
+- A React Native project created with `npx react-native init MyApp`
+
+### Usage
+
+Navigate to your React Native project directory and run:
+
+```bash
+npx create-rn-clean-architecture
+```
+
+Or install globally:
+
+```bash
+npm install -g create-rn-clean-architecture
+create-rn-clean-architecture
+```
+
+### What Happens Next?
+
+1. ✅ Validates your React Native project
+2. ✅ Creates complete directory structure
+3. ✅ Generates 4 working screens with navigation
+4. ✅ Sets up hooks, styles, and constants
+5. ✅ Updates your App.tsx
+6. ✅ Checks and installs navigation dependencies
+7. ✅ Copies architecture documentation
+8. 🎉 **Your app is ready to run!**
+
+## 📦 What Gets Created
+
+### Complete Directory Structure
+
+```
+src/
+├── assets/
+│   ├── images/
+│   ├── fonts/
+│   └── icons/
+├── components/
+│   └── common/
+├── constants/
+│   ├── sizings/
+│   │   └── SIZINGS.ts              ✓ Generated
+│   ├── styles/
+│   │   └── COLORS.ts               ✓ Generated
+│   └── splash/
+│       └── splash.constants.ts     ✓ Generated
+├── hooks/
+│   └── splash/
+│       └── useSplashNavigation.ts  ✓ Generated
+├── navigation/
+│   ├── stack/
+│   │   └── StackNavigation.tsx     ✓ Generated
+│   └── bottom/
+│       └── BottomTabNavigation.tsx ✓ Generated
+├── screens/
+│   ├── splash/
+│   │   └── SplashScreen.tsx        ✓ Generated
+│   ├── home/
+│   │   └── HomeScreen.tsx          ✓ Generated
+│   ├── profile/
+│   │   └── ProfileScreen.tsx       ✓ Generated
+│   └── settings/
+│       └── SettingsScreen.tsx      ✓ Generated
+├── state/
+│   ├── zustand/
+│   └── context/
+├── styles/
+│   ├── splash/
+│   │   └── splash.styles.ts        ✓ Generated
+│   ├── home/
+│   │   └── home.styles.ts          ✓ Generated
+│   ├── profile/
+│   │   └── profile.styles.ts       ✓ Generated
+│   └── settings/
+│       └── settings.styles.ts      ✓ Generated
+├── types/
+│   └── Type.ts                     ✓ Generated
+└── utils/
+    └── Util.ts                     ✓ Generated
+
+Root Level:
+├── App.tsx                         ✓ Updated
+└── PROJECT_ARCHITECTURE.md         ✓ Generated
+```
+
+### 🎯 4 Ready-to-Use Screens
+
+#### 1. Splash Screen
+- Auto-navigates to main app after 2 seconds
+- Uses custom hook for navigation logic
+- Demonstrates proper hook usage pattern
+
+#### 2. Home Screen
+- Part of bottom tab navigation
+- Example of presentation-only component
+- Uses centralized styles and constants
+
+#### 3. Profile Screen
+- Part of bottom tab navigation
+- Ready for user profile implementation
+- Follows clean architecture patterns
+
+#### 4. Settings Screen
+- Part of bottom tab navigation
+- Prepared for app configuration
+- Demonstrates consistent structure
+
+### 📝 Generated Core Files
+
+#### `src/utils/Util.ts`
+```typescript
+// Pre-configured navigator creators
+export const Stack = createNativeStackNavigator<STACK_NAVIGATOR_PARAMS>();
+export const Tab = createBottomTabNavigator<BOTTOM_TAB_NAVIGATOR_PARAMS>();
+```
+
+#### `src/types/Type.ts`
+```typescript
+// Complete navigation types
+export type STACK_NAVIGATOR_PARAMS = {
+  Splash: undefined;
+  Home: undefined;
+  BottomTab: undefined;
+};
+
+export type BOTTOM_TAB_NAVIGATOR_PARAMS = {
+  Home: undefined;
+  Profile: undefined;
+  Settings: undefined;
+};
+```
+
+#### `src/constants/sizings/SIZINGS.ts`
+- Border sizings (1-13px)
+- Font sizings (12-28px)
+- Spacing scale (4-48px)
+- Border radius values
+
+#### `src/constants/styles/COLORS.ts`
+- Primary and secondary colors
+- Gray scale (9 shades)
+- Status colors (success, warning, error, info)
+- Semantic colors (background, surface, text, border)
+
+### 🔗 Complete Navigation Setup
+
+The package creates a fully configured navigation system:
+
+**Stack Navigator** (Root):
+- Splash Screen → Bottom Tab Navigator
+
+**Bottom Tab Navigator**:
+- Home Tab
+- Profile Tab
+- Settings Tab
+
+**App.tsx** automatically wired up and ready to run!
+
+## 🎯 Architecture Principles
+
+All generated code follows clean architecture patterns:
+
+1. **Screens = Presentation Only**
+   - No business logic in screen components
+   - Only UI rendering and event handling
+
+2. **Hooks = Business Logic**
+   - All logic extracted to custom hooks
+   - Reusable and testable
+
+3. **Styles = Separate Files**
+   - StyleSheets in dedicated files
+   - Uses centralized constants
+
+4. **Constants = Centralized**
+   - Colors, sizes, and config in one place
+   - Easy to maintain and update
+
+5. **No Barrel Exports**
+   - Direct imports only
+   - Better tree-shaking and clarity
+
+## 📚 Example: Clean Architecture Pattern
+
+### Screen Component (Presentation)
+```typescript
+// src/screens/home/HomeScreen.tsx
+import React from 'react';
+import { Text, View } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { styles } from '../../styles/home/home.styles';
+
+const HomeScreen = () => {
+  return (
+    <SafeAreaView style={styles.container}>
+      <View style={styles.content}>
+        <Text style={styles.title}>Home Screen</Text>
+      </View>
+    </SafeAreaView>
+  );
+};
+```
+
+### Styles (Separate File)
+```typescript
+// src/styles/home/home.styles.ts
+import { StyleSheet } from 'react-native';
+import { COLORS } from '../../constants/styles/COLORS';
+import { SIZINGS } from '../../constants/sizings/SIZINGS';
+
+export const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: COLORS.colors.background,
+  },
+  title: {
+    fontSize: SIZINGS.fontSizings.large_4,
+    color: COLORS.colors.text,
+  },
+});
+```
+
+## 🔧 Automatic Dependency Management
+
+The CLI automatically detects and offers to install required packages:
+
+**Installed Automatically:**
+- `@react-navigation/native`
+- `@react-navigation/native-stack`
+- `@react-navigation/bottom-tabs`
+- `react-native-safe-area-context`
+- `react-native-screens`
+
+**iOS Note**: After installation, remember to run:
+```bash
+cd ios && pod install && cd ..
+```
+
+## 🎨 Customization
+
+### Changing Colors
+Edit `src/constants/styles/COLORS.ts`:
+```typescript
+export const COLORS = {
+  colors: {
+    primary: '#YOUR_COLOR',    // Change primary color
+    secondary: '#YOUR_COLOR',  // Change secondary color
+    // ... customize all colors
+  },
+};
+```
+
+### Adding New Screens
+1. Create screen directory: `src/screens/newscreen/`
+2. Create screen file: `NewScreen.tsx`
+3. Create styles: `src/styles/newscreen/newscreen.styles.ts`
+4. Add to navigation types in `src/types/Type.ts`
+5. Add to navigator in `src/navigation/`
+
+### Adding Business Logic
+1. Create hook directory: `src/hooks/feature/`
+2. Create hook file: `useFeatureLogic.ts`
+3. Import and use in screen component
+
+## 📖 Documentation
+
+The package includes `PROJECT_ARCHITECTURE.md` with:
+- Complete architecture guidelines
+- Best practices and patterns
+- Code examples for common scenarios
+- Naming conventions
+- Testing strategies
+- State management patterns
+
+## ✅ Success Criteria
+
+After running the tool:
+- ✅ App runs immediately with `npm start`
+- ✅ Navigation works between all screens
+- ✅ Splash screen auto-navigates after 2 seconds
+- ✅ Bottom tabs switch between Home, Profile, Settings
+- ✅ All TypeScript types are properly configured
+- ✅ No errors or warnings in console
+- ✅ Ready to customize and build upon
+
+## 🎯 CLI Output Example
+
+```
+🏗️  React Native Clean Architecture Scaffold
+
+? This will create a complete React Native app with navigation and sample screens. Continue? Yes
+
+📁 Creating directories...
+   ✓ Created src/assets/images
+   ✓ Created src/constants/sizings
+   ... (all directories)
+
+📝 Generating files...
+   ✓ Created src/constants/sizings/SIZINGS.ts
+   ✓ Created src/constants/styles/COLORS.ts
+   ✓ Created src/navigation/stack/StackNavigation.tsx
+   ✓ Created src/screens/splash/SplashScreen.tsx
+   ... (all files)
+
+📦 Checking dependencies...
+   ⚠ Missing required navigation dependencies
+? Would you like to install them now? Yes
+   Installing dependencies...
+   ✓ Dependencies installed successfully!
+
+✅ Clean architecture structure created successfully!
+🎉 Your app is ready to run!
+
+📂 What was created:
+   ✓ Complete directory structure
+   ✓ 4 sample screens (Splash, Home, Profile, Settings)
+   ✓ Navigation setup (Stack + Bottom Tabs)
+   ✓ Hooks, styles, and constants
+   ✓ Updated App.tsx ready to run
+
+📋 Next steps:
+   1. Review PROJECT_ARCHITECTURE.md for complete guidelines
+   2. Run: npm start (or yarn start)
+   3. Your app now has complete navigation and sample screens!
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📝 License
+
+MIT © Khizar
+
+## 🐛 Issues
+
+Found a bug or have a suggestion? Please [open an issue](https://github.com/yourusername/create-rn-clean-architecture/issues).
+
+## 🌟 Show Your Support
+
+Give a ⭐️ if this project helped you build better React Native apps!
+
+---
+
+**Made with ❤️ for the React Native community**

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { scaffold } = require('../src/index');
+
+scaffold().catch((error) => {
+  console.error('Error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-rn-clean-architecture",
+  "version": "1.0.0",
+  "description": "Scaffold a clean architecture structure for React Native projects",
+  "main": "src/index.js",
+  "bin": {
+    "create-rn-clean-architecture": "bin/cli.js"
+  },
+  "keywords": [
+    "react-native",
+    "clean-architecture",
+    "scaffold",
+    "cli",
+    "boilerplate",
+    "template",
+    "generator"
+  ],
+  "author": "Khizar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/create-rn-clean-architecture.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/create-rn-clean-architecture/issues"
+  },
+  "homepage": "https://github.com/yourusername/create-rn-clean-architecture#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.1.1",
+    "inquirer": "^8.2.5"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ]
+}

package/src/checkDependencies.js

@@ -0,0 +1,108 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { execSync } = require('child_process');
+
+const REQUIRED_DEPENDENCIES = [
+  '@react-navigation/native',
+  '@react-navigation/native-stack',
+  '@react-navigation/bottom-tabs',
+  'react-native-safe-area-context',
+  'react-native-screens',
+];
+
+async function checkAndInstallDependencies() {
+  console.log(chalk.cyan('\n📦 Checking dependencies...'));
+
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  const packageJson = await fs.readJson(packageJsonPath);
+
+  const dependencies = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  const missingDeps = REQUIRED_DEPENDENCIES.filter((dep) => !dependencies[dep]);
+
+  if (missingDeps.length === 0) {
+    console.log(chalk.green('   ✓ All required dependencies are already installed!'));
+    return true;
+  }
+
+  console.log(chalk.yellow('   ⚠ Missing required navigation dependencies:'));
+  missingDeps.forEach((dep) => {
+    console.log(chalk.gray(`      - ${dep}`));
+  });
+
+  const { install } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'install',
+      message: 'Would you like to install them now?',
+      default: true,
+    },
+  ]);
+
+  if (!install) {
+    const isExpo = dependencies['expo'];
+    console.log(
+      chalk.yellow(
+        '\n   ⚠ Skipping installation. You will need to install them manually later.'
+      )
+    );
+    console.log(chalk.gray('\n   Run this command to install:'));
+    if (isExpo) {
+      console.log(chalk.cyan(`   npx expo install ${REQUIRED_DEPENDENCIES.join(' ')}\n`));
+    } else {
+      console.log(chalk.cyan(`   npm install ${REQUIRED_DEPENDENCIES.join(' ')}\n`));
+    }
+    return false;
+  }
+
+  try {
+    console.log(chalk.cyan('\n   Installing dependencies... (this may take a minute)'));
+
+    // Check if it's an Expo project
+    const isExpo = dependencies['expo'];
+
+    // Check if yarn.lock exists
+    const useYarn = await fs.pathExists(path.join(process.cwd(), 'yarn.lock'));
+    const packageManager = useYarn ? 'yarn' : 'npm';
+    const installCmd = useYarn
+      ? `yarn add ${REQUIRED_DEPENDENCIES.join(' ')}`
+      : `npm install ${REQUIRED_DEPENDENCIES.join(' ')}`;
+
+    execSync(installCmd, { stdio: 'inherit', cwd: process.cwd() });
+
+    console.log(chalk.green('\n   ✓ Dependencies installed successfully!'));
+
+    // Check if iOS folder exists and remind about pod install (skip for Expo)
+    if (!isExpo) {
+      const iosExists = await fs.pathExists(path.join(process.cwd(), 'ios'));
+      if (iosExists) {
+        console.log(
+          chalk.yellow('\n   📱 iOS detected - Remember to run:')
+        );
+        console.log(chalk.cyan('      cd ios && pod install && cd ..\n'));
+      }
+    } else {
+      console.log(chalk.green('\n   ℹ️  Expo project - native dependencies handled automatically!\n'));
+    }
+
+    return true;
+  } catch (error) {
+    const isExpo = dependencies['expo'];
+    console.log(chalk.red('\n   ❌ Failed to install dependencies'));
+    console.log(chalk.gray(`   Error: ${error.message}`));
+    console.log(chalk.yellow('\n   Please install them manually:'));
+    if (isExpo) {
+      console.log(chalk.cyan(`   npx expo install ${REQUIRED_DEPENDENCIES.join(' ')}\n`));
+    } else {
+      console.log(chalk.cyan(`   npm install ${REQUIRED_DEPENDENCIES.join(' ')}\n`));
+    }
+    return false;
+  }
+}
+
+module.exports = { checkAndInstallDependencies };

package/src/createDirectories.js

@@ -0,0 +1,38 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const directories = [
+  'src/assets/images',
+  'src/assets/fonts',
+  'src/assets/icons',
+  'src/components/common',
+  'src/constants/sizings',
+  'src/constants/styles',
+  'src/constants/splash',
+  'src/hooks/splash',
+  'src/navigation/stack',
+  'src/navigation/bottom',
+  'src/screens/splash',
+  'src/screens/home',
+  'src/screens/profile',
+  'src/screens/settings',
+  'src/state/zustand',
+  'src/state/context',
+  'src/styles/splash',
+  'src/styles/home',
+  'src/styles/profile',
+  'src/styles/settings',
+  'src/types',
+  'src/utils',
+];
+
+async function createDirectories() {
+  for (const dir of directories) {
+    const dirPath = path.join(process.cwd(), dir);
+    await fs.ensureDir(dirPath);
+    console.log(chalk.gray(`   ✓ Created ${dir}`));
+  }
+}
+
+module.exports = { createDirectories };

package/src/generateFiles.js

@@ -0,0 +1,114 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+async function generateFiles() {
+  const templatesPath = path.join(__dirname, '../templates');
+
+  const files = [
+    // Constants
+    {
+      template: path.join(templatesPath, 'constants/SIZINGS.ts.template'),
+      destination: 'src/constants/sizings/SIZINGS.ts',
+    },
+    {
+      template: path.join(templatesPath, 'constants/COLORS.ts.template'),
+      destination: 'src/constants/styles/COLORS.ts',
+    },
+    {
+      template: path.join(templatesPath, 'constants/splash.constants.ts.template'),
+      destination: 'src/constants/splash/splash.constants.ts',
+    },
+
+    // Types
+    {
+      template: path.join(templatesPath, 'types/Type.ts.template'),
+      destination: 'src/types/Type.ts',
+    },
+
+    // Utils
+    {
+      template: path.join(templatesPath, 'utils/Util.ts.template'),
+      destination: 'src/utils/Util.ts',
+    },
+
+    // Navigation
+    {
+      template: path.join(templatesPath, 'navigation/StackNavigation.tsx.template'),
+      destination: 'src/navigation/stack/StackNavigation.tsx',
+    },
+    {
+      template: path.join(templatesPath, 'navigation/BottomTabNavigation.tsx.template'),
+      destination: 'src/navigation/bottom/BottomTabNavigation.tsx',
+    },
+
+    // Screens
+    {
+      template: path.join(templatesPath, 'screens/SplashScreen.tsx.template'),
+      destination: 'src/screens/splash/SplashScreen.tsx',
+    },
+    {
+      template: path.join(templatesPath, 'screens/HomeScreen.tsx.template'),
+      destination: 'src/screens/home/HomeScreen.tsx',
+    },
+    {
+      template: path.join(templatesPath, 'screens/ProfileScreen.tsx.template'),
+      destination: 'src/screens/profile/ProfileScreen.tsx',
+    },
+    {
+      template: path.join(templatesPath, 'screens/SettingsScreen.tsx.template'),
+      destination: 'src/screens/settings/SettingsScreen.tsx',
+    },
+
+    // Hooks
+    {
+      template: path.join(templatesPath, 'hooks/useSplashNavigation.ts.template'),
+      destination: 'src/hooks/splash/useSplashNavigation.ts',
+    },
+
+    // Styles
+    {
+      template: path.join(templatesPath, 'styles/splash.styles.ts.template'),
+      destination: 'src/styles/splash/splash.styles.ts',
+    },
+    {
+      template: path.join(templatesPath, 'styles/home.styles.ts.template'),
+      destination: 'src/styles/home/home.styles.ts',
+    },
+    {
+      template: path.join(templatesPath, 'styles/profile.styles.ts.template'),
+      destination: 'src/styles/profile/profile.styles.ts',
+    },
+    {
+      template: path.join(templatesPath, 'styles/settings.styles.ts.template'),
+      destination: 'src/styles/settings/settings.styles.ts',
+    },
+
+    // Root level - App.tsx
+    {
+      template: path.join(templatesPath, 'root/App.tsx.template'),
+      destination: 'App.tsx',
+    },
+  ];
+
+  // Generate all files
+  for (const file of files) {
+    const content = await fs.readFile(file.template, 'utf-8');
+    const destPath = path.join(process.cwd(), file.destination);
+    await fs.writeFile(destPath, content);
+    console.log(chalk.gray(`   ✓ Created ${file.destination}`));
+  }
+
+  // Copy PROJECT_ARCHITECTURE.md
+  const architectureMdSource = path.join(templatesPath, 'PROJECT_ARCHITECTURE.md');
+  const architectureMdDest = path.join(process.cwd(), 'PROJECT_ARCHITECTURE.md');
+
+  if (await fs.pathExists(architectureMdSource)) {
+    await fs.copy(architectureMdSource, architectureMdDest);
+    console.log(chalk.gray('   ✓ Created PROJECT_ARCHITECTURE.md'));
+  } else {
+    console.log(chalk.yellow('   ⚠ PROJECT_ARCHITECTURE.md template not found, skipping'));
+  }
+}
+
+module.exports = { generateFiles };