RAF CLI

React Architecture Framework

A powerful CLI for creating scalable React and React Native applications with MVP architecture

📖 What is RAF?

RAF stands for React Architecture Framework - a comprehensive CLI tool that provides:

• 🏗️ Opinionated architecture based on MVP (Model-View-Presenter) pattern
• 🚀 Rapid development with powerful code generators
• 📦 Scalable structure for growing applications
• ⚛️ React ecosystem integration (React & React Native)

🚀 Features

• ✨ Opinionated MVP Architecture - Follows Model-View-Presenter pattern for scalable applications
• 🎯 Code Generation - Generate models, services, hooks, components, pages, and complete CRUD operations
• 📦 Module System - NestJS-like nested module structure for better organization
• 🔄 Auto-Import - Automatically updates barrel exports (index.ts) when generating files
• ⚛️ React & React Native - Full support for both web and mobile applications
• 🎨 TypeScript First - Built with TypeScript for type safety
• 🛠️ Configurable - Customize paths, imports, and templates via raf.json
• 📝 Prettier Integration - Auto-format generated code
• 🔌 Modern Stack - Integrates with TanStack Query, React Hook Form, Axios, and more

📦 Installation

Global Installation (Recommended)

npm install -g raf-cli

Or using yarn:

yarn global add raf-cli

Or using pnpm:

pnpm add -g raf-cli

Verify Installation

raf --version

🎯 Quick Start

Create a New Project

# Create a new React project (interactive template selection)
raf new my-app

# React templates available:
# - TanStack Router + Tailwind CSS - Recommended ⭐
# - Basic Vite + React - Minimal setup

# Create a new React Native project (interactive template selection)
raf new my-mobile-app --template react-native

# React Native templates available:
# - Expo Router + NativeWind (Tailwind CSS) - Recommended ⭐
# - Tabs (Expo Router) - Navigation with tabs
# - Blank - Basic Expo app

Initialize in Existing Project

cd my-existing-project
raf init

Generate Complete Features

# Generate authentication with Better Auth
raf feature auth
# or
raf f auth

# Interactive prompts for:
# - Email & Password
# - Phone & OTP
# - Social Auth (Google, Apple, Facebook, GitHub)
# - Login, Signup, Logout, Password Reset
# - Auto-generates .env file with all variables

# Platform-specific setup:
# - React: Server-side config included
# - React Native: Client config + backend setup guide

Generate Your First Resource

# Generate a complete resource (CRUD)
raf g res User
# or
raf g resource User
# or
raf g crud User

# This creates:
# - Model (User interface + DTOs)
# - Service (API calls)
# - Hooks (queries + mutations + form)
# - Form component
# - Table component
# - List page

Generate Individual Components

# Generate a model
raf generate model User

# Generate a service
raf generate service User

# Generate hooks for data fetching
raf generate hook User --type query

# Generate a component
raf generate component UserCard

# Generate a complete CRUD
raf generate crud Product

📖 Documentation

Quick Links

• 📘 What is RAF? - Learn about the React Architecture Framework
• 🚀 Quick Start Guide - Get started in 5 minutes
• 📦 Installation Guide - Detailed installation instructions
• 📚 Commands Reference - Complete command reference
• 🤝 Contributing Guide - How to contribute

Table of Contents

1. Commands
2. Configuration
3. Architecture
4. Generators
5. Module System
6. Examples
7. Best Practices

🎮 Commands

raf new <project-name>

Create a new RAF project from scratch using Vite's official scaffolding.

raf new my-app [options]

How it works:

For React:

1. 🚀 Uses npm create vite@latest to scaffold a React project (official Vite template)
2. 📁 Adds RAF directory structure (models, services, hooks, components, pages)
3. 📦 Installs RAF dependencies (Axios, TanStack Query, React Hook Form, Zod)
4. ⚙️ Configures path aliases (@/)
5. 🔧 Creates API client and QueryClient configuration
6. 📝 Generates raf.json configuration

For React Native:

