Clang Format Node Wrapper

Common errors

• Error: spawn clang-format ENOENT

  cause The underlying `clang-format` native binary could not be found or executed by Node.js, often due to an unsupported platform/architecture, corrupted installation, or restrictive execution environment.
  fix Ensure your OS and CPU architecture are supported by `clang-format-node`. Check the integrity of your `node_modules` and try reinstalling the package. If in a container or CI, verify permissions for binary execution. Consult the official documentation's 'Supported' section for compatible environments.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES Module `import` syntax in a CommonJS (`require`) environment. `clang-format-node` v3+ is primarily designed for ESM.
  fix Configure your project to use ES Modules (e.g., by adding `"type": "module"` to your `package.json`) or use a transpiler (like TypeScript or Babel) to convert ESM syntax to CommonJS if you must target a CJS environment.

• TypeError: The 'format' function requires a string input.

  cause The `format` function was invoked with a non-string value (e.g., `null`, `undefined`, an object, or an array) for the `code` argument.
  fix Always pass a string representing the code to be formatted as the first argument to the `format` function. Implement input validation before calling the formatter.

Warnings

• breaking Version 3.0.0 introduced a significant breaking change by upgrading the bundled LLVM `clang-format` binary from `llvmorg-21.1.8` to `llvmorg-22.1.1`. This upgrade may result in subtle changes to how code is formatted, potentially causing diffs in previously formatted files, and requires Node.js >= 16. Projects relying on specific formatting behavior should thoroughly review their configurations and output after upgrading.
  Fix: Review your `.clang-format` configuration files against the new LLVM version's capabilities, as formatting rules may have evolved. Test formatting output thoroughly before upgrading in production. Ensure your Node.js environment meets the `>=16` requirement.
• gotcha This package bundles native `clang-format` binaries tailored for specific OS platforms and architectures. While comprehensive support is offered, specific environments (e.g., custom Linux distributions, sandboxed CI environments, or unsupported architectures) might encounter issues with binary execution or path resolution. This can lead to `ENOENT` errors or unexpected behavior if the binary cannot be located or run.
  Fix: Verify that your operating system and architecture are explicitly listed as supported in the package's documentation. In case of binary execution issues, ensure the Node.js process has proper execution permissions and that no security software is interfering. Consider using a supported Docker image for consistent environments in CI.
• gotcha The `clang-format-node` project is a monorepo containing three distinct packages: `clang-format-node` (the core formatter), `clang-format-git` (git integration without Python), and `clang-format-git-python` (git integration with Python). Installing the incorrect package can lead to missing functionality or unnecessary dependencies.
  Fix: For general code formatting, install `clang-format-node`. If you need `git-clang-format` functionality and want to avoid a Python dependency, install `clang-format-git`. If you prefer the original Python-dependent `git-clang-format` wrapper, install `clang-format-git-python`.
• gotcha The package officially supports Node.js version 16 and above. While it might function on slightly older versions due to not relying on the very latest Node.js features, using it with Node.js versions below 16 is not officially tested or supported and may lead to installation failures or runtime errors due to engine compatibility checks.
  Fix: Upgrade your Node.js environment to version 16 or higher. Tools like `nvm` (Node Version Manager) can help manage different Node.js versions on your system.

Install

• npm install clang-format-node npm
• yarn add clang-format-node yarn
• pnpm add clang-format-node pnpm

Imports

• format
  wrong:

  const { format } = require('clang-format-node');

  correct:

  import { format } from 'clang-format-node';

  The primary function for formatting C/C++/Objective-C/C# code strings. This package is designed for ES Modules. Using CommonJS `require` for named exports directly will not work in v3+ without a transpiler.
• execClangFormat
  wrong:

  import execClangFormat from 'clang-format-node';

  correct:

  import { execClangFormat } from 'clang-format-node';

  Used for direct execution of the underlying `clang-format` binary with custom arguments. It is a named export, not a default.
• getClangFormatVersion

  import { getClangFormatVersion } from 'clang-format-node';

  Utility function to retrieve the version of the bundled `clang-format` binary. This is a named export.
• FormatOptions

  import type { FormatOptions } from 'clang-format-node';

  TypeScript type definition for options that can be passed to the `format` function. Always use `import type` for type-only imports to prevent bundling issues.

Quickstart

Demonstrates how to import and use the asynchronous `format` function to apply `clang-format` styling to a C++ code string using different style presets. It includes error handling for formatting failures.

import { format } from 'clang-format-node';

async function applyFormatting() {
  const code = `#include <iostream>\n\nint main() { std::cout << "Hello, World!" << std::endl; return 0; }\n`;
  try {
    // Formats the C++ code string using the 'Google' style
    // 'fallbackStyle' ensures a default is used if 'style' isn't recognized or available.
    const formattedCode = await format(code, { 
      style: 'Google', 
      fallbackStyle: 'LLVM'
    });
    console.log('Original Code:\n', code);
    console.log('Formatted Code (Google Style):\n', formattedCode);

    // Example of formatting with a different style (e.g., 'Mozilla')
    const anotherFormattedCode = await format(code, { 
      style: 'Mozilla', 
      fallbackStyle: 'LLVM'
    });
    console.log('Formatted Code (Mozilla Style):\n', anotherFormattedCode);

  } catch (error) {
    console.error('Failed to format code:', error);
    // Specific error handling for clang-format issues
    if (error instanceof Error && error.message.includes('clang-format failed')) {
        console.error('The clang-format binary returned an error. Check input or style options.');
    }
  }
}

applyFormatting();