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

1. 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] 💻 🚇