Getting Started

Fogoe Documentation

Fogoe is a high-performance backend scaffolding engine for Node.js and TypeScript. It generates clean, production-grade backends in seconds across Express, Fastify, Hono, and Koa without runtime bloat or restrictive abstractions.

Pure Disk-Based Template Architecture
Fogoe does not embed massive template strings into generator source files. Every template is maintained as real, valid on-disk code files, preventing escaping bugs and guaranteeing syntax accuracy.

Core Engineering Philosophy #

  • Zero Friction: Go from an idea to a fully wired, compiling, and running HTTP API in under 30 seconds.
  • Zero Lock-in: You own 100% of the generated codebase. No custom runtime wrappers, meta-framework dependencies, or proprietary CLIs are required in production.
  • Modern Standards: Built natively around strict TypeScript 5.x, NodeNext module resolution, ES Modules ("type": "module"), and industry-standard ORMs like Drizzle and Prisma.
  • Agent & CI Native: Built from the ground up to support autonomous coding agents (Claude Code, Cursor, Copilot, Antigravity) with non-interactive flags and machine-readable --json output.

Installation & Execution #

Fogoe requires Node.js >= 18.0.0. You can run Fogoe on-demand using any major package manager without global installation:

bash
$ npx fogoe
bash
$ pnpm dlx fogoe
bash
$ bunx fogoe
bash
$ yarn dlx fogoe
bash
$ npm install -g fogoe $ fogoe --version

Quick Start Guide #

Fogoe offers two primary workflows: interactive terminal wizard for humans, and headless CLI flags for automation and coding agents.

1. Interactive Terminal Wizard (Clack TUI)

Running npx fogoe create <name> launches an interactive step-by-step wizard powered by @clack/prompts:

Terminal Wizard Flow
$ npx fogoe create payment-api ◇ Welcome to Fogoe v1.2.0 │ ◇ Select web framework › Fastify (High-performance API) ◇ Select language › TypeScript (Strict NodeNext ESM) ◇ Architecture pattern › MVC (Layered routes/controllers/models) ◇ Database / ORM › Drizzle ORM (PostgreSQL) ◇ Authentication › JWT Bearer (authMiddleware) ◇ Initialize Git repo? › Yes (with stack-tailored .gitignore) ◇ Install dependencies?› Yes (using detected npm/pnpm) │ └ ✔ Project scaffolded successfully in 38ms!

2. Single-Command Headless Flag Mode

Pass explicit flags to bypass interactive prompts entirely—ideal for CI/CD pipelines, Dockerfiles, and custom scripts:

bash
$ fogoe create store-api \ --framework fastify \ --lang ts \ --db drizzle \ --auth jwt \ --git \ --install \ -y
CLI Suite

CLI Commands Reference

Fogoe includes a complete toolchain for project initialization, component generation, plugin configuration, and Git repository synchronization.

Command Arguments / Flags Description
fogoe [name] Optional target directory name Launches the interactive TUI wizard to initialize a project.
fogoe create <name> [--framework] [--lang] [--db] [--auth] [--git] [--install] [-y] Scaffolds a new project with optional headless CLI flags.
fogoe create <name> --ai "..." Natural language description AI-assisted scaffolding: compiles plain English prompts into stack parameters.
fogoe create <name> --json --non-interactive Emits machine-readable JSON output to stdout for coding agents and CI runners.
fogoe g crud <name> Entity name (e.g. product, user) Generates a complete vertical slice: Model, Controller, and REST Route endpoints.
fogoe g route <name> Route name Generates a typed API route in src/routes/.
fogoe g controller <name> Controller name Generates a request handler controller in src/controllers/.
fogoe g model <name> Model name Generates a database schema model matching the active ORM / database driver.
fogoe add [plugin] ci, docker, compose, redis, zod, mailer, stripe, ratelimit, swagger, socket Installs and integrates modular backend capabilities or DevOps pipelines into an existing project.
fogoe docker [--docker-os <os>] Generates production multi-distribution Dockerfile (Alpine, Debian Slim, Ubuntu, Distroless) and .dockerignore.
fogoe compose — Generates stack-aware docker-compose.yml tailored to your database (PostgreSQL, MongoDB, MySQL) and Redis cache.
fogoe ci [--deploy <target>] Generates automated GitHub Actions workflow (.github/workflows/ci.yml) tailored to your tech stack.
fogoe status — Displays current project runtime, module system, ORM, and Git sync status.
fogoe update — Upgrades all project dependencies to their latest compatible versions.
fogoe init — Initializes Git repository, sets branch to main, and connects remote origin.
fogoe push "<msg>" Commit message Stages all files, commits with provided message, and pushes to remote repository.

