{"id":10755,"library":"dockerfile-language-server-nodejs","title":"Dockerfile Language Server","description":"The Dockerfile Language Server provides robust Language Server Protocol (LSP) support for Dockerfiles, enhancing developer experience across various code editors. Written in TypeScript and powered by Node.js, it offers features such as code completion, diagnostics, formatting, hover information, code actions, and semantic highlighting. Currently stable at version `0.15.0`, the project sees a consistent release cadence driven by updates to its core logic libraries. Unlike monolithic language servers, this package is designed specifically as the LSP server frontend, delegating the heavy lifting of Dockerfile parsing and language intelligence to the separate `dockerfile-ast`, `dockerfile-language-service`, and `dockerfile-utils` libraries. This architecture allows for a lean server implementation and flexible integration, as demonstrated by its adoption in popular extensions like VS Code Docker, Sublime Text LSP-dockerfile, and clients for Zed, Atom, Sourcegraph, Theia, and Emacs.","status":"active","version":"0.15.0","language":"javascript","source_language":"en","source_url":"https://github.com/rcjsuen/dockerfile-language-server-nodejs","tags":["javascript","language","server","docker","dockerfile","moby"],"install":[{"cmd":"npm install dockerfile-language-server-nodejs","lang":"bash","label":"npm"},{"cmd":"yarn add dockerfile-language-server-nodejs","lang":"bash","label":"yarn"},{"cmd":"pnpm add dockerfile-language-server-nodejs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Language Server Protocol implementation, providing the foundational API for LSP communication.","package":"vscode-languageserver"},{"reason":"Provides document synchronization utilities crucial for LSP clients and servers to manage text document states.","package":"vscode-languageserver-textdocument"},{"reason":"Handles URI parsing and manipulation, essential for resolving file paths and resources within the LSP context.","package":"vscode-uri"},{"reason":"Parses Dockerfiles into an Abstract Syntax Tree (AST), enabling structured analysis and manipulation of Dockerfile content.","package":"dockerfile-ast"},{"reason":"Implements the core language intelligence functions, such as code completion, hovers, and diagnostics, for Dockerfiles.","package":"dockerfile-language-service"},{"reason":"Provides utilities for Dockerfile validation and formatting, often used for linting and code style enforcement.","package":"dockerfile-utils"},{"reason":"Defines the Language Server Protocol types and interfaces; listed as a peer dependency.","package":"vscode-languageserver-protocol","optional":true}],"imports":[{"note":"This function is used to programmatically start the language server within a Node.js process, accepting writable and readable streams for LSP communication (e.g., `process.stdout` and `process.stdin` for stdio). This is for embedding the server, not typical client-side use.","symbol":"startServer","correct":"import { startServer } from 'dockerfile-language-server-nodejs/lib/server';"},{"note":"Represents the configuration options that can be passed to the `startServer` function, allowing for customization of server behavior.","symbol":"DockerfileLanguageServerOptions","correct":"import type { DockerfileLanguageServerOptions } from 'dockerfile-language-server-nodejs/lib/server';"},{"note":"The primary way to interact with the Dockerfile Language Server is via its `docker-langserver` CLI executable after global installation (`npm install -g`). Directly importing and executing `main` is generally not recommended as it bypasses the intended CLI entry point and might not handle argument parsing or communication streams correctly.","wrong":"import { main } from 'dockerfile-language-server-nodejs/lib/main';","symbol":"docker-langserver binary (CLI)"}],"quickstart":{"code":"import { spawn } from 'child_process';\nimport { createConnection, ProposedFeatures } from 'vscode-languageserver/node';\nimport type { InitializeParams } from 'vscode-languageserver';\n\nconst serverProcess = spawn('docker-langserver', ['--stdio'], {\n  stdio: ['pipe', 'pipe', 'inherit'],\n  windowsHide: true\n});\n\nconst connection = createConnection(ProposedFeatures.all, serverProcess.stdin, serverProcess.stdout);\n\nconnection.onInitialize(async (params: InitializeParams) => {\n  console.log('LSP Client: Received initialize request from server.');\n  return {\n    capabilities: {\n      textDocumentSync: 1, // Full\n      completionProvider: { resolveProvider: true, triggerCharacters: [' ', '.', '-', ':'] },\n      hoverProvider: true,\n      definitionProvider: true,\n      documentFormattingProvider: true,\n      diagnosticProvider: { interFileDependencies: false, workspaceDiagnostics: false }\n    },\n    serverInfo: { name: 'Test Dockerfile LSP Client', version: '1.0.0' }\n  };\n});\n\nconnection.onInitialized(() => {\n  console.log('LSP Client: Initialized. Language Server is ready.');\n});\n\nconnection.listen();\n\nserverProcess.on('exit', (code, signal) => {\n  console.log(`LSP Server process exited with code ${code} and signal ${signal}`);\n  process.exit(code || 0);\n});\n\nserverProcess.on('error', (err) => {\n  console.error('Failed to start LSP server process:', err);\n  process.exit(1);\n});\n\nconsole.log('LSP Client: Connecting to Dockerfile Language Server...');\n// In a real scenario, you'd send a didOpen notification here for a Dockerfile.\n// For this quickstart, we just establish the connection.\n","lang":"typescript","description":"This quickstart demonstrates how to programmatically spawn the `docker-langserver` CLI as a child process and establish an LSP connection over standard I/O (stdio). It sets up a minimal `vscode-languageserver` client to send an `initialize` request, showcasing how an editor extension would interact with the server."},"warnings":[{"fix":"Ensure your Node.js environment is updated to at least Node.js 16 or newer. The latest stable version typically supports current LTS Node.js releases.","message":"Support for Node.js 14 was removed in version `0.10.0` and Node.js 12 in `0.9.0`. Running the server with these older Node.js versions will result in runtime errors due to incompatible JavaScript syntax (e.g., optional chaining).","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Ensure your Node.js environment and bundler configurations (if applicable) correctly handle CommonJS (CJS) modules. For most standard Node.js setups, this change should be transparent.","message":"The internal `dockerfile-language-service` library, which this server consumes, transitioned its build output from UMD to CJS in `0.15.0`. While this primarily affects direct consumers of `dockerfile-language-service`, it could lead to subtle module resolution issues if an environment is explicitly configured for UMD or has strict module resolution rules that do not correctly handle CJS.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Verify that your `PATH` environment variable includes the directory where global npm binaries are installed (e.g., `~/.npm-global/bin` or `/usr/local/bin`). Restart your terminal or editor after installation to refresh the PATH.","message":"When installing the Dockerfile Language Server globally via `npm install -g dockerfile-language-server-nodejs`, ensure that the `docker-langserver` executable is correctly added to your system's PATH. If not, client applications (like editor extensions) may fail to launch the server, reporting 'command not found' errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js runtime to a version that supports the required syntax. As of `0.15.0`, Node.js 16 or higher is recommended.","cause":"This error often indicates that the Node.js version running the server is too old to support modern JavaScript syntax (e.g., optional chaining or nullish coalescing) used by the language server or its dependencies.","error":"SyntaxError: Unexpected token '.' at wrapSafe (internal/modules/cjs/loader.js:915:16)"},{"fix":"Install the package globally using `npm install -g dockerfile-language-server-nodejs` and verify that the `docker-langserver` binary is accessible in your system's PATH. You may need to restart your terminal or shell.","cause":"The `docker-langserver` executable could not be found in the system's PATH, meaning either the package was not installed globally, or the PATH is not correctly configured.","error":"Error: spawn docker-langserver ENOENT"},{"fix":"Often, restarting the VS Code window (Developer: Reload Window) can resolve this. In some cases, adjusting extension activation order or disabling/re-enabling them may be necessary.","cause":"This can occur in VS Code environments if multiple Docker-related extensions (e.g., Docker DX and Container Tools) are installed and activated in a specific order, leading to a race condition or conflict during server startup.","error":"Language server cannot start right after installing the extension"}],"ecosystem":"npm"}