Prettier Plugin PowerShell

A Prettier 3 plugin that formats PowerShell source files (.ps1, .psm1, .psd1) with predictable, idiomatic output. The formatter is extensively tested (high coverage with strict CI thresholds) and ready for CI/CD pipelines, editor integrations, and automated release flows.

Table of contents

• Highlights

• Quick start

  • Install
  • Prettier configuration
  • Command line
  • Programmatic usage

• Configuration reference

• Example formatting

• Automation & coverage

• Project scripts

• Contributing

• Credits

• License

Highlights

• 🌟 Idiomatic PowerShell – balances spacing, casing, and pipeline layout while preserving comments and here-strings.
• 🔧 Fine-grained controls – tune indentation style/width, trailing delimiters, brace style, alias rewriting, and keyword casing.
• ⚡ Prettier-first – drop-in plugin for Prettier v3+, compatible with the CLI, editors, and format-on-save workflows.
• 📈 Production ready – enforced by CI (lint, typecheck, tests) with Codecov-powered reporting and ≥95 % coverage gates.
• 🛠️ TypeScript source – strongly typed AST helpers and printer utilities for easy extension.

Quick start

Install

npm install --save-dev prettier prettier-plugin-powershell

Requires Node.js 18.12 or newer and Prettier v3 or newer.

Prettier configuration

Add the plugin to your Prettier config (e.g. .prettierrc.json):

{
  "plugins": ["prettier-plugin-powershell"],
  "parser": "powershell"
}

You can co-locate plugin options with standard Prettier settings:

{
  "plugins": ["prettier-plugin-powershell"],
  "tabWidth": 2,
  "powershellTrailingComma": "all",
  "powershellRewriteAliases": true
}

Command line

Format scripts recursively:

npx prettier "**/*.ps1" --write

Programmatic usage

import prettier from 'prettier';
import plugin from 'prettier-plugin-powershell';

const formatted = await prettier.format(source, {
  filepath: 'script.ps1',
  parser: 'powershell',
  plugins: [plugin]
});

Configuration reference

