Dockerfile Language Server

Common errors

• SyntaxError: Unexpected token '.' at wrapSafe (internal/modules/cjs/loader.js:915:16)

  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.
  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.

• Error: spawn docker-langserver ENOENT

  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.
  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.

• Language server cannot start right after installing the extension

  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.
  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.

Warnings

• breaking 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).
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install dockerfile-language-server-nodejs npm
• yarn add dockerfile-language-server-nodejs yarn
• pnpm add dockerfile-language-server-nodejs pnpm

Imports

• startServer

  import { startServer } from 'dockerfile-language-server-nodejs/lib/server';

  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.
• DockerfileLanguageServerOptions

  import type { DockerfileLanguageServerOptions } from 'dockerfile-language-server-nodejs/lib/server';

  Represents the configuration options that can be passed to the `startServer` function, allowing for customization of server behavior.
• docker-langserver binary (CLI)
  wrong:

  import { main } from 'dockerfile-language-server-nodejs/lib/main';

  correct:
  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.

Quickstart

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.

import { spawn } from 'child_process';
import { createConnection, ProposedFeatures } from 'vscode-languageserver/node';
import type { InitializeParams } from 'vscode-languageserver';

const serverProcess = spawn('docker-langserver', ['--stdio'], {
  stdio: ['pipe', 'pipe', 'inherit'],
  windowsHide: true
});

const connection = createConnection(ProposedFeatures.all, serverProcess.stdin, serverProcess.stdout);

connection.onInitialize(async (params: InitializeParams) => {
  console.log('LSP Client: Received initialize request from server.');
  return {
    capabilities: {
      textDocumentSync: 1, // Full
      completionProvider: { resolveProvider: true, triggerCharacters: [' ', '.', '-', ':'] },
      hoverProvider: true,
      definitionProvider: true,
      documentFormattingProvider: true,
      diagnosticProvider: { interFileDependencies: false, workspaceDiagnostics: false }
    },
    serverInfo: { name: 'Test Dockerfile LSP Client', version: '1.0.0' }
  };
});

connection.onInitialized(() => {
  console.log('LSP Client: Initialized. Language Server is ready.');
});

connection.listen();

serverProcess.on('exit', (code, signal) => {
  console.log(`LSP Server process exited with code ${code} and signal ${signal}`);
  process.exit(code || 0);
});

serverProcess.on('error', (err) => {
  console.error('Failed to start LSP server process:', err);
  process.exit(1);
});

console.log('LSP Client: Connecting to Dockerfile Language Server...');
// In a real scenario, you'd send a didOpen notification here for a Dockerfile.
// For this quickstart, we just establish the connection.