Complete CLI Flags Matrix #

All options supported by fogoe create:

Flag Short Accepted Values Default Notes
--framework -f fastify, express, hono, koa express Target HTTP web framework.
--lang -l ts, typescript, js, javascript javascript Language environment. TypeScript generates NodeNext ESM.
--type -t esm, module, cjs, commonjs module (TS) / commonjs (JS) Module system used in package.json.
--arch -a mvc, minimal minimal Architecture pattern: Layered MVC or Single-File Minimal.
--db -d drizzle, prisma, postgresql, mongodb, sqlite, mysql, none none Database driver or ORM integration.
--auth — jwt, none none JWT Bearer authentication middleware with header inspection.
--hashing — bcrypt, argon2, crypto bcrypt Password hashing algorithm helper placed in src/utils/hashing.
--test / --no-test — Boolean false Configures Vitest testing suite and creates sample health tests.
--lint / --no-lint — Boolean false Configures ESLint and Prettier with strict styling rules.
--install / --no-install -i Boolean false Automatically runs package manager installation after writing files.
--pm — npm, pnpm, bun, yarn npm Preferred package manager for installation and lockfiles.
--git / --no-git -g Boolean false Initializes local Git repository and writes tailored .gitignore.
--commit / --no-commit — Boolean or commit message string false Creates initial Git commit immediately after scaffolding.
--github — Boolean, GitHub URL, or owner/repo false Connects to GitHub remote or uses gh repo create.
--private / --public — Boolean false Sets GitHub repository visibility (public by default).
--ci / --no-ci — Boolean false Generates stack-aware GitHub Actions CI/CD pipeline (.github/workflows/ci.yml).
--docker / --no-docker — Boolean false Generates production multi-stage Dockerfile and .dockerignore.
--docker-os --os alpine, debian, ubuntu, distroless alpine Sets container Linux base distribution (Alpine, Debian Slim, Ubuntu, Distroless).
--compose / --no-compose — Boolean false Generates stack-tailored docker-compose.yml for application, database, and Redis.
--deploy — dockerhub, fly, railway, render, none none Configures automated deployment stage with required repository secrets.
--ai — String prompt — Natural-language requirement compilation.
--json — Boolean false Outputs machine-readable JSON structure on stdout.
--non-interactive / --yes -y Boolean false Bypasses all stdin prompts using flags or defaults.
AI Intelligence

AI-Assisted Scaffolding Engine

Fogoe includes a deterministic requirement compiler that translates natural language prompts into verified CLI parameters—bypassing fuzzy code generation and hallucinations with 100% template precision.

AI Prompt Command
$ fogoe create store-api \ --ai "Fastify e-commerce API with PostgreSQL, Drizzle ORM, and JWT authentication"

How Fogoe's AI Compiler Operates

Unlike generic LLM generators that attempt to write JavaScript code from scratch (frequently introducing broken imports and syntax bugs), Fogoe parses your natural language prompt against verified internal vocabulary models:

  • Framework Extraction: Detects mentions of Fastify, Express, Hono, Koa, or synonyms (e.g., "ultra-high performance" → Fastify, "edge service" → Hono).
  • Database & ORM Mapping: Maps terms like "drizzle", "prisma", "postgres", "mongo", or "sqlite" to exact driver combinations and schemas.
  • Auth & Security: Automatically activates JWT Bearer middleware when keywords like "jwt", "auth", "tokens", or "secure login" appear.
  • Architecture Selection: Chooses MVC when databases or routes are specified, or Minimal for microservices and single-endpoint servers.
Explicit Flag Overrides
You can combine --ai with explicit CLI flags. Explicit flags take priority:

fogoe create billing-svc --ai "TypeScript API with Drizzle and JWT" --framework express
Automation

