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

1. Highlights
2. Quick start
3. Configuration reference
4. Example formatting
5. Contributing
6. Credits
7. License
8. Contributors ✨

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):

Nick2bad4u 🐛 💻 📖 🤔 🚇 🚧 👀 ⚠️ 🔧	Snyk bot 🛡️ 🚇 🚧 👀	StepSecurity Bot 🛡️ 🚇 🚧	dependabot[bot] 🚇 🛡️
github-actions[bot] 💻 🚇