Prettier-Plugin-Powershell

Prettier-Plugin-Powershell by Typpi / Nick2bad4u

View on GitHub

Prettier Plugin PowerShell

CI codecov npm version npm downloads License: UnLicense Node.js >= 18.12

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.

Prettier PowerShell mascot

Table of contents

Highlights

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" Render indentation with spaces or tabs.
powershellIndentSize number 4 Overrides Prettier’s tabWidth specifically for PowerShell files (clamped between 1 and 8).
powershellTrailingComma "none" \ | "multiline" \ | "all" "none" When to emit trailing semicolons between hashtable entries (PowerShell arrays do not support trailing commas).
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" Choose inline braces or newline-aligned Allman style.
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" \ | "pascal" "lower" Normalise PowerShell keyword casing (defaults to lowercase to match PSScriptAnalyzer/Invoke-Formatter).
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" Apply a bundle of defaults (e.g. invoke-formatter mirrors the settings PowerShell’s built-in formatter uses).

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

Property-based testing

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:
  1. Contributions remain under the UnLicense license.

Bug reports and feature requests are welcome via GitHub issues.

Credits

License

Distributed under the UnLicense License.