{"id":11514,"library":"oxfmt","title":"Oxc Formatter (oxfmt)","description":"Oxfmt is a high-performance, zero-configuration code formatter for JavaScript and TypeScript, built as part of the broader Oxidation Compiler (Oxc) project. It offers a fast alternative to tools like Prettier, leveraging Rust for superior performance. The package is currently at `v0.45.0` and is under active development, with frequent releases often tied to its companion linter, Oxlint, and the underlying Oxc Rust crates (typically weekly to bi-weekly for the monorepo). Its primary differentiators are its exceptional speed, minimal configuration overhead (enforcing an opinionated style), and its tight integration within the Oxc ecosystem, which aims to provide a complete suite of JavaScript tooling written in Rust. It ships with TypeScript types, supporting both programmatic usage via `formatSync` and `formatAsync` functions, and a direct command-line interface.","status":"active","version":"0.45.0","language":"javascript","source_language":"en","source_url":"https://github.com/oxc-project/oxc","tags":["javascript","formatter","oxc","oxfmt","prettier","typescript"],"install":[{"cmd":"npm install oxfmt","lang":"bash","label":"npm"},{"cmd":"yarn add oxfmt","lang":"bash","label":"yarn"},{"cmd":"pnpm add oxfmt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime requirement for the native Node-API bindings, specifying compatible Node.js versions.","package":"node","optional":false}],"imports":[{"note":"Synchronous formatting function, suitable for immediate string processing.","wrong":"const { formatSync } = require('oxfmt');","symbol":"formatSync","correct":"import { formatSync } from 'oxfmt';"},{"note":"Asynchronous formatting function, recommended for larger files or non-blocking operations.","wrong":"const { formatAsync } = require('oxfmt');","symbol":"formatAsync","correct":"import { formatAsync } from 'oxfmt';"},{"note":"TypeScript type definition for options that can be passed to the format functions. Primarily for type checking, not a runtime value.","wrong":"import { FormatterOptions } from 'oxfmt';","symbol":"FormatterOptions","correct":"import type { FormatterOptions } from 'oxfmt';"}],"quickstart":{"code":"import { formatSync, formatAsync } from 'oxfmt';\nimport { readFileSync, writeFileSync, rmSync } from 'node:fs';\nimport { join } from 'node:path';\n\n// Example: Synchronously format a string\nconst messyCode = `function  add ( a, b )  { return  a  +  b; }`;\nconst formattedCodeSync = formatSync(messyCode);\nconsole.log('Synchronously formatted code:', formattedCodeSync);\n// Expected output: \"function add(a, b) { return a + b; }\"\n\n// Example: Asynchronously format a file\nasync function formatFile(filePath: string) {\n  try {\n    const sourceText = readFileSync(filePath, 'utf-8');\n    const formattedText = await formatAsync(sourceText);\n    console.log(`Formatted ${filePath}:\\n`, formattedText);\n    // Optionally write back to file\n    // writeFileSync(filePath, formattedText);\n  } catch (error) {\n    console.error(`Error formatting file ${filePath}:`, error);\n  }\n}\n\n// Create a dummy file for demonstration\nconst dummyFilePath = join(process.cwd(), 'temp-file.js');\nwriteFileSync(dummyFilePath, `\n  const   foo    =     \"bar\"   ;\n  if   (  true  )  { console.log(foo)  ; }`);\n\nconsole.log('Attempting to format a dummy file...');\nformatFile(dummyFilePath).then(() => {\n  console.log('Formatting complete for dummy file.');\n  // Clean up dummy file\n  rmSync(dummyFilePath);\n});","lang":"typescript","description":"This quickstart demonstrates how to use `oxfmt` programmatically to format both a string synchronously and a local file asynchronously, showcasing its core API functions."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<20.19.0 || >=22.12.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"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."},{"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.","cause":"The `oxfmt` executable is not in the system's PATH, or the package is not installed correctly for direct command-line access.","error":"command not found: oxfmt"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'formatSync') at Object.<anonymous> (/path/to/your/script.js:L:C)"}],"ecosystem":"npm"}