Bash Language Server

5.6.0 · active · verified Sun Apr 19

The Bash Language Server provides an IDE-like experience for Bash scripts by implementing the Language Server Protocol. It leverages Tree Sitter for parsing, and integrates with external tools like ShellCheck for linting, shfmt for formatting, and explainshell for documentation. The current stable version is 5.6.0. It follows a frequent release cadence, indicated by multiple minor and patch releases within short periods. A key differentiator is its comprehensive integration with established Bash tooling, offering features such as jump to definition, find references, code completion, diagnostics, and formatting. It requires Node.js version 16 or newer to run, and ships with TypeScript types, allowing for type-safe client development or custom integrations. Primarily used as a standalone server, it's typically invoked by editor clients rather than imported as a library.

Common errors

```
bash-language-server: command not found
```
cause The package is not installed globally or the npm global bin directory is not in your system's PATH.

fix Install globally using `npm install -g bash-language-server` or ensure your PATH includes the npm global bins (e.g., `export PATH="$(npm config get prefix)/bin:$PATH"`).
```
Error: Node.js version too old. Expected >=16. Got 14.x.y
```
cause The installed Node.js version does not meet the minimum requirement of Node.js 16 or higher.

fix Upgrade Node.js to version 16 or higher. Using `nvm` is recommended: `nvm install 18 && nvm use 18`.
```
[LSP Error] Failed to start bash-language-server. Make sure it's installed and executable.
```
cause Your editor's LSP client cannot locate or execute the `bash-language-server` binary.

fix Verify global installation with `bash-language-server --help` in your terminal and ensure the npm global bin directory is correctly configured in your system's PATH, especially for the environment your editor runs in.

Warnings

gotcha Full functionality, including linting and formatting, relies on external tools like ShellCheck and shfmt. Not installing these will result in missing features.
Fix: Install shellcheck (e.g., 'sudo apt install shellcheck') and shfmt (e.g., 'go install mvdan.cc/sh/cmd/shfmt@latest') via your system's package manager or appropriate installation method.
breaking Requires Node.js version 16 or newer. Older Node.js versions are not supported and will prevent the server from running.
Fix: Upgrade your Node.js installation to version 16 or later (e.g., using nvm: 'nvm install 18 && nvm use 18').
deprecated Prior to version 5.5.0, `shfmt` environment variable deprecation warnings could appear due to an underlying dependency. This was resolved in version 5.5.0.
Fix: Upgrade to bash-language-server version 5.5.0 or newer to resolve the `shfmt` environment variable deprecation warning.

Install

npm install bash-language-server npm
yarn add bash-language-server yarn
pnpm add bash-language-server pnpm

Imports

startServer
```
import { startServer } from 'bash-language-server/lib/server';
```
This is the core server entry point, typically invoked by the CLI. Direct import is for advanced use cases like embedding the server or custom test runners, and uses an internal path.
Settings
```
import { Settings } from 'bash-language-server/lib/config';
```
Imports the TypeScript interface for server configuration settings. Useful for type-checking when creating custom configuration providers or working with the server's internal structure.
Logger
```
import { Logger } from 'bash-language-server/lib/util/logger';
```
Provides the internal logger interface, useful if developing custom extensions or debugging server behavior programmatically. This is for advanced usage.

Quickstart

Demonstrates global installation verification and clarifies how the Bash Language Server is typically used via editor integrations rather than direct programmatic imports.

import { startServer } from 'bash-language-server/lib/server';
import { exec } from 'child_process';

// This package is primarily a CLI tool (bash-language-server start)
// for editor integration. The following demonstrates how to verify
// its global installation and provides a conceptual programmatic hook.

console.log('Verifying bash-language-server installation...');

exec('bash-language-server --version', (error, stdout, stderr) => {
  if (error) {
    console.error(`Error checking server version: ${error.message}`);
    console.error('Please ensure bash-language-server is installed globally: npm i -g bash-language-server');
    return;
  }
  if (stderr) {
    console.error(`Server stderr: ${stderr}`);
  }
  console.log(`Bash Language Server installed and version: ${stdout.trim()}`);
  console.log('\nTo use it, configure your editor (e.g., VS Code, Neovim) to use `bash-language-server start` as its LSP server command.');
  
  // For advanced, programmatic usage (e.g., custom testing or embedding),
  // one might theoretically import 'startServer' from 'bash-language-server/lib/server'.
  // However, this function expects a Language Server Protocol connection object
  // (e.g., from 'vscode-languageserver/node') which is outside a simple quickstart.
  // Example of how it *might* be used in a highly custom setup:
  // const connection = createConnection(ProposedFeatures.all);
  // connection.onInitialize((params) => { /* ... */ });
  // connection.listen();
  // startServer(connection);
});

view raw JSON →