Oxc Formatter (oxfmt)

Common errors

• Error: The module '\path\to\node_modules\oxfmt\oxfmt.node' was compiled against a different Node.js version using NODE_MODULE_VERSION N. This version of Node.js requires NODE_MODULE_VERSION M. Please update your Node.js installation or recompile the module.

  cause The native Rust addon for `oxfmt` was built for a Node.js ABI version that is incompatible with the currently running Node.js runtime.
  fix Upgrade or downgrade your Node.js version to match the `engines` requirement specified in `oxfmt`'s `package.json` (`^20.19.0 || >=22.12.0`). Use `nvm` or `volta` to manage Node.js versions, and reinstall `oxfmt` after changing versions to ensure the correct native binary is used.

• command not found: oxfmt

  cause The `oxfmt` executable is not in the system's PATH, or the package is not installed correctly for direct command-line access.
  fix Use `npx oxfmt@latest` to run the latest version without global installation. If you've installed it locally (`npm install oxfmt`), you can run it via `npx oxfmt` (which resolves from `node_modules/.bin`) or by adding `node_modules/.bin` to your PATH.

• TypeError: Cannot read properties of undefined (reading 'formatSync') at Object.<anonymous> (/path/to/your/script.js:L:C)

  cause Attempting to access `formatSync` (or `formatAsync`) from the `oxfmt` package using incorrect import syntax for the module system (CommonJS vs. ESM) or when the symbol is not correctly exported/resolved.
  fix For ESM projects, use named imports: `import { formatSync } from 'oxfmt';`. For CommonJS projects (Node.js versions without ESM support or older configurations), use `const { formatSync } = require('oxfmt');`. Verify that you are importing the correct symbol name.

Warnings

• breaking The `oxc` project undergoes rapid development, leading to frequent breaking changes in its underlying Rust crates (`oxc_allocator`, `oxc_span`, `oxc_str`, etc.). While `oxfmt`'s Node-API surface aims for stability, deep dependencies on `oxc`'s internal structures could lead to unexpected behavioral changes or errors with new `oxfmt` versions if the underlying `oxc` crates introduce incompatible changes.
  Fix: Always test `oxfmt` upgrades in a staging environment. Regularly consult the `oxc-project` GitHub releases for detailed breaking changes in `crates_vX.Y.Z` affecting core functionalities, as these may have downstream impacts on `oxfmt`.
• gotcha Oxfmt is designed for zero-configuration by default, meaning it has a strong opinion on formatting styles and provides very few options for customization compared to tools like Prettier. Users accustomed to fine-grained control over formatting rules may find this limiting.
  Fix: Embrace the opinionated style or evaluate if `oxfmt`'s defaults align with your project's coding standards. There is currently no support for external configuration files like `.prettierrc`.
• gotcha The `oxfmt` package requires specific Node.js versions due to its native (Rust-based) Node-API bindings. Running `oxfmt` on an unsupported Node.js version will result in a runtime error stating the module was compiled against a different Node.js ABI.
  Fix: Ensure your Node.js environment matches the specified `engines` requirement (`^20.19.0 || >=22.12.0`). Use a version manager like `nvm` or `volta` to easily switch Node.js versions and avoid ABI mismatches.
• gotcha As a performance-focused tool implemented in Rust, any unexpected runtime crashes or unhandled exceptions within `oxfmt` may manifest as native Node.js process crashes (e.g., segmentation faults), which can be harder to debug than typical JavaScript errors.
  Fix: Report issues to the `oxc-project` GitHub repository with detailed reproduction steps and any available stack traces. Ensure you are running the latest stable version of `oxfmt`.

Install

• npm install oxfmt npm
• yarn add oxfmt yarn
• pnpm add oxfmt pnpm

Imports

• formatSync
  wrong:

  const { formatSync } = require('oxfmt');

  correct:

  import { formatSync } from 'oxfmt';

  Synchronous formatting function, suitable for immediate string processing.
• formatAsync
  wrong:

  const { formatAsync } = require('oxfmt');

  correct:

  import { formatAsync } from 'oxfmt';

  Asynchronous formatting function, recommended for larger files or non-blocking operations.
• FormatterOptions
  wrong:

  import { FormatterOptions } from 'oxfmt';

  correct:

  import type { FormatterOptions } from 'oxfmt';

  TypeScript type definition for options that can be passed to the format functions. Primarily for type checking, not a runtime value.

Quickstart

This quickstart demonstrates how to use `oxfmt` programmatically to format both a string synchronously and a local file asynchronously, showcasing its core API functions.

import { formatSync, formatAsync } from 'oxfmt';
import { readFileSync, writeFileSync, rmSync } from 'node:fs';
import { join } from 'node:path';

// Example: Synchronously format a string
const messyCode = `function  add ( a, b )  { return  a  +  b; }`;
const formattedCodeSync = formatSync(messyCode);
console.log('Synchronously formatted code:', formattedCodeSync);
// Expected output: "function add(a, b) { return a + b; }"

// Example: Asynchronously format a file
async function formatFile(filePath: string) {
  try {
    const sourceText = readFileSync(filePath, 'utf-8');
    const formattedText = await formatAsync(sourceText);
    console.log(`Formatted ${filePath}:\n`, formattedText);
    // Optionally write back to file
    // writeFileSync(filePath, formattedText);
  } catch (error) {
    console.error(`Error formatting file ${filePath}:`, error);
  }
}

// Create a dummy file for demonstration
const dummyFilePath = join(process.cwd(), 'temp-file.js');
writeFileSync(dummyFilePath, `
  const   foo    =     "bar"   ;
  if   (  true  )  { console.log(foo)  ; }`);

console.log('Attempting to format a dummy file...');
formatFile(dummyFilePath).then(() => {
  console.log('Formatting complete for dummy file.');
  // Clean up dummy file
  rmSync(dummyFilePath);
});