Coding Agents & CI Automation

Zero prompt blocking. Pass --json and --non-interactive to pipe clean, machine-readable JSON directly into Claude Code, Cursor, Copilot, Antigravity, and CI/CD runners.

bash
$ fogoe create auth-service \ --framework fastify \ --lang ts \ --db postgresql \ --auth jwt \ --non-interactive \ --json

Structured JSON Output Schema

When --json is passed, Fogoe guarantees that only valid JSON is written to stdout. Informational logs and ASCII art are suppressed:

stdout (JSON)
{ "success": true, "projectName": "auth-service", "targetDir": "/workspace/auth-service", "config": { "framework": "fastify", "language": "ts", "architecture": "mvc", "database": "postgresql", "auth": "jwt", "git": true, "install": true }, "stats": { "filesWritten": 16, "durationMs": 38 } }

CI/CD & Docker Integration Recipe

GitHub Actions Workflow Step
- name: Scaffold microservice backend run: | npx fogoe create test-api \ --framework fastify \ --lang ts \ --db sqlite \ --auth jwt \ --install \ --non-interactive
Code Generation

Full CRUD Vertical Slice Generator

fogoe g crud <name> writes production-ready Models, Controllers, and REST Routes in a single atomic step. Pre-wired with standard HTTP verbs, status codes, and type safety.

bash
$ fogoe g crud product

Generated Artifacts Breakdown

Running the command creates 3 synchronized files tailored to your project's active framework and database:

src/routes/product.routes.ts
import { Router } from "express"; import * as productController from "../controllers/product.controller.js"; const router = Router(); router.get("/", productController.listProducts); router.get("/:id", productController.getProductById); router.post("/", productController.createProduct); router.put("/:id", productController.updateProduct); router.delete("/:id", productController.deleteProduct); export default router;
src/controllers/product.controller.ts
import { Request, Response } from "express"; import * as ProductModel from "../models/product.model.js"; export const listProducts = async (req: Request, res: Response) => { try { const items = await ProductModel.findAll(); res.json(items); } catch (err) { res.status(500).json({ error: "Failed to retrieve products" }); } }; export const getProductById = async (req: Request, res: Response) => { const item = await ProductModel.findById(req.params.id); if (!item) return res.status(404).json({ error: "Product not found" }); res.json(item); }; export const createProduct = async (req: Request, res: Response) => { const created = await ProductModel.create(req.body); res.status(201).json(created); };
src/models/product.model.ts
export interface Product { id: string; name: string; price: number; createdAt: Date; } export const findAll = async (): Promise<Product[]> => { // Integrated query using active ORM (Drizzle, Prisma, or native driver) return []; }; export const findById = async (id: string): Promise<Product | null> => { return null; }; export const create = async (data: Partial<Product>): Promise<Product> => { return { id: "p_1", name: data.name || "", price: data.price || 0, createdAt: new Date() }; };

Individual Component Generators #

When you don't need a full CRUD slice, scaffold standalone MVC parts instantly:

bash
# Generate a typed route $ fogoe generate route auth # -> src/routes/auth.routes.ts # Generate a controller handler $ fogoe generate controller auth # -> src/controllers/auth.controller.ts # Generate a database model $ fogoe generate model user # -> src/models/user.model.ts
Runtimes

Supported Web Frameworks

Fogoe provides feature parity across four modern HTTP frameworks.

Fastify

High Perf

Schema-based validation, lightning-fast JSON serialization, and full async lifecycle hooks. Includes @fastify/cors.

Express

Battle-Tested

The industry standard with immense middleware ecosystem, typed routes, and robust error handlers.

Hono

Edge & Node

Ultra-fast web framework optimized for Node.js, Bun, Cloudflare Workers, and serverless environments via @hono/node-server.

Koa

Expressive

Modern async middleware cascading powered by native promises with zero built-in middleware bloat.

Language & Module System Support #

TypeScript 5.x First

Fogoe configures TypeScript with optimal defaults targeting ES2022:

