React Architect 🏗️

A powerful CLI scaffolding tool for React + TypeScript applications

Generate opinionated folder structures and component templates with Angular-style architecture for Vite + React + TypeScript projects.

---

🎯 Features

• 🚀 Quick Scaffolding: Initialize a complete project structure in seconds
• 📦 Angular-Style Architecture: Organized modules, services, and components
• 🎨 Component Generation: Auto-generate components with TypeScript, SCSS modules, and type definitions
• 🔧 Service Layer: Class-based singleton services for business logic
• 🪝 Custom Hooks: Generate custom React hooks with boilerplate
• 📁 Module System: Organize features into self-contained modules
• ⚡ TypeScript First: Full TypeScript support out of the box
• 🎯 Opinionated Structure: Best practices baked in

---

📦 Installation

Global Installation (Recommended)

npm install -g react-architect

Local Development

npx react-architect init

---

🚀 Quick Start

1. Initialize Project Structure

react-architect init

This creates the following folder structure:

src/
├── core/
│   ├── services/
│   ├── hooks/
│   └── context/
├── components/
├── shared/
│   ├── ui/
│   └── utils/
└── modules/

2. Generate Components

# Generate a component in src/components
react-architect generate component Button

# Or use the shorthand
react-architect g component Button

This creates:

src/components/Button/
├── Button.tsx
├── Button.module.scss
├── Button.types.ts
└── index.ts

3. Generate Components in Modules

# Generate a component inside a specific module
react-architect g component LoginForm --module auth

This creates:

src/modules/auth/components/LoginForm/
├── LoginForm.tsx
├── LoginForm.module.scss
├── LoginForm.types.ts
└── index.ts

---

📚 Commands

init

Initialize the recommended folder structure.

react-architect init

generate (alias: g)

Generate components, modules, services, or hooks.

react-architect generate <type> <name> [options]

Types:

• component - React component with styles and types
• module - Feature module with folder structure
• service - Singleton service class
• hook - Custom React hook

Options:

• -m, --module <name> - Generate inside a specific module

Examples:

# Generate a component
react-architect g component Button

# Generate a component in a module
react-architect g component LoginForm --module auth
react-architect g component LoginForm -m auth  # shorthand

module (alias: m) - NEW! 🎉

Cleaner syntax for generating items inside a specific module.

react-architect module <moduleName> <type> <name>

Types:

• component - React component
• service - Service class
• hook - Custom hook

Examples:

# Generate components in auth module
react-architect module auth component LoginForm
react-architect m auth component RegisterForm  # shorthand

# Generate service in auth module
react-architect m auth service Auth

# Generate hook in auth module
react-architect m auth hook useAuth

list-modules (alias: ls) - NEW! 🎉

List all available modules in your project.

react-architect list-modules
react-architect ls  # shorthand

Output:

📦 Available modules:
  • auth
  • products
  • dashboard

Total: 3 module(s)

---

🎨 Examples

Generate a Component

react-architect g component Header

Output:

// Header.tsx
import React from 'react';
import styles from './Header.module.scss';
import { HeaderProps } from './Header.types';

export const Header: React.FC<HeaderProps> = ({ children, className = '' }) => {
  return (
    <div className={`${styles.header} ${className}`}>
      <h2>Header Component</h2>
      {children}
    </div>
  );
};

Generate a Service

react-architect g service Auth

Output:

// AuthService.ts
class AuthService {
  private static instance: AuthService;
  
  private constructor() {
    this.initialize();
  }

  public static getInstance(): AuthService {
    if (!AuthService.instance) {
      AuthService.instance = new AuthService();
    }
    return AuthService.instance;
  }

  // ... methods
}

export const authService = AuthService.getInstance();

Generate a Hook

react-architect g hook useAuth

Output:

// useAuth.ts
import { useState, useEffect } from 'react';

export const useAuth = () => {
  const [data, setData] = useState<any>(null);
  const [loading, setLoading] = useState<boolean>(false);
  const [error, setError] = useState<Error | null>(null);

  // ... hook logic

  return { data, loading, error };
};

Generate a Module

react-architect g module auth

Output:

src/modules/auth/
├── components/
├── services/
├── hooks/
└── index.ts

Generate Component Inside Module

# Traditional way with --module flag
react-architect g component LoginForm --module auth

# Or use the cleaner module command (NEW!)
react-architect module auth component LoginForm
react-architect m auth component LoginForm  # shorthand

---

🏗️ Architecture

React Architect enforces a clean, scalable architecture:

Core

Global services, hooks, and context that are used across the entire application.

Components

Reusable components that aren't tied to a specific feature.

Shared

• ui/: Common UI components (buttons, inputs, modals)
• utils/: Helper functions and utilities

Modules

Feature-based modules containing:

• components/: Feature-specific components
• services/: Business logic and API calls
• hooks/: Feature-specific custom hooks

---

📂 File Structure

Component Structure

Each component gets:

• ComponentName.tsx - React component
• ComponentName.module.scss - Scoped styles
• ComponentName.types.ts - TypeScript interfaces
• index.ts - Clean exports

Module Structure

src/modules/feature-name/
├── components/          # Feature components
├── services/           # Feature services
├── hooks/              # Feature hooks
└── index.ts            # Module exports

---

🛠️ Development

Local Testing

1. Clone the repository:

git clone https://github.com/yourusername/react-architect.git
cd react-architect

2. Install dependencies:

npm install

3. Link the package locally:

npm link

4. Test the CLI:

react-architect --help

5. Unlink when done:

npm unlink -g react-architect

---

📤 Publishing to NPM

First-Time Setup

1. Create an NPM account at npmjs.com

2. Login to NPM:

npm login

Publishing

1. Update version in package.json:

npm version patch  # or minor, or major

2. Publish to NPM:

npm publish

Version Management

• Patch (1.0.0 → 1.0.1): Bug fixes

npm version patch

• Minor (1.0.0 → 1.1.0): New features

npm version minor

• Major (1.0.0 → 2.0.0): Breaking changes

npm version major

Update Package

npm version patch
npm publish

---

🔮 Future Enhancements

Planned Features

• Interactive Mode: CLI prompts for configuration
• Config File: .reactarchitectrc for project-specific settings
• Storybook Integration: Auto-generate Storybook stories
• JavaScript Support: Generate JS files instead of TS
• Testing Templates: Auto-generate test files
• Custom Templates: User-defined template support
• Context Generation: Generate React context providers
• API Client Generator: Generate API service boilerplate
• Route Generation: Auto-generate route configurations
• Form Generation: Generate form components with validation

Community Ideas

• Support for other styling solutions (Styled Components, Tailwind)
• Redux/Zustand slice generators
• GraphQL query generators
• Docker configuration
• CI/CD pipeline templates

---

🤝 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
• Built for the React community
• Powered by Node.js, Commander, and Handlebars

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the React community

⭐ Star this repo if you find it helpful!