{"id":20416,"library":"prettier-plugin-sh","title":"prettier-plugin-sh","description":"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.","status":"active","version":"0.18.1","language":"javascript","source_language":"en","source_url":"https://github.com/un-ts/prettier","tags":["javascript","dockerfile","ini","properties","sh","shell","shellscript","plugin","prettier","typescript"],"install":[{"cmd":"npm install prettier-plugin-sh","lang":"bash","label":"npm"},{"cmd":"yarn add prettier-plugin-sh","lang":"bash","label":"yarn"},{"cmd":"pnpm add prettier-plugin-sh","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: plugin requires Prettier ^3.6.0 to function. Not included as a direct dependency.","package":"prettier","optional":false}],"imports":[{"note":"Plugin is ESM-only since v0.18. CJS require() will fail. Prettier handles plugin loading automatically; manual imports are only for programmatic use.","wrong":"const prettierPluginSh = require('prettier-plugin-sh');","symbol":"default plugin export","correct":"// Plugin is auto-loaded by Prettier when listed in .prettierrc\n// No manual import needed in typical usage.\n// If dynamic configuration is needed, use:\nimport plugin from 'prettier-plugin-sh'"},{"note":"ShOptions is a type-only export, used for configuring the prettier parser options. Cannot be used at runtime.","wrong":"const { ShOptions } = require('prettier-plugin-sh');","symbol":"ShOptions (TypeScript interface)","correct":"import type { ShOptions } from 'prettier-plugin-sh';"},{"note":"LangVariant is a named export from the main package. Incorrect paths cause import errors.","wrong":"import { LangVariant } from 'prettier-plugin-sh/syntax';","symbol":"LangVariant enum (TypeScript)","correct":"import { LangVariant } from 'prettier-plugin-sh';"}],"quickstart":{"code":"// .prettierrc\n{\n  \"plugins\": [\"prettier-plugin-sh\"],\n  \"overrides\": [\n    {\n      \"files\": [\"*.sh\", \"*.bash\"],\n      \"options\": {\n        \"parser\": \"sh\",\n        \"tabWidth\": 4\n      }\n    }\n  ]\n}\n\n// Then run:\n// npx prettier --write script.sh\n// The plugin automatically formats shell scripts with consistent indentation, quotes, and line breaks.","lang":"typescript","description":"Configuration to enable shell script formatting via Prettier using the prettier-plugin-sh plugin. Shows setup in .prettierrc and basic CLI usage."},"warnings":[{"fix":"Use dynamic import() if needed, or let Prettier load the plugin automatically via the plugins config in .prettierrc.","message":"Plugin is ESM-only. Using require('prettier-plugin-sh') with CommonJS will throw an error.","severity":"gotcha","affected_versions":">=0.18.0"},{"fix":"Update Node to v16 or later.","message":"Drop support for Node versions below 16. Requires Node >=16.0.0.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Update prettier to ^3.6.0 or later.","message":"Peer dependency requirement changed: prettier ^3.6.0 is required. Older Prettier versions will not work.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Manually check formatted ignore files for correctness. Avoid relying on this plugin for ignore files.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Remove keepComments from configuration if previously set to false.","message":"The 'keepComments' option now defaults to true and cannot be disabled via the parser options.","severity":"deprecated","affected_versions":">=0.17.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"Trying to require() the plugin in a CommonJS environment. The package is ESM-only.","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."},{"fix":"npm install prettier-plugin-sh --save-dev and add 'prettier-plugin-sh' to the plugins array in .prettierrc.","cause":"Plugin not installed, or not listed in .prettierrc plugins array. Prettier does not automatically discover plugins unless configured.","error":"Cannot find module 'prettier-plugin-sh'"},{"fix":"Update prettier to ^3.6.0: npm install prettier@^3.6.0 --save-dev","cause":"Incompatible version of Prettier. The plugin requires prettier ^3.6.0, but older versions used a different internal module structure.","error":"Error: Cannot find module '@prettier/sync'"},{"fix":"Ensure the file extension is .sh, .bash, .env, etc. Use the 'overrides' option to specify parser explicitly.","cause":"Parsing a file with unsupported extension or syntax. The plugin may not handle all shell variants correctly.","error":"TypeError: Cannot read properties of undefined (reading 'type')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}