1. 🚀 Uses npx create-expo-app@latest to scaffold an Expo project (official Expo template)
2. 📁 Adds RAF directory structure (models, services, hooks, components, screens, navigation)
3. 📦 Installs RAF dependencies (Axios, TanStack Query, React Hook Form, Zod, React Navigation)
4. ⚙️ Configures path aliases (@/)
5. 🔧 Creates API client, QueryClient, and Navigation setup
6. 📝 Generates raf.json configuration

Options:

• -t, --template <template> - Project template: react or react-native (default: react)
• --skip-install - Skip dependency installation

Example:

raf new my-awesome-app --template react

What you get:

React:

• ✅ Vite-powered React project (fast HMR, optimized builds)
• ✅ RAF MVP architecture directories
• ✅ Pre-configured API client with interceptors
• ✅ TanStack Query setup for data fetching
• ✅ TypeScript with path aliases
• ✅ Ready to use raf generate commands

React Native:

• ✅ Expo-powered React Native project (fast refresh, easy deployment)
• ✅ RAF MVP architecture directories
• ✅ Pre-configured API client with interceptors
• ✅ TanStack Query setup for data fetching
• ✅ React Navigation setup
• ✅ TypeScript with path aliases
• ✅ Ready to use raf generate commands

raf init

Initialize RAF in an existing project.

raf init [options]

Options:

• -t, --type <type> - Project type: react or react-native (default: react)

Example:

raf init --type react

raf generate (alias: g)

Generate code artifacts.

Generate Model

raf generate model <name> [options]
raf g m <name> [options]

Options:

• -p, --path <path> - Custom path for the model

Example:

raf g model User
raf g model Product -p src/modules/shop/models

Generated files:

src/models/
└── user.model.ts
└── index.ts (updated)

Generate Service

raf generate service <name> [options]
raf g s <name> [options]

Options:

• -p, --path <path> - Custom path for the service

Example:

raf g service User
raf g service Product -p src/modules/shop/services

Generated files:

src/services/user/
├── user.service.ts
└── index.ts
src/services/api/
└── api.client.ts (if not exists)

Generate Hook

raf generate hook <name> [options]
raf g h <name> [options]

Options:

• -p, --path <path> - Custom path for the hook
• -t, --type <type> - Hook type: query, mutation, form, or custom (default: custom)

Examples:

# Generate query hooks (useUsers, useUser, useCreateUser, etc.)
raf g hook User --type query

# Generate mutation hook
raf g hook UpdateProfile --type mutation

# Generate form hook with validation
raf g hook UserForm --type form

# Generate custom hook
raf g hook WindowSize --type custom

Generate Component

raf generate component <name> [options]
raf g c <name> [options]

Options:

• -p, --path <path> - Custom path for the component
• -t, --type <type> - Component type: common, form, table, chart, or modal (default: common)

Examples:

raf g component Button --type common
raf g component UserModal --type modal
raf g component DataChart --type chart

Generated files:

src/components/common/Button/
├── Button.tsx
└── index.ts

Generate Page

raf generate page <name> [options]
raf g p <name> [options]

Options:

• -p, --path <path> - Custom path for the page

Example:

raf g page Dashboard
raf g page UserProfile

Generated files:

src/pages/Dashboard/
├── DashboardPage.tsx
└── index.ts

Generate Module

raf generate module <name> [options]

Options:

• -p, --path <path> - Custom path for the module

Example:

raf g module Auth
raf g module Shop

Generated structure:

src/modules/auth/
├── models/
│   └── index.ts
├── services/
│   └── index.ts
├── hooks/
│   └── index.ts
├── components/
│   └── index.ts
├── pages/
│   └── index.ts
├── index.ts
└── README.md

Generate Resource (CRUD)

Generate a complete resource with all CRUD operations (model + service + hooks + form + table + page).

raf generate resource <name> [options]
raf g res <name> [options]
# or
raf generate crud <name> [options]
raf g crud <name> [options]

Options:

• -p, --path <path> - Custom path for the resource

Example:

# All of these do the same thing:
raf g res Product
raf g resource Product
raf g crud Product

What it generates:

