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
• 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" | 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 }
}

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 MIT License.

Bug reports and feature requests are welcome via GitHub issues.

Credits

• Built with Prettier, TypeScript, and Vitest.

License

Distributed under the MIT License.

Contributors ✨

Thanks goes to these wonderful people (emoji key):