Quick Start¶

This guide walks you through building your first single-file PowerShell script from a multi-file project.

Prerequisites¶

PSScriptBuilder installed — see Installation
A PowerShell project with source files to combine

Example Project Structure¶

This guide uses a simple project as example:

MyModule/
├── psscriptbuilder.config.json
├── build/
│   ├── Templates/
│   │   └── MyModule.psm1.template
│   └── Output/           ← generated files go here
└── src/
    ├── Classes/
    │   ├── Animal.ps1
    │   └── Dog.ps1
    └── Public/
        └── Get-AnimalInfo.ps1

Step 1 — Add the Configuration File¶

Create psscriptbuilder.config.json in your project root:

{
    "build": {
        "outputPath":             ".\\build\\Output",
        "ensureOutputPathExists": false,
        "backupPath":             ".\\build\\Output\\Backup",
        "templatesPath":          ".\\build\\Templates",
        "orderedComponentsKey":   "ORDERED_COMPONENTS",
        "backupEnabled":          false
    },
    "release": {
        "dataFile":       ".\\build\\Release\\psscriptbuilder.releasedata.json",
        "bumpConfigFile": ".\\build\\Release\\psscriptbuilder.bumpconfig.json"
    }
}

All fields are required

Every field in the configuration file must be present. The validator enforces all fields as required — omitting any field causes an error when the configuration is loaded.

PSScriptBuilder searches for this file starting from the current directory upward, so you only need to place it once at the project root.

Step 2 — Create a Template¶

Create build/Templates/MyModule.psm1.template:

#region Classes
{{ClassDefinitions}}
#endregion Classes

#region Functions
{{FunctionDefinitions}}
#endregion Functions

Each {{Token}} placeholder is replaced with the collected and dependency-ordered source code of the corresponding collector. The default token per collector type is:

Collector Type	Default Token
`Using`	`{{UsingStatements}}`
`Enum`	`{{EnumDefinitions}}`
`Class`	`{{ClassDefinitions}}`
`Function`	`{{FunctionDefinitions}}`
`File`	`{{FileContents}}`

Step 3 — Run a Build Script¶

Create a Build-MyModule.ps1 at the project root:

using module PSScriptBuilder

$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath '.\src\Classes' |
    Add-PSScriptBuilderCollector -Type Function -IncludePath '.\src\Public'

Invoke-PSScriptBuilderBuild `
    -ContentCollector $cc `
    -TemplatePath     '.\build\Templates\MyModule.psm1.template' `
    -OutputPath       '.\build\Output\MyModule.psm1'

Run it from your project directory:

.\Build-MyModule.ps1

Step 4 — Check the Output¶

The generated build/Output/MyModule.psm1 contains all classes (in correct dependency order) followed by all functions — ready to deploy as a single file.

PSScriptBuilder automatically resolves the load order: if Dog inherits from Animal, Animal is always placed before Dog in the output, regardless of file order.

Cross-Dependency Mode¶

When classes reference functions and functions reference classes, PSScriptBuilder detects this and switches to Cross-Dependency Mode automatically. In this mode, use the ORDERED_COMPONENTS placeholder instead of separate per-type tokens:

# template with cross-dependency support
{{ORDERED_COMPONENTS}}

The ORDERED_COMPONENTS key is configured in psscriptbuilder.config.json under build.orderedComponentsKey (default: "ORDERED_COMPONENTS"). See the Templates Guide for all available placeholder options.

Use Test-PSScriptBuilderTemplate to validate your template before building:

$isValid = Test-PSScriptBuilderTemplate -ContentCollector $cc -TemplatePath '.\build\Templates\MyModule.psm1.template'

if ($isValid) {
    Invoke-PSScriptBuilderBuild -ContentCollector $cc `
        -TemplatePath '.\build\Templates\MyModule.psm1.template' `
        -OutputPath   '.\build\Output\MyModule.psm1'
}