src/models/product.model.ts              # TypeScript interface + DTOs
src/services/product/product.service.ts  # API service with CRUD methods
src/hooks/queries/use-products.ts        # TanStack Query hooks
src/hooks/forms/use-product-form.ts      # React Hook Form + Zod validation
src/components/forms/ProductForm/        # Form component
src/components/tables/ProductTable/      # Table component with columns
src/pages/ProductListPage/               # List page with table

What you get:

• ✅ Full CRUD operations (Create, Read, Update, Delete)
• ✅ Type-safe API calls
• ✅ Data fetching with caching
• ✅ Form validation
• ✅ Table with sorting/filtering
• ✅ Ready-to-use page component

Generate Form

raf generate form <name> [options]

Example:

raf g form UserRegistration

Generate Table

raf generate table <name> [options]

Example:

raf g table UserList

⚙️ Configuration

RAF CLI uses a raf.json file in your project root for configuration.

Default Configuration

{
  "projectName": "my-app",
  "projectType": "react",
  "version": "1.0.0",
  "paths": {
    "src": "src",
    "models": "src/models",
    "services": "src/services",
    "hooks": "src/hooks",
    "components": "src/components",
    "pages": "src/pages",
    "utils": "src/utils",
    "constants": "src/constants",
    "config": "src/config"
  },
  "imports": {
    "autoImport": true,
    "useBarrelExports": true,
    "pathAlias": "@"
  },
  "templates": {
    "customTemplatesPath": null
  },
  "formatting": {
    "usePrettier": true,
    "prettierConfig": null
  },
  "typescript": {
    "strict": true
  }
}

React Native Configuration

For React Native projects, additional configuration is available:

{
  "projectType": "react-native",
  "reactNative": {
    "navigation": "react-navigation",
    "stateManagement": "context"
  }
}

Options:

• navigation: react-navigation, expo-router, or none
• stateManagement: context, zustand, redux, or none

🏗️ Architecture

RAF CLI follows the MVP (Model-View-Presenter) architecture pattern, adapted for React applications.

Directory Structure

my-app/
├── src/
│   ├── models/              # Data models and TypeScript interfaces
│   │   ├── user.model.ts
│   │   ├── product.model.ts
│   │   └── index.ts
│   │
│   ├── services/            # API services and business logic
│   │   ├── api/
│   │   │   ├── api.client.ts
│   │   │   └── index.ts
│   │   ├── user/
│   │   │   ├── user.service.ts
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   ├── hooks/               # Custom React hooks (Presenters)
│   │   ├── queries/         # TanStack Query hooks
│   │   │   ├── use-users.ts
│   │   │   └── index.ts
│   │   ├── mutations/       # Mutation hooks
│   │   ├── forms/           # Form hooks with validation
│   │   │   ├── use-user-form.ts
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   ├── components/          # React components (Views)
│   │   ├── common/          # Reusable UI components
│   │   │   ├── Button/
│   │   │   ├── Input/
│   │   │   └── index.ts
│   │   ├── forms/           # Form components
│   │   │   ├── UserForm/
│   │   │   └── index.ts
│   │   ├── tables/          # Table components
│   │   │   ├── UserTable/
│   │   │   └── index.ts
│   │   ├── charts/          # Chart components
│   │   ├── modals/          # Modal components
│   │   └── index.ts
│   │
│   ├── pages/               # Page-level components
│   │   ├── Dashboard/
│   │   │   ├── DashboardPage.tsx
│   │   │   └── index.ts
│   │   ├── Users/
│   │   │   ├── UserListPage.tsx
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   ├── utils/               # Utility functions
│   ├── constants/           # Application constants
│   ├── config/              # Configuration files
│   └── App.tsx
│
├── raf.json                 # RAF CLI configuration
├── package.json
└── tsconfig.json

Layer Responsibilities

1. Models (/src/models)

Define data structures and TypeScript interfaces.

// user.model.ts
export interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
  createdAt: Date;
}

export interface CreateUserDto {
  name: string;
  email: string;
  password: string;
}

export interface UpdateUserDto extends Partial<CreateUserDto> {}

