⚒️ ForgeCLI

React Architecture Engine for scalable frontend applications

Generate, structure, and manage React application architecture directly from your terminal.

🚀 What is ForgeCLI?

ForgeCLI is a developer tool for building scalable and maintainable React applications through a plugin-driven architecture and AST-based code transformation.

Instead of manually managing deeply nested providers, imports, and application configuration, ForgeCLI lets developers compose application-level features through plugins.

forge add auth
forge add theme
forge add state

ForgeCLI then determines the correct provider order, updates the application through AST transformations, and rebuilds the provider tree deterministically.

The core idea

Define architecture as plugins. Let ForgeCLI manage the composition.

🎯 Why ForgeCLI?

As React applications grow, application-level providers can quickly become difficult to manage.

A typical application might evolve into:

<AuthProvider>
  <ThemeProvider>
    <Router>
      <StateProvider>
        <QueryProvider>
          <App />
        </QueryProvider>
      </StateProvider>
    </Router>
  </ThemeProvider>
</AuthProvider>

This creates several problems:

❌ Manual provider nesting
❌ Provider ordering becomes difficult to reason about
❌ Duplicate providers and imports
❌ Repetitive application configuration
❌ Fragile code modifications
❌ Difficult-to-maintain architecture

ForgeCLI addresses this by treating providers as composable architectural plugins.

✨ Core Features

Feature	Description
🔌 Plugin Architecture	Add application capabilities through modular plugins
🧠 AST Transformation	Safely modify React source code using Babel AST
⚡ Priority Resolution	Automatically determine provider nesting order
♻️ Idempotent Execution	Re-running commands does not duplicate providers
🔄 Deterministic Rebuilds	Provider trees are rebuilt from plugin configuration
📦 Automatic Imports	Detect and inject required imports
🛠️ CLI Workflow	Manage architecture directly from the terminal
🧩 Extensible Design	Designed for future community plugins

🧩 How ForgeCLI Thinks About Architecture

ForgeCLI separates what a feature is from how it is inserted into the application.

A plugin can describe:

{
  name: "auth",
  provider: "AuthProvider",
  priority: 1,
  imports: [
    "@/providers/AuthProvider"
  ]
}

ForgeCLI uses this metadata to determine how the feature should be composed into the application.

For example:

Plugin Configuration
        │
        ▼
   Priority Sort
        │
        ▼
Provider Tree
        │
        ▼
 AST Transformation
        │
        ▼
Updated React Application

This allows architecture to become declarative rather than manually maintained.

🔌 Plugin System

Features are represented as plugins.

Example:

forge add auth
forge add theme
forge add state

A plugin can define:

Provider component
Required imports
Priority
Configuration
Dependencies
Future compatibility metadata

Example

AuthProvider
Priority: 1

ThemeProvider
Priority: 10

StateProvider
Priority: 20

ForgeCLI resolves the order automatically.

Generated structure:

<AuthProvider>
  <ThemeProvider>
    <StateProvider>
      <App />
    </StateProvider>
  </ThemeProvider>
</AuthProvider>

🧠 AST-Based Code Transformation

ForgeCLI uses Babel AST tooling instead of fragile string or regex manipulation.

Rather than searching for text such as:

<App />

and injecting code around it, ForgeCLI works with the actual structure of the JavaScript/TypeScript program.

Transformation Pipeline

React Source File
       │
       ▼
   Parse AST
       │
       ▼
Analyze Application Tree
       │
       ▼
Extract Providers
       │
       ▼
Resolve Plugin Order
       │
       ▼
Rebuild Provider Tree
       │
       ▼
Inject Required Imports
       │
       ▼
Generate Source Code

Why AST?

AST-based transformations provide:

✅ Structural code awareness
✅ Safer transformations
✅ Less fragile than regex
✅ Better handling of nested JSX
✅ Easier future extensibility
✅ Cleaner architectural manipulation

⚡ Priority-Based Provider Injection

Provider order can matter.

For example:

AuthProvider  → Priority 1
ThemeProvider → Priority 10
StateProvider → Priority 20

ForgeCLI sorts providers by priority before constructing the final tree.

Result

<AuthProvider>
  <ThemeProvider>
    <StateProvider>
      <App />
    </StateProvider>
  </ThemeProvider>
</AuthProvider>

This removes the need for developers to manually remember provider ordering.

♻️ Deterministic Rebuild Engine

ForgeCLI follows a rebuild-oriented architecture.

Instead of continuously applying patches to an already modified provider tree, ForgeCLI can reconstruct the desired structure from the current plugin configuration.

Current Application
        │
        ▼
Extract Existing Structure
        │
        ▼
Identify Managed Providers
        │
        ▼
Resolve Plugin Configuration
        │
        ▼
Sort By Priority
        │
        ▼
Rebuild Provider Tree
        │
        ▼
Generate Source

Why rebuild?

This provides:

Predictable output
Easier debugging
Reduced provider conflicts
Cleaner transformations
Better repeatability

♻️ Idempotent Execution

ForgeCLI is designed to make repeated operations safe.

Running:

forge add auth
forge add auth

should not result in:

<AuthProvider>
  <AuthProvider>
    <App />
  </AuthProvider>
</AuthProvider>

Instead, ForgeCLI recognizes that the provider already exists.

Expected behavior

