Why ModuleForge Exists

Building a PowerShell module is easy. Building one well, and keeping it that way across months of changes and a team of contributors, is not. ModuleForge exists to close that gap.

The problem

Most PowerShell modules start the same way: a single .psm1, a handful of functions, and good intentions. Then they grow, and the same problems surface in almost every project:

  • Structure drifts. Every module invents its own layout, so no two look alike and onboarding starts from zero each time.
  • Versioning is manual. Someone remembers to bump the manifest, or they don’t. Prerelease conventions are ad hoc.
  • Changelogs rot. Release notes get written by hand, late, from memory, if at all.
  • CI is bespoke and fragile. The build works on one person’s machine and nobody is quite sure why it breaks on the runner.
  • Conventions are unwritten. How you write a function, where tests live, what a commit message should say: all folklore, none of it enforced.

None of these is hard on its own. Collectively they are why a promising module becomes hard to maintain, and they are exactly the kind of problem tooling should solve once so you never solve it again. For a head-to-head with the specific tools in this space, see ModuleForge vs Alternatives.

Borrowed from the best

Spend time in other ecosystems and the envy sets in. A single command spins up a complete React project: build tooling, a dev server, tests, and a sensible structure, ready in seconds. A well-run Terraform project tags every resource automatically, enforces its own conventions, and quietly makes the right thing the easy thing. Those communities decided long ago that scaffolding, automation, and convention were not luxuries; they were the baseline.

PowerShell development deserves the same. Nothing about a PowerShell module makes it unworthy of instant project creation, automated versioning and tagging, generated changelogs, and a pipeline that just works. ModuleForge is, in large part, those borrowed ideas brought home: the DevOps niceties other ecosystems take for granted, applied to PowerShell.

The idea

ModuleForge is an opinionated build and release tool for PowerShell modules. It makes the boring decisions for you, scaffolds a project that already has CI/CD, versioning, and documentation wired in, and then gets out of your way so you can write functions.

Three convictions shape it:

  • Opinionated beats configurable. The questions every project must answer (where do classes go? what is the prerelease format? what counts as a breaking change?) all have defensible answers most projects can live with. ModuleForge answers them so you do not have to. You can still override; you rarely need to.
  • Pure PowerShell. No external build runner, no DSL to learn. If you know PowerShell, you can read, modify, and trust every part of the pipeline. More on that choice in From Bartender to ModuleForge.
  • It builds itself. Every release of ModuleForge is built and published by the previous release. If the tool cannot build and ship itself, the build is broken before it ever reaches you. See ModuleForge Builds Itself.

The principles in practice

Those convictions show up as concrete defaults:

  • Convention over configuration. A fixed source layout (functions, private, classes, enums, and so on) compiled in a known order. Learn it once, recognise it everywhere. Start in Getting Started.
  • Versioning with discipline. SemVer with PSGallery-compatible prerelease handling, derived from your git tags rather than hand-edited. See Module Versioning with SemVer.
  • Changelogs from your commits. Well-prefixed commits generate release notes automatically, so the changelog is a by-product of working, not a chore.
  • Tests and docs as first-class. Pester runs as a hard gate, coverage is advisory, and a documentation site regenerates from your help text. See Writing Pester Tests and Publishing a Documentation Site.
  • Cross-platform by default. The scaffolded pipelines run on Linux runners, and the conventions assume your code might too.

ModuleForge also has opinions about the code inside your functions, though it does not enforce them. Those are gathered, take them or leave them, in PowerShell Style Recommendations.

What it buys you

The headline is speed: a new module is one command away from a working structure, CI/CD, versioning, and a documentation pipeline, so your first hour goes on functions, not plumbing.

  • Get going faster. The setup that normally eats your first day is already done, so you start with code, not boilerplate.
  • Be encouraged to code to a high standard. Tests gate the build, linting and coverage report on every PR, conventions stay consistent, and good documentation falls out of good help text. The easy path and the high-quality path are the same path.
  • Get the niceties other tooling takes for granted. The scaffolding, automation, and convention this page opened with, brought to PowerShell.

And because the tool builds itself, none of this is theoretical: the workflow you are handed is the one that ships ModuleForge, exercised on real code with every release. A contributor who has seen one ModuleForge module can find their way around any of them.

Where it is going

ModuleForge is deliberately scoped: it targets GitHub and Azure DevOps, it does not compile binaries, and it stays opinionated rather than growing endless configuration. Within that scope, two directions matter most.

Security and supply-chain confidence. Release integrity is already part of the pipeline; published checksums let you prove an installed module is exactly the one that was built (see Release Integrity and Checksums). The next steps build on that foundation: flagging code that will not run under Constrained Language Mode before it ships, and making artifact signing a first-class, documented step.

Whatever the community actually needs. The direction is shaped as much by users as by the maintainers, and the project stays open-minded about where it goes next. Some of the most valuable additions, such as support for other CI platforms or DSC resources, are explicitly open for contribution. If ModuleForge is missing something that would make your PowerShell DevOps better, that is a conversation worth starting, not a closed door.

Your path through the docs

Depending on why you are here:

Welcome. Forge something great.