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.
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
--jsonoutput.
Installation & Execution #
Fogoe requires Node.js >= 18.0.0. You can run Fogoe on-demand using any major package manager without global installation:
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:
2. Single-Command Headless Flag Mode
Pass explicit flags to bypass interactive prompts entirely—ideal for CI/CD pipelines, Dockerfiles, and custom scripts:
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-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.
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.
--ai with explicit CLI flags. Explicit flags take priority:
fogoe create billing-svc --ai "TypeScript API with Drizzle and JWT" --framework express
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.
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:
CI/CD & Docker Integration Recipe
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.
Generated Artifacts Breakdown
Running the command creates 3 synchronized files tailored to your project's active framework and database:
Individual Component Generators #
When you don't need a full CRUD slice, scaffold standalone MVC parts instantly:
Supported Web Frameworks
Fogoe provides feature parity across four modern HTTP frameworks.
Fastify
High PerfSchema-based validation, lightning-fast JSON serialization, and full async lifecycle hooks. Includes @fastify/cors.
Express
Battle-TestedThe industry standard with immense middleware ecosystem, typed routes, and robust error handlers.
Hono
Edge & NodeUltra-fast web framework optimized for Node.js, Bun, Cloudflare Workers, and serverless environments via @hono/node-server.
Koa
ExpressiveModern 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 watchfor 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:
2. Layered MVC Architecture Pattern
Enterprise-ready separation of concerns with dedicated lifecycle boundaries:
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 usingbcrypt.--hashing argon2: Winner of the Password Hashing Competition (memory-hard).--hashing crypto: Zero-dependency hashing powered by Node's nativecrypto.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
--testBlazing fast unit & integration testing suite. Scaffolds sample health check tests and adds npm test to package.json.
ESLint + Prettier
--lintPreconfigured linting rules with TypeScript parser and Prettier configuration files. Adds npm run lint and npm run format.
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 alpineUltra-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 debianOfficial 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 ubuntuCanonical 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 distrolessMaximum 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(ornonroot:nonrooton Distroless) for container security. - Native Healthchecks: Automatically injects
HEALTHCHECK --interval=30s --timeout=3sprobes 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-alpinewithpg_isreadyhealthcheck probe and named volumepostgres_data. - MongoDB:
mongo:7-jammywithmongoshping probe and named volumemongo_data. - MySQL:
mysql:8withmysqladmin pingprobe and named volumemysql_data. - Redis:
redis:7-alpinewithredis-cli pingprobe and named volumeredis_data.
- PostgreSQL:
- Synchronized Boot Dependencies: The application service uses
condition: service_healthyon its dependencies, ensuring database initialization completes before the Node server starts. - Environment & Networking: Injects variables from
.envand orchestrates services on a dedicated private bridge network (app-network).
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:
2. Inspect Container Status & Health Probes
Check running containers and verify that health checks report healthy:
3. Stream Application Logs
Follow real-time HTTP server logs and database connection queries:
4. Rebuild After Dependency Changes
When modifying package.json or adding native plugins, rebuild the container image:
5. Stop and Clean Up Services
Gracefully stops containers while preserving database volume data:
Modular Plugin Ecosystem
Extend any existing Fogoe application on demand using fogoe add <plugin>.
Redis
fogoe add redisConfigures ioredis with connection pooling, reconnect retry logic, and environment variable configuration.
Zod Validation
fogoe add zodInjects TypeScript-first request validation middleware for body payloads and query parameters.
Nodemailer
fogoe add mailerConfigures SMTP transactional email sending helpers with environment credentials.
Stripe SDK
fogoe add stripeInitializes Stripe payment processing SDK with webhook signature verification.
OpenAPI / Swagger
fogoe add swaggerMounts an interactive API documentation explorer at /api-docs using swagger-ui-express.
Socket.io
fogoe add socketSets up real-time bi-directional WebSocket event communication server.
GitHub Actions CI/CD
fogoe add ciScaffolds complete .github/workflows/ci.yml configured for lint, test, build, Docker checks, and cloud deployments.
Docker Multi-Distribution
fogoe dockerGenerates 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 composeGenerates 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.
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 k8sAutomated 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 docsAutomated 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.jsonandopenapi.yamlfor external developer portals.
3. GitLab CI & Bitbucket Pipelines
fogoe add gitlab-ciInstant scaffolding of continuous integration and deployment pipelines for alternative git platforms (GitLab CI and Bitbucket).
- Generates
.gitlab-ci.ymlandbitbucket-pipelines.ymltailored 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
.envpresence 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.