prettier-plugin-sh

0.18.1 verified Sat Apr 25 auth: no javascript

An opinionated shell script formatter for Prettier, extending support to Dockerfile, .properties, .gitignore, .env, hosts, and JVM options files. Current stable version is 0.18.1, maintained actively with minor updates every few months. It leverages mvdan-sh and dockerfmt under the hood, providing a consistent shell formatting experience within Prettier's ecosystem. Unlike standalone shell formatters, it integrates seamlessly with Prettier's plugin system and respects project-wide formatting configuration. Supports Prettier ^3.6.0 and Node 16+. Ships TypeScript definitions.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/prettier-plugin-sh/dist/index.js from /path/to/script.js not supported. ↓

cause Trying to require() the plugin in a CommonJS environment. The package is ESM-only.

fix

Use import() or let Prettier load the plugin automatically via .prettierrc. For legacy scripts, switch to ESM by adding 'type': 'module' to package.json or use dynamic import.

error Cannot find module 'prettier-plugin-sh' ↓

cause Plugin not installed, or not listed in .prettierrc plugins array. Prettier does not automatically discover plugins unless configured.

fix

npm install prettier-plugin-sh --save-dev and add 'prettier-plugin-sh' to the plugins array in .prettierrc.

error Error: Cannot find module '@prettier/sync' ↓

cause Incompatible version of Prettier. The plugin requires prettier ^3.6.0, but older versions used a different internal module structure.

fix

Update prettier to ^3.6.0: npm install prettier@^3.6.0 --save-dev

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause Parsing a file with unsupported extension or syntax. The plugin may not handle all shell variants correctly.

fix

Ensure the file extension is .sh, .bash, .env, etc. Use the 'overrides' option to specify parser explicitly.

Warnings

gotcha Plugin is ESM-only. Using require('prettier-plugin-sh') with CommonJS will throw an error. ↓

fix Use dynamic import() if needed, or let Prettier load the plugin automatically via the plugins config in .prettierrc.

breaking Drop support for Node versions below 16. Requires Node >=16.0.0. ↓

fix Update Node to v16 or later.

breaking Peer dependency requirement changed: prettier ^3.6.0 is required. Older Prettier versions will not work. ↓

fix Update prettier to ^3.6.0 or later.

gotcha Ignore files (e.g., .gitignore, .dockerignore) are not fully supported by the underlying mvdan-sh library. Basic patterns work, but complex ignores may not format correctly. ↓

fix Manually check formatted ignore files for correctness. Avoid relying on this plugin for ignore files.

deprecated The 'keepComments' option now defaults to true and cannot be disabled via the parser options. ↓

fix Remove keepComments from configuration if previously set to false.

Install

npm install prettier-plugin-sh

yarn add prettier-plugin-sh

pnpm add prettier-plugin-sh

Imports

default plugin export

wrong

const prettierPluginSh = require('prettier-plugin-sh');

correct

// Plugin is auto-loaded by Prettier when listed in .prettierrc
// No manual import needed in typical usage.
// If dynamic configuration is needed, use:
import plugin from 'prettier-plugin-sh'

Plugin is ESM-only since v0.18. CJS require() will fail. Prettier handles plugin loading automatically; manual imports are only for programmatic use.

ShOptions (TypeScript interface)
wrong
```
const { ShOptions } = require('prettier-plugin-sh');
```
correct
```
import type { ShOptions } from 'prettier-plugin-sh';
```
ShOptions is a type-only export, used for configuring the prettier parser options. Cannot be used at runtime.
LangVariant enum (TypeScript)
wrong
```
import { LangVariant } from 'prettier-plugin-sh/syntax';
```
correct
```
import { LangVariant } from 'prettier-plugin-sh';
```
LangVariant is a named export from the main package. Incorrect paths cause import errors.

Quickstart

Configuration to enable shell script formatting via Prettier using the prettier-plugin-sh plugin. Shows setup in .prettierrc and basic CLI usage.

// .prettierrc
{
  "plugins": ["prettier-plugin-sh"],
  "overrides": [
    {
      "files": ["*.sh", "*.bash"],
      "options": {
        "parser": "sh",
        "tabWidth": 4
      }
    }
  ]
}

// Then run:
// npx prettier --write script.sh
// The plugin automatically formats shell scripts with consistent indentation, quotes, and line breaks.