A dependency-aware PowerShell script builder that combines multi-file projects into a single, deployable script.

The Problem

As a PowerShell project grows, managing the order of classes, enums, and functions across dozens of files becomes error-prone and hard to maintain. Class and enum definitions must appear before the code that references them — base classes before derived classes, enums before the classes that use them, classes before the functions that depend on them.

The Solution

PSScriptBuilder analyzes your source files using PowerShell's AST, resolves all dependencies automatically, and combines everything into a single, correctly ordered, deployable script — no manual sorting required.

• Automatic Dependency Ordering — Uses topological sort and AST analysis to resolve class inheritance, type dependencies, and inter-file relationships; output is always in valid load order
• Cycle Detection — Detects fatal circular dependencies (inheritance, static initializers) before any output is written; type reference cycles are resolved automatically
• Cross-Dependency Support — Detects when classes and functions must be interleaved and switches to a unified ordered output block automatically
• Flexible Templates — Define your output structure once using a template with token placeholders; supports any output format (.psm1, .ps1, .txt)
• Configurable Collectors — Dedicated, customizable collectors for Classes, Functions, Enums, Using statements, and raw Files
• Project Scaffolding — Generates a ready-to-build project structure with sample source files and a build script
• Script Compression — Strips comments and blank lines from the built output for lean, deployable scripts
• Release Management — Built-in SemVer version bumping, Git metadata extraction, and file update automation
• PowerShell 5.1 and 7+ Compatible — Runs on Windows PowerShell 5.1 and PowerShell 7+ (Windows, Linux, macOS)

PSScriptBuilder is available on the PowerShell Gallery and requires using module for import.

1. Install

Install-Module -Name PSScriptBuilder -Scope CurrentUser

2. Import

Note: Always use using module — not Import-Module. PowerShell only loads class and enum definitions with using module. The using statement must appear at the very top of your script, before any other code.

✅ Correct — all class and enum definitions are loaded and available:

using module PSScriptBuilder

❌ Wrong — classes and enums will NOT be available:

Import-Module PSScriptBuilder

After importing the module, follow the path that matches your situation.

1. Scaffold

New-PSScriptBuilderProject -Name "MyProject" -Path "C:\Projects"
cd "C:\Projects\MyProject"

2. Build (runs the generated build script with sample source files)

.\Build-MyProject.ps1

1. Create configuration (first-time setup)

New-PSScriptBuilderConfiguration

2. Configure collectors

$contentCollector = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath "src/Classes" |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src/Public"

3. Build

Invoke-PSScriptBuilderBuild `
    -ContentCollector $contentCollector `
    -TemplatePath     "build/MyProject.ps1.template" `
    -OutputPath       "build/Output/MyProject.ps1"

Note: PSScriptBuilder resolves relative paths (like src/Classes) against the project root. Run these commands from your project directory, or call Set-PSScriptBuilderProjectRoot -Path "C:\Projects\MyProject" first to set it explicitly.

Fifteen runnable examples are included in the examples/ directory, covering scenarios from simple function builds to full release workflows with scaffolding, compression, and real-time file watching.

See the Examples page for descriptions and walkthroughs.

PSScriptBuilder provides five collector types, each targeting a specific PowerShell component.

Each collector accepts -IncludePath, -ExcludePath, -IncludeFile, -ExcludeFile, -FileExtension, and an optional -CollectionKey for use as a template token.

See the Collectors Guide for details on filtering, custom keys, and advanced collector configuration.

PSScriptBuilder uses plain text template files with {{Token}} placeholders to define the structure of the output file — supporting any extension (.psm1, .ps1, .txt, etc.).

Default CollectionKey per collector type:

Example template (build/MyProject.ps1.template):

{{USING_STATEMENTS}}

{{ENUM_DEFINITIONS}}

{{CLASS_DEFINITIONS}}

{{FUNCTION_DEFINITIONS}}

{{FILE_CONTENTS}}

Use -CollectionKey on Add-PSScriptBuilderCollector to define a custom token name, e.g. {{DOMAIN_CLASSES}}.

When classes and functions have mutual dependencies that require interleaving in the output, PSScriptBuilder automatically switches to Ordered Mode. Replace the individual per-type placeholders with a single {{ORDERED_COMPONENTS}} token:

{{USING_STATEMENTS}}
{{ORDERED_COMPONENTS}}

Hybrid Mode lets you adopt this layout proactively — even when no cross-dependencies currently exist — making the template resilient to future dependency changes without restructuring. See the Templates Guide for details.

PSScriptBuilder includes cmdlets for SemVer version management, Git metadata extraction, and automated file updates.

# Bump the version (Major / Minor / Patch)
Update-PSScriptBuilderReleaseData -Minor

# Propagate version tokens across all registered files
Update-PSScriptBuilderBumpFiles

# Then run your build
Invoke-PSScriptBuilderBuild `
    -ContentCollector $contentCollector `
    -TemplatePath     "build/MyProject.ps1.template" `
    -OutputPath       "build/Output/MyProject.ps1"

See the Release Management Guide for details on bump configuration, token replacement, and the full release pipeline.

To build the module from source, clone the repository and run the build script.

git clone https://github.com/PSScriptBuilder/PSScriptBuilder.git
cd PSScriptBuilder

.\build.ps1 -ProjectRoot $PWD

build.ps1 is the bootstrap script — it does not require PSScriptBuilder to be installed and is used for the initial build only. Once the module is built, Build-Module.ps1 is used for subsequent builds.

This GitHub repository is a mirror of the primary development repository hosted on GitLab. Pull requests submitted here will not be merged. Please use GitHub Issues for bug reports and feature requests.

For code conventions, testing instructions, and contribution guidelines, see CONTRIBUTING.md.

ModuleBuilder — a simpler alternative for projects that do not require class dependency ordering.

See CHANGELOG.md.

MIT — see LICENSE.

Tim Hartling

For questions, bug reports, or feature requests, please open an Issue on GitHub.