2. Services (/src/services)

Handle API communication and business logic.

// user.service.ts
import { apiClient } from '../api/api.client';
import { User, CreateUserDto } from '@/models';

export class UserService {
  private static endpoint = '/users';

  static async getAll(): Promise<User[]> {
    const { data } = await apiClient.get<User[]>(this.endpoint);
    return data;
  }

  static async create(userData: CreateUserDto): Promise<User> {
    const { data } = await apiClient.post<User>(this.endpoint, userData);
    return data;
  }
}

3. Hooks (/src/hooks)

Manage state and side effects (Presenters).

// use-users.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { UserService } from '@/services';

export const useUsers = () => {
  return useQuery({
    queryKey: ['users'],
    queryFn: UserService.getAll,
  });
};

export const useCreateUser = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: UserService.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
};

4. Components (/src/components)

Presentational UI components (Views).

// UserCard.tsx
import React from 'react';
import { User } from '@/models';

interface UserCardProps {
  user: User;
  onEdit: (user: User) => void;
}

export const UserCard: React.FC<UserCardProps> = ({ user, onEdit }) => {
  return (
    <div className="card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
      <button onClick={() => onEdit(user)}>Edit</button>
    </div>
  );
};

5. Pages (/src/pages)

Compose features and handle routing.

// UserListPage.tsx
import React, { useState } from 'react';
import { useUsers, useCreateUser } from '@/hooks';
import { UserTable, UserForm } from '@/components';

export const UserListPage: React.FC = () => {
  const { data: users, isLoading } = useUsers();
  const createUser = useCreateUser();

  return (
    <div>
      <h1>Users</h1>
      <UserTable data={users || []} isLoading={isLoading} />
    </div>
  );
};

🎨 Generators

Model Generator

Generates TypeScript interfaces for data models.

Command:

raf g model User

Output:

// user.model.ts
export interface User {
  id: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateUserDto {
  // Add your properties here
}

export interface UpdateUserDto extends Partial<CreateUserDto> {}

export interface UserQuery {
  page?: number;
  limit?: number;
  search?: string;
  sortBy?: keyof User;
  sortOrder?: 'asc' | 'desc';
}

Service Generator

Generates API service classes with CRUD operations.

Command:

raf g service User

Output:

// user.service.ts
import { apiClient } from '../api/api.client';
import { User, CreateUserDto, UpdateUserDto } from '@/models';

export class UserService {
  private static endpoint = '/users';

  static async getAll(): Promise<User[]> {
    const { data } = await apiClient.get<User[]>(this.endpoint);
    return data;
  }

  static async getById(id: string): Promise<User> {
    const { data } = await apiClient.get<User>(`${this.endpoint}/${id}`);
    return data;
  }

  static async create(userData: CreateUserDto): Promise<User> {
    const { data } = await apiClient.post<User>(this.endpoint, userData);
    return data;
  }

  static async update(id: string, userData: UpdateUserDto): Promise<User> {
    const { data } = await apiClient.put<User>(`${this.endpoint}/${id}`, userData);
    return data;
  }

  static async delete(id: string): Promise<void> {
    await apiClient.delete(`${this.endpoint}/${id}`);
  }
}

Hook Generator

Generates custom React hooks for different purposes.

Query Hook

Command:

raf g hook User --type query

Output:

// use-users.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { UserService } from '@/services';

export const useUsers = () => {
  return useQuery({
    queryKey: ['users'],
    queryFn: UserService.getAll,
  });
};

export const useUser = (id: string) => {
  return useQuery({
    queryKey: ['users', id],
    queryFn: () => UserService.getById(id),
    enabled: !!id,
  });
};

export const useCreateUser = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: UserService.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
};

Form Hook

Command:

raf g hook UserForm --type form

Output:

// use-user-form.ts
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';

const userFormSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
});

export type UserFormData = z.infer<typeof userFormSchema>;

export const useUserForm = (defaultValues?: Partial<UserFormData>) => {
  return useForm<UserFormData>({
    resolver: zodResolver(userFormSchema),
    defaultValues: defaultValues || {
      name: '',
      email: '',
    },
  });
};