Option	Type	Default	Description
powershellIndentStyle	`"spaces" \	"tabs"`	"spaces"
powershellIndentSize	number	4	Overrides Prettier's tabWidth specifically for PowerShell files (clamped between 1 and 8).
powershellTrailingComma	`"none" \	"multiline" \	"all"`
powershellSortHashtableKeys	boolean	false	Sort hashtable keys alphabetically before printing.
powershellBlankLinesBetweenFunctions	number	1	Minimum blank lines preserved between function declarations (clamped between 0 and 3).
powershellBlankLineAfterParam	boolean	true	Insert a blank line after param (...) blocks within functions/script blocks.
powershellBraceStyle	`"1tbs" \	"allman"`	"1tbs"
powershellLineWidth	number	120	Maximum print width for wrapping pipelines, hashtables, and arrays (clamped between 40 and 200).
powershellPreferSingleQuote	boolean	false	Prefer single-quoted strings when interpolation is not required.
powershellKeywordCase	`"preserve" \	"lower" \	"upper" \
powershellRewriteAliases	boolean	false	Expand cmdlet aliases such as ls, %, ?, gci.
powershellRewriteWriteHost	boolean	false	Rewrite Write-Host invocations to Write-Output.
powershellPreset	`"none" \	"invoke-formatter"`	"none"

Invoke-Formatter parity preset

Set "powershellPreset": "invoke-formatter" to mirror the behavior of Invoke-Formatter/PSScriptAnalyzer's CodeFormatting profile. The preset only fills in values that you haven't provided yourself--any explicit option in your Prettier config still wins.

{
  "plugins": ["prettier-plugin-powershell"],
  "powershellPreset": "invoke-formatter",
  // overrides remain opt-in
  "powershellRewriteAliases": true
}

Per-directory overrides (keyword casing, presets, etc.)

Prettier supports overrides, so you can scope keyword casing/presets to specific folders without extra tooling:

{
  "plugins": ["prettier-plugin-powershell"],
  "powershellPreset": "invoke-formatter",
  "overrides": [
    {
      "files": "legacy/**/*.ps1",
      "options": {
        "powershellKeywordCase": "preserve"
      }
    }
  ]
}

Combined with the preset, this makes it easy to keep your primary scripts aligned with PowerShell's formatter while letting legacy or third-party snippets retain their original casing.

Example formatting

Input:

function Get-Widget{
param(
[string]$Name,
[int] $Count
)
$items=Get-Item |Where-Object { $_.Name -eq $Name}| Select-Object Name,Length
$hash=@{ b=2; a =1 }
}

Output with default settings:

function Get-Widget {
    param(
        [string] $Name,
        [int] $Count
    )

    $items = Get-Item
        | Where-Object {
            $_.Name -eq $Name
        }
        | Select-Object Name, Length
    $hash = @{ b = 2; a = 1 }
}

Automation & coverage

• CI – GitHub Actions (see ci.yml) installs dependencies, lint checks, type-checks, and runs the Vitest suite with coverage on every push and pull request.
• Codecov – Coverage artefacts (coverage/lcov.info) are uploaded via the Codecov action. The badge above reflects the latest metrics on main.
• npm publishing – Every push to main triggers publish.yml, which bumps the version (patch by default, feat → minor, BREAKING → major), runs the quality bar, commits the build artifacts, tags the release, publishes to npm, and opens a GitHub release. The legacy manual workflow now just points back to this automated pipeline; you can still run it manually from the Actions tab when needed.

Property-based testing

• Fast-check harness – Property-based tests across multiple modules use fast-check to validate behavior with randomly generated inputs:

  • tests/parser.property.test.ts – Exercises the parser and formatter with randomly generated PowerShell snippets, validating location metadata, token ordering, formatting stability, and re-parseability.
  • tests/parser.edge-cases.property.test.ts – Stress-tests the parser with edge cases: deep nesting, unbalanced delimiters, comment placement, string variations, whitespace handling, pipelines, operators, and location consistency.
  • tests/tokenizer.property.test.ts – Validates tokenizer correctness: token ordering, location ranges, determinism, and proper handling of keywords, variables, strings, comments, and edge cases.
  • tests/tokenizer-helpers.property.test.ts – Tests the normalizeHereString helper function with various line counts, empty lines, mixed line endings, and edge cases.
  • tests/options.property.test.ts – Ensures option resolution never throws, produces valid output, respects user preferences, applies sensible defaults, and correctly clamps numeric values.
  • tests/ast.property.test.ts – Tests AST utility functions (createLocation, isNodeType, cloneNode) for correctness with edge cases like negative values, NaN, Infinity, and type safety.
  • tests/printer.property.test.ts – Validates printer output: formatting never throws, produces valid PowerShell, remains idempotent, preserves semantics, respects configuration options, and handles edge cases like empty scripts and comments.
  • tests/integration.property.test.ts – Tests full round-trip preservation (tokenize → parse → format → re-parse), option combinations, cross-module consistency, error resilience, plugin interface contracts, and file extension handling.
  • tests/weird-files.property.test.ts – Exercises BOM + shebang combinations, Unicode-heavy content, comment directives, and exotic whitespace to ensure the parser and printer remain stable on atypical files.
  • tests/printer-options.property.test.ts – Verifies option-sensitive printing behavior (blank line heuristics, string quote normalization, alias rewriting, and Write-Host rewriting) across randomized inputs.
  • tests/github-samples.property.test.ts – Opt-in: when enabled, pulls real-world PowerShell scripts from the GitHub API, then formats and re-parses them to guard against regressions on long/complex inputs. By default it runs against local fallback fixtures; set POWERSHELL_ENABLE_GITHUB_SAMPLES=1 (and optionally GITHUB_TOKEN) to exercise live GitHub samples.

• Custom arbitraries – Reusable builders in tests/property/arbitraries.ts generate assignments, pipelines, functions, try/catch blocks, and other constructs to shake out edge cases.

• Idempotence checks – Most property tests and fixtures assert that formatting is idempotent; a small number of known edge-case fixtures are marked with expectIdempotent: false so they still validate parseability without requiring strict first/second-pass equality.

• Tuning – Adjust the number of runs with the POWERSHELL_PROPERTY_RUNS environment variable (default 100 for most tests, 150 for parser tests). For a deeper local sweep: POWERSHELL_PROPERTY_RUNS=500 npm test.

• PowerShell syntax sampling – By default, every formatted script is re-validated with PowerShell's built-in parser so regressions surface immediately. Use POWERSHELL_MAX_SYNTAX_CHECKS to cap the number of checks (set to a positive integer) or 0 to skip entirely, and toggle the feature wholesale with POWERSHELL_VERIFY_SYNTAX (0 to disable).

  • Use POWERSHELL_SYNTAX_TRACE=1 to emit per-invocation logs when diagnosing hangs or parser failures.

• Property progress & timeboxing – Flip on run-by-run logging with POWERSHELL_PROPERTY_PROGRESS=1 (default interval 50, tweak via POWERSHELL_PROPERTY_PROGRESS_INTERVAL). Extend or shrink Vitest's overall timeout with POWERSHELL_TEST_TIMEOUT_MS when running extended fuzz sweeps, and control worker concurrency with MAX_THREADS (default 4, or 1 on CI).

• Deep fuzzing – npm run test:fuzz now shells through PowerShell so the POWERSHELL_PROPERTY_RUNS=2000 environment toggle works cross-platform.

To fuzz against GitHub-hosted PowerShell, export POWERSHELL_ENABLE_GITHUB_SAMPLES=1 (optionally GITHUB_TOKEN to raise rate limits) and run npm test. You can further tune POWERSHELL_GITHUB_SAMPLE_COUNT, POWERSHELL_GITHUB_QUERY, POWERSHELL_GITHUB_MIN_LENGTH, POWERSHELL_GITHUB_MAX_LENGTH, and POWERSHELL_GITHUB_MAX_CANDIDATES to control source selection. Enable POWERSHELL_CACHE_GITHUB_SAMPLES=1 to save downloaded samples to tests/fixtures/github-cache/ for reuse across runs, avoiding redundant API calls.

Project scripts

Script	Description
npm run build	Bundle the plugin to dist/ via tsup.
npm run build:watch	Rebuild continuously while developing.
npm run clean	Remove the dist/ directory.
npm run lint / npm run lint:fix	Run ESLint (optionally with auto-fix).
npm run format	Apply Prettier to TypeScript source and tests.
npm run test / npm run test:watch	Execute the Vitest suite.
npm run test:ci	Run the Vitest suite with a summary reporter (used in CI workflows).
npm run test:debug	Start Vitest under the Node inspector for interactive debugging.
npm run test:coverage	Generate v8 coverage reports (consumed by Codecov).
npm run test:fuzz	Run the Vitest suite with POWERSHELL_PROPERTY_RUNS=2000 via PowerShell for deep fuzzing.
npm run benchmark	Run the built-in benchmark against synthetic PowerShell functions.
npm run profile / npm run profile:enhanced	Capture parser/formatter performance profiles for detailed analysis.
npm run typecheck	Ensure the TypeScript project compiles without emitting files.

Contributing

1. Fork and clone the repository.
2. Install dependencies with npm install.
3. Use npm run build:watch during active development.
4. Before opening a pull request, run:

• npm run lint
• npm run typecheck
• npm run test:coverage

5. Contributions remain under the UnLicense license.

Bug reports and feature requests are welcome via GitHub issues.

Credits

• Mascot artwork courtesy of the ColorScripts team (light and dark variants included in assets/).
• Built with Prettier, TypeScript, and Vitest.

License

Distributed under the UnLicense License.