create-rn-starter-kit/template/README.md

Interactive CLI for creating modular React Native apps with Expo

# Create React Native Starter Kit CLI

A CLI tool for creating modular React Native applications with Expo. This tool generates customizable projects with a modular architecture using pre-configured templates for rapid prototyping.

## Features

- 🏗️ **Template-Based Architecture**: Choose from basic, auth, or full-featured templates
- 📦 **Pre-built Modules**: Core and feature modules ready to use
- 🛠️ **Interactive CLI**: Easy project setup with template selection
- 📱 **Rapid Prototyping**: Get started quickly with pre-configured setups
- 🔧 **Expo Integration**: Built on Expo's reliable foundation

## Getting Started / Installation

```bash
# Create a new project
npx create-rn-starter-kit my-app

# Navigate to the project directory
cd my-app

# Start the development server
npm start
```

## Usage

### Basic Usage

```bash
create-rn-starter-kit my-app
```

The CLI will prompt you to select which template you want to use for your project.

### Skip Prompts (Use Full Template)

```bash
create-rn-starter-kit my-app --yes
```

## Available Templates

### Basic Starter
- **Description**: Simple app with basic navigation and components
- **Best for**: Minimal setup, custom development from scratch
- **Modules**: None (clean slate)

### Auth Starter
- **Description**: Includes authentication and user management
- **Best for**: Apps requiring user authentication
- **Modules**: Splash Screen, Main Navigator, Account Overview

### Full Featured
- **Description**: Complete starter with theming, auth, and all modules
- **Best for**: Complex apps, rapid prototyping
- **Modules**: Splash, Authentication, Combined Auth, Summary, Everyday Banking, Cards, Applications

## Generated Project Structure

```
my-app/
├── src/
│   ├── config/
│   │   ├── modules.ts          # Module definitions
│   │   └── moduleLoader.ts     # Module loading utilities
│   └── modules/
│       ├── core/               # Essential modules
│       └── feature/            # Optional feature modules
├── assets/                     # Static assets
├── App.<template>.tsx          # Template-specific app entry point
├── App.tsx                     # Main app component
├── app.json                    # Expo configuration
├── package.json               # Dependencies
└── tsconfig.json              # TypeScript config
```

## Module System

The project uses a template-based module system defined in `src/config/modules.ts`. Each template includes a pre-selected set of modules that work together seamlessly.

### Available Modules

#### Core Modules
- **Splash**: App startup and loading screens
- **Authentication**: User login and authorization
- **Combined Auth**: Complete authentication flow
- **Main Navigator**: React Navigation integration

#### Feature Modules
- **Account Overview**: Dashboard components
- **Summary**: Account summary and overview
- **Everyday Banking**: Daily banking operations
- **Cards**: Credit and debit card management
- **Applications**: Apply for banking products
- **Statements**: Transaction history and timelines
- **Payments**: Payment processing forms

### Adding Custom Modules

Want to add your own modules? Here's how:

#### 1. Create Module Structure

```bash
# For core modules
mkdir -p src/modules/core/your-module

# For feature modules
mkdir -p src/modules/feature/your-module
```

#### 2. Create Module Files

Create your module component:

```typescript
// src/modules/feature/your-module/index.tsx
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';

const YourModule = () => {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Your Custom Module</Text>
      {/* Add your module content here */}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
  },
});

export default YourModule;
```

#### 3. Add Module to Configuration

Add your module to `src/config/modules.ts`:

```typescript
{
  id: 'your-module',
  name: 'Your Module',
  description: 'Description of what this module does',
  category: 'feature', // or 'core'
  enabled: true,
  dependencies: [], // List any required modules
  priority: 10, // Loading priority (lower numbers load first)
  importFn: () => import('../modules/feature/your-module'),
}
```

#### 4. Import and Use Your Module

Import and use your module in your App component:

```typescript
// App.tsx (or your specific App.<template>.tsx)
import React from 'react';
import YourModule from './src/modules/feature/your-module';

const App = () => {
  return (
    <YourModule />
    // Or integrate it into your navigation/layout
  );
};

export default App;
```

#### 5. Test Your Module

Start the development server to test your changes:

```bash
npm start
```

This will start the Expo development server. You can then:
- Press `i` to open iOS simulator
- Press `a` to open Android emulator  
- Press `w` to open in web browser
- Scan the QR code with Expo Go app on your device

### Module Communication

Modules communicate through standard React patterns:

- **Props**: Pass data down to child modules
- **Context**: Share state across multiple modules
- **Direct imports**: Import utilities or components from other modules
- **Navigation**: Use React Navigation to navigate between module screens

Example using React Context:

```typescript
// src/context/AppContext.tsx
import React, { createContext, useContext } from 'react';

const AppContext = createContext(null);

export const AppProvider = ({ children }) => {
  const [user, setUser] = useState(null);
  
  return (
    <AppContext.Provider value={{ user, setUser }}>
      {children}
    </AppContext.Provider>
  );
};

export const useApp = () => useContext(AppContext);
```

Then use it in your modules:

```typescript
// In your module
import { useTheme } from '../../context/AppContext';

const YourModule = () => {
  const { user } = useApp();
  
  return (
    <Text>Welcome, {user?.name}</Text>
  );
};
```

## Theming System

The starter kit includes a comprehensive theming system that supports both light/dark modes and multiple brand configurations.

### Using Themes

Wrap your app with the `ThemeProvider` to enable theming:

```typescript
// App.tsx
import { ThemeProvider } from './src/theme/ThemeProvider';

export default function App() {
  return (
    <ThemeProvider initialTheme="dark">
      {/* Your app components */}
    </ThemeProvider>
  );
}
```

### Using Themes in Components

Access theme values in your components using the `useTheme` hook:

```typescript
import { useTheme } from '../theme/ThemeProvider';

const MyComponent = () => {
  const { theme, themeName, brandName, toggleTheme, setBrand } = useTheme();
  
  return (
    <View style={{ backgroundColor: theme.colors.background }}>
      <Text style={{ color: theme.colors.text }}>
        Current theme: {themeName} ({brandName})
      </Text>
    </View>
  );
};
```

### Available Theme Properties

The theme object provides:
- **Colors**: `background`, `text`, `primary`, `secondary`, etc.
- **Typography**: Font sizes, weights, and families
- **Spacing**: Consistent spacing values
- **Brand-specific**: Customizable brand colors and styling

### Theme Configuration

Customize themes by editing the brand files in `src/theme/brands/`:
- `default.json` - Default brand theme
- `brandA.json` - Alternative brand A
- `brandB.json` - Alternative brand B

### Switching Themes

You can switch themes programmatically:

```typescript
const { toggleTheme, setBrand } = useTheme();

// Toggle between light and dark
toggleTheme();

// Switch to a specific brand
setBrand('brandA'); // or 'brandB', 'default'
```

**Note**: The theming system is designed for manual theme management. You can extend it to include automatic theme switching, user preferences storage, or system theme detection based on your app's needs.

For detailed contribution guidelines, including CLI development, see [CONTRIBUTING.md](https://github.com/dankupfer/rn-starter-kit/blob/main/CONTRIBUTING.md).