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.

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

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

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",
		},
	},
];

The plugin provides one language per shell dialect:

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

Each rule mirrors a well-known ShellCheck check.

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

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

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"

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');

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.

Apache-2.0