devforge-scaffold 0.1.1

Generate opinionated starter projects for Flutter, Django and Next.js.

DevForge

A CLI tool that generates opinionated starter projects for Flutter, Django and Next.js.

Built with Typer (CLI framework) and Rich (terminal UI).

Status: all three generators — Flutter, Django and Next.js — are fully working.

Usage

devforge version                # version + runtime info (also: devforge --version / -V)
devforge doctor                 # check required tooling and templates
devforge flutter my_app         # scaffold a Flutter project
devforge django my_site         # scaffold a Django project
devforge next my-web            # scaffold a Next.js project
devforge --help                 # help for the app or any command (-h works too)
devforge -v <command>           # enable debug logging

Generating into an existing folder is fine as long as it's empty — including a freshly cloned empty GitHub repository (its .git is preserved and DevForge then skips git init, leaving commits to you). All generators accept --no-git to skip repository initialisation explicitly.

devforge flutter

devforge flutter my_app \
  --org com.mycompany \          # Android/iOS bundle-id organisation (reverse-DNS)
  --app-name "My App" \          # display name (default: project name title-cased)
  --description "..." \          # pubspec description
  --api-url https://api.my.dev \ # baked into lib/core/constants/api_routes.dart
  -o ~/projects                  # parent directory (default: current directory)

What it does: checks the Flutter SDK → runs flutter create (correct platform folders for your --org) → replaces lib/, assets/, test/, pubspec.yaml and analysis_options.yaml with the DevForge template and substitutes its tokens → sets the app display name across android/ios/macos/web → adds the INTERNET permission to the main Android manifest (release builds need it for networking) → flutter pub get → regenerates branded launcher icons and splash screens from assets/images/logo.png (flutter_launcher_icons / flutter_native_splash) → git init + initial commit. The generated project is flutter analyze-clean.

The template intentionally has no android//ios/ folders — platform folders always come fresh from flutter create, so they never drift out of date with new Flutter releases. See templates/flutter_starter/TEMPLATE_REPORT.md.

devforge django

devforge django my_site \
  --app-name "My Site" \            # display name (default: project name title-cased)
  --description "..." \             # README + API docs description
  --domain my-site.com \            # production domain (ALLOWED_HOSTS examples)
  --author "Name" --email [e-mail] \ # defaults: git config user.name / user.email
  --organization "Acme" \           # copyright holder (default: author)
  -o ~/projects                     # parent directory (default: current directory)

What it does: copies the django_starter template (Django 4.2 + Django Ninja + JWT, Docker/Postgres ready, SQLite fallback for local dev) → renames the {{PROJECT_SLUG}}/ settings package → substitutes all tokens including a freshly generated SECRET_KEY → creates .venv and installs requirements.txt → runs migrations → git init + initial commit. The result passes manage.py check and its own test suite, and serves API docs at /api/v1/docs.

devforge next

devforge next my-web \
  --auth / --no-auth \               # auth module (login/signup, cookie-JWT, axios refresh queue)
  --multi-tenant / --no-multi-tenant # subdomain-per-tenant routing (proxy + [tenant] segment)
  --app-name "My Web" --domain my-web.com \
  --api-url http://127.0.0.1:8000/api/v1 \
  --cookie-prefix mw \               # default: project name initials
  --skip-install \                   # skip npm install
  -o ~/projects

Both features default to no. If the flags are omitted on a terminal, DevForge asks two yes/no questions interactively; in scripts (no TTY) it silently uses the defaults.

What it does: copies the template per its template.json manifest → applies the feature selection (disabled features have files removed and variant overlays applied, so e.g. disabling multi-tenant relocates app/[tenant]/dashboard → app/dashboard) → substitutes tokens → npm install → git init. All four feature combinations produce a project that passes npm run build.

Configuration

Settings resolve in precedence order: environment variables → ./devforge.json → ~/.config/devforge/config.json → defaults.

Setting	Env var	Config key	Default
Template root	DEVFORGE_TEMPLATE_ROOT	template_root	devforge/templates/ inside the package
Log level	DEVFORGE_LOG_LEVEL	log_level	WARNING

Installation

Full step-by-step guide (all platforms, updating, troubleshooting): docs/installation.md. The short version:

With Python 3.9+ (Windows / macOS / Linux):

pipx install devforge-scaffold   # recommended (isolated); or: pip install devforge-scaffold
devforge --version

Without Python — download the standalone binary for your OS from GitHub Releases (devforge-macos-arm64, devforge-windows-x86_64.exe), put it on your PATH and run it. macOS will quarantine an unsigned download: xattr -d com.apple.quarantine devforge-macos-arm64.

The PyPI distribution is named devforge-scaffold (plain devforge was taken), but the installed command is devforge either way.

For development:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Releasing

1. Bump version in pyproject.toml (and src/devforge/__init__.py).
2. git tag v0.x.y && git push origin v0.x.y
3. GitHub Actions (.github/workflows/release.yml) runs the tests, builds the macOS/Windows binaries with PyInstaller (packaging/build_binary.py), attaches them to a GitHub Release, and publishes the wheel to PyPI.

One-time setup for PyPI publishing: create the devforge-scaffold project as a trusted publisher on pypi.org pointing at this repo's release.yml workflow (environment pypi) — no token secrets required.

Project layout

DevForge/
├── pyproject.toml          # packaging, dependencies, `devforge` entry point
├── src/devforge/           # the CLI package (src layout)
│   ├── templates/          # starter templates, shipped as package data
│   │   ├── flutter_starter/  # complete — see its TEMPLATE_REPORT.md
│   │   ├── django_starter/   # complete
│   │   └── nextjs_starter/   # placeholder, to be added
│   ├── cli.py              # Typer app assembly — registers commands, no logic
│   ├── commands/           # one module per CLI command (new, list, doctor)
│   ├── core/               # config, constants, exception hierarchy
│   ├── generators/         # one generator per framework + base interface + registry
│   ├── services/           # shared engines: template substitution, file ops, validation
│   ├── ui/                 # Rich rendering — the only package that imports rich
│   └── utils/              # small dependency-free helpers
├── tests/
│   ├── unit/               # per-module tests mirroring src/devforge
│   └── integration/        # end-to-end `devforge new` runs against real templates
└── docs/
    └── architecture.md     # detailed folder purposes and SOLID mapping

See docs/architecture.md for what each folder is for and why.