First execution
      ↓
Add AuthProvider

Second execution
      ↓
Detect existing provider
      ↓
No duplicate insertion

The same principle applies to imports.

📦 Automatic Import Management

ForgeCLI manages imports required by plugins.

For example, when adding authentication:

import { AuthProvider } from "@/providers/AuthProvider";

ForgeCLI can:

Detect existing imports
Add missing imports
Avoid duplicate imports
Keep transformations consistent

This keeps generated application code clean.

📦 Installation

Install ForgeCLI globally using npm:

npm install -g @shubham12568/forgecli

Verify the installation:

forge --version

🚀 Quick Start

Create a new application:

forge create my-app

Move into the project:

cd my-app

Add application features:

forge add auth
forge add theme

View available templates:

forge list

Inspect a template:

forge info react-ts

Install a plugin:

forge install plugin-name

🛠️ CLI Commands

Command	Purpose
`forge create <name>`	Create a new application
`forge add <plugin>`	Add a feature/plugin
`forge list`	List available templates or plugins
`forge info <name>`	Display template/plugin information
`forge install <plugin>`	Install a plugin
`forge --version`	Display installed ForgeCLI version

🏗️ Architecture

                         ┌─────────────────┐
                         │   User Command  │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │   ForgeCLI      │
                         │     Engine      │
                         └────────┬────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
              ┌──────────┐ ┌────────────┐ ┌─────────────┐
              │  Plugin  │ │  Config    │ │    CLI      │
              │  System  │ │  Loader    │ │  Commands   │
              └────┬─────┘ └─────┬──────┘ └─────────────┘
                   │             │
                   └──────┬──────┘
                          ▼
                  ┌───────────────┐
                  │  AST Parser   │
                  │    (Babel)    │
                  └───────┬───────┘
                          │
                          ▼
                ┌───────────────────┐
                │ Provider Analysis │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │ Priority Resolver │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │ Provider Rebuild  │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │  Code Generator   │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │ React Application │
                └───────────────────┘

📂 Project Structure

ForgeCLI/
│
├── src/
│   ├── cli/
│   │   └── commands/
│   │
│   ├── core/
│   │   ├── astModifier.ts
│   │   ├── rebuildProviders.ts
│   │   └── providerResolver.ts
│   │
│   ├── plugins/
│   │
│   ├── templates/
│   │
│   └── utils/
│       ├── logger.ts
│       └── error-handler.ts
│
├── templates/
│   └── react-app/
│
├── plugins/
│
├── tests/
│
├── package.json
├── tsconfig.json
└── README.md

The exact structure may evolve as ForgeCLI grows. The architecture is intentionally modular so new commands, plugins, and transformation strategies can be introduced without tightly coupling the core engine.

🔄 Example

Before ForgeCLI

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Run:

forge add auth
forge add theme

After ForgeCLI

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

import { AuthProvider } from "@/providers/AuthProvider";
import { ThemeProvider } from "@/providers/ThemeProvider";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <AuthProvider>
      <ThemeProvider>
        <App />
      </ThemeProvider>
    </AuthProvider>
  </React.StrictMode>
);

The developer does not need to manually construct or reorder the provider tree.

🧠 Design Principles

1. Architecture as Configuration

Application capabilities should be composable through configuration rather than manually maintained boilerplate.

Feature → Plugin → Configuration → Generated Architecture

2. AST Over Regex

ForgeCLI operates on the structure of the source code rather than blindly modifying strings.

Regex
  ↓
Text Matching
  ↓
Fragile Transformations

versus:

AST
  ↓
Structural Analysis
  ↓
Intentional Transformation
  ↓
Predictable Output

3. Rebuild Over Patch

ForgeCLI favors deterministic reconstruction of managed provider trees instead of accumulating fragile modifications.

Plugin State
     ↓
Resolve
     ↓
Rebuild
     ↓
Generate

4. Priority-Driven Composition

Plugins should not need to know about every other plugin.

Each plugin declares its own priority and ForgeCLI handles composition.

Plugin A ──┐
Plugin B ──┼──> Priority Resolver ──> Provider Tree
Plugin C ──┘

5. Idempotency

Running the same operation multiple times should produce the same architectural result.

forge add auth
forge add auth
forge add auth

        ↓

One AuthProvider
One Import
Predictable Output

🧪 Current Status

ForgeCLI is currently under active development.

The core architecture focuses on:

Plugin-driven feature composition
React provider management
Babel AST transformations
Priority-based provider resolution
Deterministic rebuilds
Idempotent CLI operations

APIs and plugin interfaces may evolve as the project develops.

🤝 Contributing

Contributions are welcome.

If you have an idea, improvement, or bug fix:

Open an issue
Discuss the proposed change
Fork the repository
Create a feature branch
Submit a pull request

For larger architectural changes, opening an issue first is recommended.

📜 License

ForgeCLI is released under the MIT License.

👨‍💻 Author

Shubham Srivastava

Building developer tools, full-stack applications, and AI-powered systems.

⚒️ Forge your React architecture.

_{Built for developers who want architecture to scale with their applications.}

Name		Name	Last commit message	Last commit date
bin		bin
plugins		plugins
src		src
templates/react-app		templates/react-app
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
forgecli-1.0.0.tgz		forgecli-1.0.0.tgz
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation