ESLint Shell Language Plugin

A shell language plugin for ESLint, providing:

• an ESLint-style parser for shell scripts (wrapping mvdan-sh, the parser behind shfmt) that produces an ESTree-style syntax tree,
• an ESLint language implementation so rules can traverse that tree,
• rules inspired by ShellCheck checks, and
• a recommended configuration.

Installation

npm install --save-dev eslint @eslint/shell

Requires Node.js ^20.19.0 || ^22.13.0 || >=24. Tested with ESLint v10.

Usage

Add the plugin to your eslint.config.js:

import shell from "@eslint/shell";

export default [
	// use the recommended rules for *.sh and *.bash files
	shell.configs.recommended,
];

Or configure it manually:

import shell from "@eslint/shell";

export default [
	{
		files: ["**/*.sh"],
		plugins: { shell },
		language: "shell/bash",
		rules: {
			"shell/no-backticks": "error",
			"shell/no-unquoted-expansions": "error",
		},
	},
];

Languages

The plugin provides one language per shell dialect:

Language	Description
shell/bash	Bash. Used by the recommended config.
shell/posix	POSIX sh, without Bash extensions.
shell/mksh	MirBSD Korn shell.

export default [
	{
		files: ["**/*.sh"],
		plugins: { shell },
		language: "shell/posix",
		rules: { "shell/no-backticks": "error" },
	},
];

Rules

Each rule mirrors a well-known ShellCheck check.

Rule	ShellCheck	Description	Fixable	Recommended
no-backticks	SC2006	Use $(...) instead of legacy backticks	✅	error
no-expansions-in-single-quotes	SC2016	Expressions don't expand in single quotes		warn
no-ls-iteration	SC2045	Don't iterate over ls output; use globs		error
no-unquoted-expansions	SC2086/46	Quote expansions subject to word splitting and globbing	✅	error
no-unused-vars	SC2034	Disallow variables that are assigned but never used		error
no-useless-cat	SC2002	Don't pipe from a single-file cat		error
no-useless-echo	SC2116	Disallow $(echo ...)		error
no-variables-in-printf-format	SC2059	Don't put variables in the printf format string		error
require-cd-guard	SC2164	Handle cd failure with || exit (has suggestions)		error
require-read-r	SC2162	Use read -r so backslashes aren't mangled	✅	error

Rule options

shell/no-unused-vars accepts an object option:

"shell/no-unused-vars": ["error", { allowed: ["MY_GLOBAL"] }]

Configuration comments

Standard ESLint configuration comments work inside shell scripts:

# eslint-disable-next-line shell/no-backticks
echo `pwd`

echo `pwd` # eslint-disable-line shell/no-backticks -- legacy

# eslint shell/no-useless-echo: "warn"

Syntax tree

The tree format is documented in docs/syntax-tree.md. Nodes carry start/end character offsets instead of range/loc properties; use sourceCode.getRange(node) and sourceCode.getLoc(node).

The parser is also exported directly:

import { parseShell } from "@eslint/shell";

const { ast, comments } = parseShell('echo "hello"\n');

Development

npm install
npm test          # unit + integration tests (Vitest)
npm run lint      # ESLint on the plugin's own sources
npm run fmt       # Prettier
npm run build     # compile TypeScript to dist/

Pre-commit hooks (via yorkie and lint-staged) run Prettier and ESLint on staged files. Releases are managed with release-please through GitHub Actions.

License

Apache-2.0

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors

Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.