{"id":15980,"library":"clang-format-node","title":"Clang Format Node Wrapper","description":"clang-format-node is a Node.js wrapper that provides programmatic access to the LLVM project's `clang-format` and `git-clang-format` native binaries. The current stable version is 3.0.2, bundling LLVM clang-format version 22.1.3. This package securely builds and bundles these native binaries directly from official LLVM source code, eliminating third-party binary dependencies and offering full GitHub Actions Attestation and npm Build Provenances for enhanced supply chain security. It also includes separate packages within its monorepo, `clang-format-git` for standalone Git integration without Python, and `clang-format-git-python` for the original Python script wrapper. Release cycles typically align with new LLVM clang-format versions, ensuring access to the latest formatting capabilities and bug fixes. It is inspired by `angular/clang-format` but aims for a more streamlined and secure integration into Node.js and npm workflows.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/lumirlumir/npm-clang-format-node","tags":["javascript","clang-format","clang","cli","format","formatter","lint","linter","cpplint","typescript"],"install":[{"cmd":"npm install clang-format-node","lang":"bash","label":"npm"},{"cmd":"yarn add clang-format-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add clang-format-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { format } = require('clang-format-node');","symbol":"format","correct":"import { format } from 'clang-format-node';"},{"note":"Used for direct execution of the underlying `clang-format` binary with custom arguments. It is a named export, not a default.","wrong":"import execClangFormat from 'clang-format-node';","symbol":"execClangFormat","correct":"import { execClangFormat } from 'clang-format-node';"},{"note":"Utility function to retrieve the version of the bundled `clang-format` binary. This is a named export.","symbol":"getClangFormatVersion","correct":"import { getClangFormatVersion } from 'clang-format-node';"},{"note":"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.","symbol":"FormatOptions","correct":"import type { FormatOptions } from 'clang-format-node';"}],"quickstart":{"code":"import { format } from 'clang-format-node';\n\nasync function applyFormatting() {\n  const code = `#include <iostream>\\n\\nint main() { std::cout << \"Hello, World!\" << std::endl; return 0; }\\n`;\n  try {\n    // Formats the C++ code string using the 'Google' style\n    // 'fallbackStyle' ensures a default is used if 'style' isn't recognized or available.\n    const formattedCode = await format(code, { \n      style: 'Google', \n      fallbackStyle: 'LLVM'\n    });\n    console.log('Original Code:\\n', code);\n    console.log('Formatted Code (Google Style):\\n', formattedCode);\n\n    // Example of formatting with a different style (e.g., 'Mozilla')\n    const anotherFormattedCode = await format(code, { \n      style: 'Mozilla', \n      fallbackStyle: 'LLVM'\n    });\n    console.log('Formatted Code (Mozilla Style):\\n', anotherFormattedCode);\n\n  } catch (error) {\n    console.error('Failed to format code:', error);\n    // Specific error handling for clang-format issues\n    if (error instanceof Error && error.message.includes('clang-format failed')) {\n        console.error('The clang-format binary returned an error. Check input or style options.');\n    }\n  }\n}\n\napplyFormatting();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<16"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Error: spawn clang-format ENOENT"},{"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.","cause":"Attempting to use ES Module `import` syntax in a CommonJS (`require`) environment. `clang-format-node` v3+ is primarily designed for ESM.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"The `format` function was invoked with a non-string value (e.g., `null`, `undefined`, an object, or an array) for the `code` argument.","error":"TypeError: The 'format' function requires a string input."}],"ecosystem":"npm"}