⚒️ hexforge

Scaffold production-ready React and Next.js projects powered by Hexagonal Architecture — in seconds.

What is hexforge?

hexforge is a command-line scaffolding tool that generates fully structured projects and modules following Hexagonal Architecture (also known as Ports & Adapters). It supports both React + Vite and Next.js App Router workflows.

Each project generated by hexforge comes with:

• ✅ TypeScript — strict, out of the box
• 🏗️ Hexagonal Architecture — Domain, Infrastructure, Repository, Hooks, Store, Sections
• 🌐 i18n ready — built-in LanguageContext with es / en translations
• 🐻 Zustand — lightweight global state management
• 📅 date-fns — modern date utilities
• 🛣️ Routing — React Router (React) or App Router (Next.js)
• 🎨 Adaptive Styling — Tailwind CSS or scoped CSS Modules

Installation

npm install -g hexforge

Or use directly with npx without installing:

npx hexforge my-app

Commands

| Command | Description | |---|---| | hexforge [react/next] <name> | Create a new project. Defaults to react if omitted. | | hexforge module <ModuleName> | Add a new module. Auto-detects React/Next.js project environment. |

Global Options

| Option | Description | |---|---| | -v, --version | Print the current CLI version in a styled ASCII banner | | -h, --help | Display the formatted help menu with command usage and examples |

Note: hexforge module acts intelligently based on your current project root. It will safely abort if run outside a valid React or Next.js project to prevent stray files. You can also run npx hexforge [react/next] <name> directly.

React — Quick Start

Create a project

npx hexforge my-app

The CLI will ask:

🎨 Do you want to use Tailwind CSS? (y/n) [y]:

Then it will:

1. Scaffold a Vite + React + TypeScript project
2. Install React Router, Zustand, and date-fns
3. Generate the full hexagonal folder structure
4. Create all initial files from templates

cd my-app
npm run dev

Add a module

Run inside the project root:

hexforge module Product

This generates:

src/
  modules/
    product/
      domain/            product.ts
      infrastructure/    APIProductRepository.ts
      repository/        ProductRepository.ts
      hooks/             useProduct.ts
      store/             useProductStore.ts
      sections/          Product.tsx
                         Product.module.css  ← Auto-generated if Tailwind is skipped
      translations/      es.ts · en.ts · index.ts
      ProductViewFactory.tsx
  router/
    Router.tsx           ← /product route auto-injected ✅

Next.js — Quick Start

Create a project

npx hexforge next my-next-app

The CLI will ask:

🎨 Do you want to use Tailwind CSS? (y/n) [y]:

Then it will:

1. Scaffold a Next.js App Router + TypeScript project via create-next-app
2. Install Zustand and date-fns
3. Generate the full hexagonal folder structure
4. Overwrite app/page.tsx and app/layout.tsx with hexforge templates

cd my-next-app
npm run dev

Add a module

Run inside the project root:

hexforge module Product

This generates:

src/
  modules/
    product/
      domain/            product.ts
      infrastructure/    APIProductRepository.ts
      repository/        ProductRepository.ts
      hooks/             useProduct.ts
      store/             useProductStore.ts
      sections/          Product.tsx
                         Product.module.css       ← Auto-generated if Tailwind is skipped
      translations/      es.ts · en.ts · index.ts
      ProductViewFactory.tsx   ← includes 'use client'
  app/
    product/
      page.tsx           ← Next.js route /product ✅

Generated Project Structure

React + Vite

my-app/
  index.html                    ← meta generator: hexforge
  src/
    App.tsx
    main.tsx
    config/
      config.ts                 ← env-aware API base URL
    context/
      LanguageContext.tsx        ← i18n provider (es/en)
    helpers/
      fetch.ts                  ← typed fetch wrapper
    layouts/
      Layout.tsx                ← React Router <Outlet />
    router/
      Router.tsx                ← BrowserRouter + Routes
    utils/
      date.ts                   ← date-fns utilities
    modules/
      shared/
        types/
          response-wrapper.ts   ← generic API response type
      home/                     ← initial Home module
        domain/
        infrastructure/
        repository/
        hooks/
        store/
        sections/
        translations/
        HomeViewFactory.tsx

Next.js App Router

my-next-app/
  src/
    app/
      layout.tsx                ← root layout (meta: hexforge)
      page.tsx                  ← home page → HomeViewFactory
      globals.css
    config/
      config.ts
    context/
      LanguageContext.tsx        ← 'use client' + i18n provider
    helpers/
      fetch.ts
    utils/
      date.ts
    modules/
      shared/
        types/
          response-wrapper.ts
      home/                     ← initial Home module
        domain/
        infrastructure/
        repository/
        hooks/
        store/
        sections/
        translations/
        HomeViewFactory.tsx      ← 'use client' boundary

Hexagonal Architecture Overview

Each module follows a strict layer separation:

modules/<name>/
  domain/          → Pure TypeScript entity / domain model
  infrastructure/  → Concrete implementation of API calls
  repository/      → Interface (port) that infrastructure implements
  hooks/           → Business logic hook that consumes the repository
  store/           → Zustand slice for global state
  sections/        → React component (the "view")
  translations/    → i18n dictionary (es · en · index)
  <Name>ViewFactory.tsx → Composes LanguageProvider + Section

Data Flow

Section (View)
  ↓  uses
Hook (use<Name>)
  ↓  calls
Repository interface (<Name>Repository)
  ↓  implemented by
Infrastructure (API<Name>Repository)
  ↓  fetches from
External API / Backend

🎨 Adaptive Styling

When scaffolding via hexforge, the CLI will prompt you: 🎨 Do you want to use Tailwind CSS? (y/n).

Your choice determines how all future modules are styled:

• With Tailwind CSS: Views receive full-featured, standard Tailwind utility classes directly embedded within the tsx components for a modern, rapid UI configuration.
• Without Tailwind CSS: Views are cleanly segregated, automatically generating robust, scoped *.module.css modules and safely importing them.

Router Auto-Injection (React)

When you run hexforge module, the CLI automatically adds the import and route to Router.tsx using two anchor comments:

// @factory-imports — ⚠️ DO NOT REMOVE: used by hexforge module to auto-inject imports

{/* @factory-routes — ⚠️ DO NOT REMOVE: used by hexforge module to auto-inject routes */}

Warning: Do not remove these comments or the auto-injection will be skipped.

i18n Support

Every module ships with a translation system:

// modules/product/translations/es.ts
export const es = { title: 'Productos' };

// modules/product/translations/en.ts
export const en = { title: 'Products' };

And uses it in the section:

function Product() {
  const { t } = useLanguage();
  return <h1>{t('title')}</h1>;
}

Switch language programmatically:

const { setLanguage } = useLanguage();
setLanguage('en');

Requirements

| Tool | Version | |---|---| | Node.js | ≥ 18.0.0 | | npm | ≥ 9.0.0 |

Dependencies

hexforge itself only depends on two packages at runtime:

| Package | Purpose | |---|---| | ejs | Render .ejs templates to TypeScript/TSX files | | fs-extra | Enhanced file system operations (outputFile, ensureDir, pathExists) |

All other tools (Vite, Next.js, React Router, Zustand, Tailwind…) are installed into the generated project, not into hexforge itself.

Author

Jesús Mendoza Verduzco 📧 [email protected]

License

ISC © 2025 Jesús Mendoza Verduzco