webforge

A modular CLI tool for scaffolding and configuring web projects. Define your stack once, generate consistent projects in seconds.

Why webforge?

Tools like create-next-app or nest new scaffold a framework, but stop there. You still manually wire up ESLint, Prettier, testing, Docker, CI/CD, git hooks, and folder structure — every single time.

webforge generates a complete, production-ready project with your entire stack configured and working together, in one command. It's modular by design: each framework, tool, and infrastructure concern is an independent plugin that adapts to the rest of your choices.

Quick Start

# Install globally
npm install -g webforge

# Interactive mode — answer prompts to configure your project
webforge init

# Declarative mode — generate from a config file
webforge create .forgefile.yml

Features

• 3 frameworks — Next.js, React + Vite, NestJS
• Full tooling — ESLint (flat config), Prettier, Vitest, Jest, Husky, Commitlint, Playwright, Storybook
• Infrastructure — Docker (multi-stage builds), GitHub Actions CI/CD (with Vercel/Docker deploy), Prisma ORM, Turborepo
• TypeScript or JavaScript — Every framework module supports both language modes
• Declarative config — .forgefile.yml for reproducible, shareable project setups
• Presets — Save and reuse configurations across projects
• Modular architecture — Every technology is a self-contained plugin
• Context-aware — Modules adapt to each other (e.g., ESLint adds eslint-config-next when Next.js is selected)

Usage

Interactive Mode

webforge init

Walks you through a series of prompts:

1. Project name — validated for npm compatibility
2. Framework — Next.js, React + Vite, or NestJS (with framework-specific options like styling, language, App Router)
3. Tooling — Linter, formatter, unit testing, E2E testing, component development tools, git hooks
4. Infrastructure — Docker, ORM (Prisma), monorepo (Turborepo), CI/CD with optional deploy target

Declarative Mode

Create a .forgefile.yml:

name: my-app
framework: nextjs
language: typescript

tooling:
  linter: eslint
  formatter: prettier
  testing: vitest
  e2e: playwright
  componentDev: storybook
  git:
    husky: true
    commitlint: true

infrastructure:
  docker: true
  turborepo: true
  prisma:
    provider: postgresql
  ci:
    provider: github-actions
    steps: [lint, test, build]
    deployTarget: vercel

Then run:

webforge create .forgefile.yml

Presets

webforge ships with built-in presets you can use directly:

webforge create src/presets/default-nextjs.yml
webforge create src/presets/default-react.yml
webforge create src/presets/default-nestjs.yml
webforge create src/presets/minimal.yml

Supported Modules

Frameworks

| Module | ID | Description | | --- | --- | --- | | Next.js | nextjs | Full-stack React with SSR/SSG, App Router, Tailwind/CSS Modules/Styled Components | | React + Vite | react-vite | Fast React SPA with Vite, optional React Router | | NestJS | nestjs | Backend API with Prisma/TypeORM, optional Swagger docs |

Tooling

| Module | ID | Description | | --- | --- | --- | | ESLint | eslint | Flat config, auto-adapts to selected framework | | Prettier | prettier | Code formatter with Tailwind plugin support | | Vitest | vitest | Fast unit testing (recommended for React/Next.js) | | Jest | jest | Testing framework (recommended for NestJS) | | Husky | husky | Git hooks with lint-staged integration | | Commitlint | commitlint | Conventional commit message enforcement | | Playwright | playwright | End-to-end testing with configurable browser (Chromium/Firefox/WebKit) | | Storybook | storybook | Component development environment, adapts to Next.js or React+Vite |

Infrastructure

| Module | ID | Description | | --- | --- | --- | | Docker | docker | Multi-stage Dockerfile + Compose, adapted per framework | | GitHub Actions | github-actions | CI pipeline with optional Vercel or Docker deploy job | | Prisma | prisma | ORM with schema, migrations, db scripts, and singleton client | | Turborepo | turborepo | Monorepo task runner wrapping build/dev/lint/test scripts |

Architecture

webforge is built around a plugin system where each technology is a self-contained module:

src/
├── cli/              # Commands and interactive prompts
├── core/             # Engine, resolver, loader, template system
│   ├── engine.ts     # Orchestrates the generation pipeline
│   ├── resolver.ts   # Dependency graph and conflict detection
│   ├── loader.ts     # Auto-discovers modules at startup
│   └── template.ts   # Handlebars-based file generation
├── modules/          # All technology plugins (15 modules)
│   ├── frameworks/   # nextjs, react-vite, nestjs
│   ├── tooling/      # eslint, prettier, vitest, jest, husky, commitlint, playwright, storybook
│   └── infra/        # docker, github-actions, prisma, turborepo
└── presets/          # Ready-to-use .forgefile.yml configurations

Each module consists of two files:

• module.yml — Declares metadata, capabilities, conflicts, and configurable options
• index.ts — Implements the WebforgeModule interface (generate files, declare dependencies, lifecycle hooks)

The core never hardcodes any technology. Adding support for a new framework or tool means creating a new module folder — zero changes to existing code.

See CONTRIBUTING.md for a guide on creating modules.

Forgefile Reference

The .forgefile.yml schema supports the following fields:

| Field | Type | Required | Description | | --- | --- | --- | --- | | name | string | Yes | Project name (lowercase, hyphens/dots/underscores) | | framework | string | Yes | nextjs, react-vite, or nestjs | | language | string | No | typescript (default) or javascript | | tooling.linter | string | No | eslint | | tooling.formatter | string | No | prettier | | tooling.testing | string | No | vitest or jest | | tooling.e2e | string | No | playwright | | tooling.e2eOptions.browser | string | No | chromium (default), firefox, or webkit | | tooling.componentDev | string | No | storybook | | tooling.git.husky | boolean | No | Enable git hooks | | tooling.git.commitlint | boolean | No | Enable conventional commits | | infrastructure.docker | boolean | No | Generate Dockerfile + Compose | | infrastructure.turborepo | boolean | No | Enable Turborepo task runner | | infrastructure.prisma.provider | string | No | postgresql (default), mysql, sqlite, or mongodb | | infrastructure.ci.provider | string | No | github-actions | | infrastructure.ci.steps | string[] | No | ["lint", "test", "build"] | | infrastructure.ci.deployTarget | string | No | none (default), vercel, or docker |

A JSON Schema is available at .forgefile.schema.json for IDE autocompletion.

Development

# Clone the repo
git clone https://github.com/vincbct34/webforge.git
cd webforge

# Install dependencies
npm install

# Run in dev mode
npx tsx src/cli/index.ts init

# Run tests
npm test

# Type check
npm run typecheck

# Build for distribution
npm run build

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to contribute, create new modules, and submit pull requests.

License

MIT © Vincent Bichat