Registry / devops / prettier-plugin-sh

prettier-plugin-sh

library0.18.1jsnpmunverified

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.

devops

npm install prettier-plugin-sh

github ↗package ↗

INSTALL

IMPORT

SIG · PRETTIER-PLUGIN-SH

prettier-plugin-sh

devopsjavascriptv0.18.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default plugin export

✓ // 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'

✗ const prettierPluginSh = require('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)

✓ import type { ShOptions } from 'prettier-plugin-sh';

✗ const { ShOptions } = require('prettier-plugin-sh');

ShOptions is a type-only export, used for configuring the prettier parser options. Cannot be used at runtime.

LangVariant enum (TypeScript)

✓ import { LangVariant } from 'prettier-plugin-sh';

✗ import { LangVariant } from 'prettier-plugin-sh/syntax';

LangVariant is a named export from the main package. Incorrect paths cause import errors.

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.

Debug

Known issues

gotchaPlugin 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.

affects: >=0.18.0

breakingDrop support for Node versions below 16. Requires Node >=16.0.0.

fix

Update Node to v16 or later.

affects: >=0.18.0

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

fix

Update prettier to ^3.6.0 or later.

affects: >=0.18.0

gotchaIgnore 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.

affects: >=0.0.0

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

fix

Remove keepComments from configuration if previously set to false.

affects: >=0.17.0

Errors

Common errors & fixes

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.

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.

Cannot find module 'prettier-plugin-sh'

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: Cannot find module '@prettier/sync'

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

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

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.

Upgrade

Version history

0.18.1latest on npm

Audit

Dependencies

prettierrequiredPeer dependency: plugin requires Prettier ^3.6.0 to function. Not included as a direct dependency.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/un-ts/prettier ↗

packagehttps://www.npmjs.com/package/prettier-plugin-sh ↗