📦 Module System

RAF CLI supports a NestJS-like module system for better code organization.

Creating a Module

raf g module Auth

This creates a complete module structure:

src/modules/auth/
├── models/
│   └── index.ts
├── services/
│   └── index.ts
├── hooks/
│   └── index.ts
├── components/
│   └── index.ts
├── pages/
│   └── index.ts
├── index.ts
└── README.md

Using Modules

Generate components within a module:

# Generate model in Auth module
raf g model Login -p src/modules/auth/models

# Generate service in Auth module
raf g service Auth -p src/modules/auth/services

# Generate component in Auth module
raf g component LoginForm -p src/modules/auth/components

Importing from Modules

// Import from module
import { LoginModel, AuthService, LoginForm } from '@/modules/auth';

💡 Examples

Example 1: Building a User Management Feature

# Step 1: Generate complete CRUD
raf g crud User

# This generates:
# - src/models/user.model.ts
# - src/services/user/user.service.ts
# - src/hooks/queries/use-users.ts
# - src/hooks/forms/use-user-form.ts
# - src/components/forms/UserForm/
# - src/components/tables/UserTable/
# - src/pages/UserListPage/

Example 2: Creating a Custom Feature Module

# Step 1: Create module
raf g module Shop

# Step 2: Generate models
raf g model Product -p src/modules/shop/models
raf g model Cart -p src/modules/shop/models

# Step 3: Generate services
raf g service Product -p src/modules/shop/services
raf g service Cart -p src/modules/shop/services

# Step 4: Generate hooks
raf g hook Product --type query -p src/modules/shop/hooks
raf g hook Cart --type query -p src/modules/shop/hooks

# Step 5: Generate components
raf g component ProductCard -p src/modules/shop/components
raf g component CartSummary -p src/modules/shop/components

# Step 6: Generate pages
raf g page ProductList -p src/modules/shop/pages
raf g page Checkout -p src/modules/shop/pages

Example 3: React Native App

# Create React Native project
raf new MyMobileApp --template react-native

cd MyMobileApp

# Generate CRUD for Posts
raf g crud Post

# The generated components will use React Native components
# (View, Text, StyleSheet, etc.)

🎯 Best Practices

1. Separation of Concerns

• Models: Only define data structures
• Services: Handle API calls and business logic
• Hooks: Manage state and side effects
• Components: Focus on UI rendering
• Pages: Compose features

2. Use Barrel Exports

Enable barrel exports in raf.json for cleaner imports:

{
  "imports": {
    "useBarrelExports": true
  }
}

This allows:

// Instead of
import { User } from '@/models/user.model';
import { Product } from '@/models/product.model';

// You can do
import { User, Product } from '@/models';

3. Path Aliases

Configure path aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

4. Module Organization

For large applications, use modules:

src/
├── modules/
│   ├── auth/
│   ├── shop/
│   ├── blog/
│   └── admin/
└── shared/
    ├── components/
    ├── hooks/
    └── utils/

5. Type Safety

Always use TypeScript and enable strict mode:

{
  "typescript": {
    "strict": true
  }
}

6. Code Formatting

Enable Prettier for consistent code style:

{
  "formatting": {
    "usePrettier": true
  }
}

🔧 Advanced Usage

Custom Templates

You can create custom templates for generators:

1. Create a templates directory:

mkdir -p .raf/templates

2. Add custom EJS templates:

.raf/templates/
├── model.ejs
├── service.ejs
└── component.ejs

3. Update raf.json:

{
  "templates": {
    "customTemplatesPath": ".raf/templates"
  }
}

Custom Paths

Override default paths in raf.json:

{
  "paths": {
    "src": "app",
    "models": "app/domain/models",
    "services": "app/infrastructure/services",
    "components": "app/presentation/components"
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Angular CLI and NestJS CLI
• Built with Commander.js
• Powered by TypeScript

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ by the RAF Team

Website • Documentation • Twitter

To install dependencies:

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.2.21. Bun is a fast all-in-one JavaScript runtime.

raf-cli