Unified Language Server

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` an ESM-only package.
  fix Change `const { createUnifiedLanguageServer } = require('unified-language-server');` to `import { createUnifiedLanguageServer } from 'unified-language-server';` and ensure `"type": "module"` is set in your `package.json`.

• Error: Cannot find module 'remark' from '/path/to/language-server'

  cause The specified `processorName` (e.g., 'remark') is not installed in the environment where the language server is executing.
  fix Ensure the processor package (e.g., `remark`) is listed in your language server's `dependencies` and run `npm install`.

• TypeError: options.defaultProcessor is not a function

  cause `defaultProcessor` was passed an incorrect value or the imported processor is not the expected `unified` function.
  fix Verify that `defaultProcessor` receives a valid `unified` processor instance (e.g., `remark`) and that its named export is correctly imported (e.g., `import { remark } from 'remark';`).

• Language server failed to initialize: Configuration option 'requireConfig' is not recognized.

  cause Using an outdated client or language server definition that doesn't recognize newer configuration options.
  fix Ensure both the `unified-language-server` package and the editor client integration are updated to their latest versions to support all configuration features.

Warnings

• breaking Support for Node.js 12 was removed. Ensure your environment runs Node.js 16.0 or higher.
  Fix: Upgrade your Node.js runtime to version 16.0 or newer.
• breaking The package transitioned to ESM-only. CommonJS `require()` is no longer supported for importing `unified-language-server`.
  Fix: Update imports to use `import` statements and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
• breaking Updated `unified-engine` dependency, which notably introduced support for YAML 1.2 in configuration files. This might affect how existing configuration files are parsed if they rely on older YAML features or if new YAML 1.2 syntax is introduced.
  Fix: Review existing configuration files (`.remarkrc`, etc.) to ensure compatibility with `unified-engine`'s updated YAML parser. Update YAML configurations if necessary.
• breaking Refactored to use `unist-util-lsp` internally. While not a direct API change for most users, this signals significant internal architecture updates which could affect custom extensions or deep integrations.
  Fix: No direct fix needed for standard usage. If you have custom extensions interacting with internal structures, verify compatibility or consult the `unist-util-lsp` documentation.
• gotcha If `options.processorName` cannot be found locally in `node_modules`, a warning is shown. This can happen if the processor (e.g., `remark`) is not installed as a dependency in the workspace where the language server is running.
  Fix: Always ensure that the `processorName` specified (e.g., `remark`) is correctly listed and installed as a dependency in your language server's `package.json` or the user's project `node_modules`.

Install

• npm install unified-language-server npm
• yarn add unified-language-server yarn
• pnpm add unified-language-server pnpm

Imports

• createUnifiedLanguageServer
  wrong:

  const { createUnifiedLanguageServer } = require('unified-language-server')

  correct:

  import { createUnifiedLanguageServer } from 'unified-language-server'

  Package is ESM-only since v3.0.0, requiring `import` syntax and a Node.js `type: "module"` package configuration.
• remark
  wrong:

  import remark from 'remark'

  correct:

  import { remark } from 'remark'

  The `remark` package exports its processor as a named export, not a default export.
• LanguageServerOptions
  wrong:

  import { LanguageServerOptions } from 'unified-language-server'

  correct:

  import type { LanguageServerOptions } from 'unified-language-server'

  TypeScript type import. Use `import type` to ensure it's not bundled as runtime code, especially if configuring a language server in TypeScript.

Quickstart

Demonstrates how to create a basic language server for `remark` using `unified-language-server`, including configuration options for file handling.

import { remark } from 'remark';
import { createUnifiedLanguageServer } from 'unified-language-server';

// Set the process title for easier identification in system monitors
process.title = 'my-remark-language-server';

// Create and start the language server
createUnifiedLanguageServer({
  // Name of ignore files (e.g., '.remarkignore')
  ignoreName: '.remarkignore',
  // Field in package.json to look for configuration
  packageField: 'remarkConfig',
  // Prefix for plugin names (e.g., 'remark-lint-')
  pluginPrefix: 'remark',
  // Name of the RC file (e.g., '.remarkrc')
  rcName: '.remarkrc',
  // The package ID of the expected processor (e.g., 'remark')
  processorName: 'remark',
  // The specifier to get the processor on the resolved module (e.g., 'remark' for named export)
  processorSpecifier: 'remark',
  // Optional fallback processor if `processorName` isn't found locally
  defaultProcessor: remark
});

console.log('Remark language server started. Waiting for client connection...');