Skip to content

development.md

Latest commit

 

History

History
88 lines (72 loc) · 5.4 KB

development.md

File metadata and controls

88 lines (72 loc) · 5.4 KB
Raw
title Development

Development

Prerequisites

  • Node.js 20+
  • npm 10+ recommended for working on the DevForge repository
  • Use Node 20.19.0+ or 22.12.0+ when running generated frontend or extension runtime scenarios locally

Local Setup

npm install
npm run check
npx --yes @ali-dev11/devforge@latest doctor

Config-As-Code Workflow

npx --yes @ali-dev11/devforge@latest init --preset frontend-app --output ./my-app
npx --yes @ali-dev11/devforge@latest init --yes --save-config
npx --yes @ali-dev11/devforge@latest init --config ./devforge.config.json --output ./my-app
npx --yes @ali-dev11/devforge@latest upgrade
npx --yes @ali-dev11/devforge@latest add testing
  • --preset seeds the scaffold from a built-in preset name or a local preset JSON file so teams can standardize starting points.
  • --save-config writes the normalized project plan to devforge.config.json so the same scaffold can be replayed later.
  • --config runs the generator non-interactively from a saved plan while still letting --output or --name override the destination.
  • Config-driven runs pass through the same normalization and compatibility checks as interactive runs, so invalid hand-written combinations are still corrected or rejected with guidance.
  • devforge upgrade refreshes DevForge-managed docs, workflows, AI rules, deployment files, and core tooling surfaces while skipping files that no longer match the previous generated baseline.
  • devforge add <feature> updates an existing DevForge project by reading .devforge/project-plan.json and rewriting only the managed files for that feature.
  • Verified deployment targets now carry a normalized provider profile, so generated docs and workflows stay aligned on build commands, start commands, health checks, secrets, and expected environment variables.

Repository Commands

npm run dev -- --help
npm run lint
npm run typecheck
npm run test
npm run build
npm run check
npm run docs:changelog
npm run smoke
npm run smoke:packed
npm run runtime:matrix -- --scenario backend-hono --scenario cli-tool

Why Each Command Exists

  • npm run dev -- --help lets you exercise the CLI locally without publishing a package first.
  • npm run lint checks repository code-style and code-quality rules.
  • npm run typecheck catches TypeScript regressions before runtime.
  • npm run test runs focused regression tests for prompting, normalization, generator output, changelog rendering, and runtime-matrix coverage.
  • npm run build compiles the CLI to dist/, which mirrors what npm users receive.
  • npm run check is the primary contributor gate because it runs lint, types, tests, and build verification together.
  • npx --yes @ali-dev11/devforge@latest doctor checks the local machine for the tool and runtime prerequisites that commonly break first-run scaffolds.
  • npm run docs:changelog keeps the GitHub Pages changelog synchronized with CHANGELOG.md.
  • npm run smoke verifies a fast end-to-end scaffold run without interactive prompts.
  • npm run smoke:packed verifies the built npm tarball by installing the packed artifact into a temp directory and running the shipped CLI from there.
  • npm run runtime:matrix -- --scenario ... validates generated projects as products by installing, building, and checking runtime behavior for representative stacks.

Working On Generated Scaffolds

  • Prefer npm run smoke for quick CLI sanity checks.
  • Run npx --yes @ali-dev11/devforge@latest init --preflight-only when you want stack-aware readiness checks without writing a new project yet.
  • Use npx --yes @ali-dev11/devforge@latest init --preset frontend-app when validating built-in preset coverage or a local preset file path.
  • Use npx --yes @ali-dev11/devforge@latest init --save-config when you want an interactive run to become a reusable team preset later.
  • Use npx --yes @ali-dev11/devforge@latest init --config ./devforge.config.json --output ./my-app when validating reproducible scaffold output.
  • Use npx --yes @ali-dev11/devforge@latest upgrade when changing generated docs, workflows, deployment baselines, or other managed tooling surfaces.
  • When changing deployment targets, verify both the generated provider file and the follow-up workflow guidance because upgrade now removes stale managed provider files that still match a previous generated baseline.
  • Use npx --yes @ali-dev11/devforge@latest add testing, add docker, add github-actions, or add ai-rules when validating managed post-scaffold updates.
  • Use npm run runtime:matrix when changing templates, prompts, package-manager behavior, or generated runtime surfaces.
  • Use npm run smoke:packed when changing the package entrypoints, published files, CLI dispatch, or install-time behavior.
  • If you touch deployment generation, validate Render and Railway flows through npm run runtime:matrix or npm run smoke:packed, not just unit-level file snapshots.
  • If you touch microfrontend templates, validate the generated dev workflow, not just build output.
  • If you touch docs or release notes, rerun npm run docs:changelog.

Tooling Defaults

  • ESLint and Prettier are default-on in generated projects because they are broad quality baselines.
  • Husky and Commitlint are opt-in because local hook enforcement is not appropriate for every team or prototype.
  • Generated GitHub Actions, Docker, and heavier DevOps setup remain optional to avoid forcing unnecessary tooling into every scaffold.