  • "module": "NodeNext" and "moduleResolution": "NodeNext" for native Node.js ES Modules.
  • Strict type-checking enabled ("strict": true).
  • Development powered by tsx watch for instant reload without build steps.
  • Clean path aliases configured for MVC architectures:
    • @routes/* → src/routes/*
    • @controllers/* → src/controllers/*
    • @models/* → src/models/*
    • @middlewares/* → src/middlewares/*
    • @config/* → src/config/*

JavaScript (ESM & CommonJS)

Full support for modern ES Modules (import / export) with "type": "module" in package.json, or classic CommonJS (require / module.exports).

Architecture Blueprints #

1. Minimal Architecture Pattern

Single entry point with health check route. Best for microservices, lambdas, and single-file prototypes:

Directory Tree
my-api/ ├── src/ │ └── server.ts ├── .env ├── .gitignore ├── package.json └── tsconfig.json

2. Layered MVC Architecture Pattern

Enterprise-ready separation of concerns with dedicated lifecycle boundaries:

Directory Tree
my-api/ ├── src/ │ ├── server.ts # Server bootstrap & port listening │ ├── app.ts # Middleware registration & route mounting │ ├── config/ │ │ ├── env.ts # Validated environment variables │ │ └── db.ts # Database pool & connection lifecycle │ ├── controllers/ │ │ └── home.controller.ts │ ├── routes/ │ │ └── home.routes.ts │ ├── models/ │ │ └── home.model.ts │ ├── middlewares/ │ │ └── authMiddleware.ts # JWT Bearer token inspection │ └── utils/ │ └── hashing.ts # Password hashing helpers ├── drizzle.config.ts # (If Drizzle ORM selected) ├── prisma/schema.prisma # (If Prisma ORM selected) ├── .env ├── .gitignore ├── package.json └── tsconfig.json
Data Layer

Databases & ORM Drivers

Fogoe establishes connection pooling, client singletons, and schemas ready for immediate querying.

Provider Driver / Package Scaffolded Client Setup
Drizzle ORM drizzle-orm + pg Includes drizzle.config.ts, PostgreSQL client pool, and schema migrations script.
Prisma ORM @prisma/client + prisma Generates prisma/schema.prisma, PrismaClient singleton, and DB connection checks.
PostgreSQL pg High-performance new Pool() connection pool with graceful error handling.
MongoDB mongoose Mongoose client with connection events and auto-reconnect logic.
SQLite better-sqlite3 Synchronous, zero-config embedded SQLite database file.
MySQL mysql2/promise Promise-based connection pool with parameterized query helpers.

Authentication & Security #

Production JWT Bearer Middleware

When --auth jwt is enabled, Fogoe generates an authMiddleware that inspects incoming Authorization: Bearer <token> headers, verifies signatures with process.env.JWT_SECRET, attaches the decoded payload to the request context, and returns standard HTTP 401 / 403 responses on failure.

Password Hashing

Includes a pre-configured hashing utility in src/utils/hashing:

  • --hashing bcrypt: Industry standard using bcrypt.
  • --hashing argon2: Winner of the Password Hashing Competition (memory-hard).
  • --hashing crypto: Zero-dependency hashing powered by Node's native crypto.scrypt.

Git & GitHub Automation #

Fogoe automates the entire repository lifecycle:

  • Stack-Tailored .gitignore: Automatically excludes .env, node_modules/, dist/, SQLite database files (*.db, *.sqlite), and OS artifacts.
  • Automated Initial Commit (--commit): Stages all scaffolded files and writes an initial git commit.
  • Remote GitHub Setup (--github, --private): Connects to existing remote repositories or provisions new ones via GitHub CLI (gh repo create).

Testing & Code Quality #

Vitest

--test

Blazing fast unit & integration testing suite. Scaffolds sample health check tests and adds npm test to package.json.

ESLint + Prettier

--lint

Preconfigured linting rules with TypeScript parser and Prettier configuration files. Adds npm run lint and npm run format.

DevOps Suite v1.2.0

Docker & Container Orchestration

Fogoe provides automated, security-hardened containerization pipelines. Generate production-ready multi-stage Dockerfiles across 4 distinct Linux distributions, and scaffold stack-tailored Docker Compose environments with synchronized database healthchecks.

Multi-Distribution Dockerfiles (fogoe docker) #

Scaffold multi-stage container assets on demand with fogoe docker or by passing --docker during project creation. Fogoe supports 4 distinct base Linux distributions via --docker-os <distribution>:

Alpine Linux (Default)

--docker-os alpine

Ultra-compact musl-based container image. Delivers minimal footprint (~150MB image size) ideal for cloud deployments, serverless containers, and low-latency transfer times.

Debian Bookworm Slim

--docker-os debian

Official glibc runtime baseline. Recommended when working with native C/C++ bindings (such as bcrypt, better-sqlite3, canvas, or Sharp) to ensure flawless pre-compiled binary execution.

Ubuntu Noble

--docker-os ubuntu

Canonical LTS enterprise environment based on Ubuntu 24.04 Noble Numbat. Compatible with enterprise compliance baselines, system packages, and proprietary cloud dependencies.

Google Distroless

--docker-os distroless

Maximum security posture. Distroless containers contain only your application runtime without package managers, shells, or auxiliary utilities, dramatically shrinking the CVE attack surface.

Production Hardening & Development Hot Reloading

Fogoe's Docker generator produces both a production Dockerfile and a live development container Dockerfile.dev:

  • Multi-Stage Caching: Separates dependency installation, TypeScript compilation, and runtime packaging into isolated cache layers for lightning-fast incremental builds.
  • Unprivileged Non-Root Execution: Production images drop root permissions and execute as appuser (or nonroot:nonroot on Distroless) for container security.
  • Native Healthchecks: Automatically injects HEALTHCHECK --interval=30s --timeout=3s probes to monitor the application endpoint.
  • Local Hot Reloading (Dockerfile.dev): Leverages volume mounts to enable source code synchronization with active package manager dev scripts (npm run dev, pnpm run dev, bun run dev).

Stack-Aware Docker Compose (fogoe compose) #

Run fogoe compose in any existing Fogoe project (or pass --compose to fogoe create). Fogoe inspects your project metadata, database drivers, ORM configuration, and cache services to generate a customized docker-compose.yml:

  • Database Engine Provisioning: Configures official Docker images matching your project:
    • PostgreSQL: postgres:16-alpine with pg_isready healthcheck probe and named volume postgres_data.
    • MongoDB: mongo:7-jammy with mongosh ping probe and named volume mongo_data.
    • MySQL: mysql:8 with mysqladmin ping probe and named volume mysql_data.
    • Redis: redis:7-alpine with redis-cli ping probe and named volume redis_data.
  • Synchronized Boot Dependencies: The application service uses condition: service_healthy on its dependencies, ensuring database initialization completes before the Node server starts.
  • Environment & Networking: Injects variables from .env and orchestrates services on a dedicated private bridge network (app-network).
Separation of Concerns: Environment Scaffolding vs. Container Runtime
Fogoe generates and configures your container architecture, but intentionally does not usurp your Docker daemon. Developers retain full ownership and execute standard Docker commands to manage their runtime environments.

Developer Runtime Workflow #

Once Fogoe has generated your Docker and Compose configurations, run your stack using standard Docker CLI commands:

1. Launch Services in Detached Mode

Starts your application and all database/cache dependencies in the background:

bash
$ docker compose up -d

2. Inspect Container Status & Health Probes

Check running containers and verify that health checks report healthy:

bash
$ docker compose ps

3. Stream Application Logs

Follow real-time HTTP server logs and database connection queries:

bash
$ docker compose logs -f app

4. Rebuild After Dependency Changes

When modifying package.json or adding native plugins, rebuild the container image:

bash
$ docker compose up -d --build

5. Stop and Clean Up Services

Gracefully stops containers while preserving database volume data:

bash
$ docker compose down
Extensions

Modular Plugin Ecosystem

Extend any existing Fogoe application on demand using fogoe add <plugin>.

Redis

fogoe add redis

Configures ioredis with connection pooling, reconnect retry logic, and environment variable configuration.

Zod Validation

fogoe add zod

Injects TypeScript-first request validation middleware for body payloads and query parameters.

Nodemailer

fogoe add mailer

Configures SMTP transactional email sending helpers with environment credentials.

Stripe SDK

fogoe add stripe

Initializes Stripe payment processing SDK with webhook signature verification.

OpenAPI / Swagger

fogoe add swagger

Mounts an interactive API documentation explorer at /api-docs using swagger-ui-express.

Socket.io

fogoe add socket

Sets up real-time bi-directional WebSocket event communication server.

GitHub Actions CI/CD

fogoe add ci

Scaffolds complete .github/workflows/ci.yml configured for lint, test, build, Docker checks, and cloud deployments.

Docker Multi-Distribution

fogoe docker

Generates production multi-stage Dockerfile, development container (Dockerfile.dev), and .dockerignore. Supports Alpine Linux, Debian Slim, Ubuntu, and Google Distroless with unprivileged non-root execution and healthcheck probes.

Docker Compose Multi-Container

fogoe compose

Generates complete docker-compose.yml tailored to your project. Orchestrates PostgreSQL (16-alpine), MongoDB (7-jammy), MySQL (8), or Redis (7-alpine) with persistent named volumes, isolated bridge network, and synchronized healthcheck boot probes.

Roadmap

Upcoming Features & Roadmap

Fogoe is continuously evolving. Here is a look at what is actively planned for upcoming releases to further streamline backend development, containerization, and deployment.

1. Kubernetes Manifests & Helm Charts

fogoe add k8s

Automated generation of production-ready Kubernetes deployment manifests, service definitions, ConfigMaps, and Helm charts tailored to Fogoe backends.

  • Zero-friction Deployment, Service, and Ingress YAML definitions with resource requests and limits.
  • Horizontal Pod Autoscaler (HPA) and rolling update configurations.
  • SealedSecrets / ExternalSecrets integration for safe credential injection.

2. API Documentation Generator

fogoe g docs

Automated compilation of OpenAPI / Swagger schemas directly from your route definitions and validation layers.

  • Automatic schema derivation from Zod schemas, TypeBox types, and controllers.
  • Generates interactive Swagger UI explorer mounted at /api-docs.
  • Exports static openapi.json and openapi.yaml for external developer portals.

3. GitLab CI & Bitbucket Pipelines

fogoe add gitlab-ci

Instant scaffolding of continuous integration and deployment pipelines for alternative git platforms (GitLab CI and Bitbucket).

  • Generates .gitlab-ci.yml and bitbucket-pipelines.yml tailored to your package manager.
  • Automated multi-stage test, lint, and build jobs across runner environments.
  • Container registry login and cloud deployment triggers.

4. Project Doctor

fogoe doctor [--fix]

Intelligent diagnostics suite to verify environment health, dependency consistency, and configuration integrity.

  • Audits Node.js version compatibility, missing lockfiles, and broken path aliases.
  • Validates .env presence against schema requirements.
  • fogoe doctor --fix: Automatically repairs detected discrepancies and missing scripts.

Troubleshooting & FAQ #

Q: Do I need to install Fogoe globally?

No. You can run Fogoe directly on demand with npx fogoe, pnpm dlx fogoe, bunx fogoe, or yarn dlx fogoe.

Q: Does Fogoe run docker compose up for me?

No. Fogoe is an environment scaffold and code generator. It crafts production-grade Dockerfile and docker-compose.yml assets tailored to your stack, but leaves container runtime lifecycle (such as docker compose up -d) under developer control.

Q: How does Fogoe handle pnpm build script approvals for native C++ modules?

Fogoe automatically passes --config.dangerouslyAllowAllBuilds=true during pnpm installations and provides multi-tier fallback to npm, preventing [ERR_PNPM_IGNORED_BUILDS] errors when installing packages with native C++ compilation steps (such as better-sqlite3 and bcrypt).

Q: Why does Fogoe use on-disk templates instead of embedded template strings?

Embedded string templates often suffer from syntax errors, difficult formatting, and escaping issues. Fogoe keeps pure, syntax-checked template files on disk, ensuring atomic and deterministic file generation every time.

Q: How do I run my generated project?

Navigate to your project directory and run npm run dev for hot-reloading development or npm run build && npm start for production builds.

Embedded string templates often suffer from syntax errors, difficult formatting, and escaping issues. Fogoe keeps pure, syntax-checked template files on disk, ensuring atomic and deterministic file generation every time.

Q: How do I run my generated project?

Navigate to your project directory and run npm run dev for hot-reloading development or npm run build && npm start for production builds.