Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
formatSync
✓ import { formatSync } from 'oxfmt';
✗ const { formatSync } = require('oxfmt');
Synchronous formatting function, suitable for immediate string processing.
formatAsync
✓ import { formatAsync } from 'oxfmt';
✗ const { formatAsync } = require('oxfmt');
Asynchronous formatting function, recommended for larger files or non-blocking operations.
FormatterOptions
✓ import type { FormatterOptions } from 'oxfmt';
✗ import { FormatterOptions } from 'oxfmt';
TypeScript type definition for options that can be passed to the format functions. Primarily for type checking, not a runtime value.
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);
});
oxfmt --version
Debug
Known issues
breakingThe `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.fixAlways 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`.
affects: >=0.1.0
gotchaOxfmt 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.fixEmbrace 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`.
affects: >=0.1.0
gotchaThe `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.fixEnsure 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.
affects: <20.19.0 || >=22.12.0
gotchaAs 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.fixReport 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`.
affects: >=0.1.0
Errors
Common errors & fixes
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.
The native Rust addon for `oxfmt` was built for a Node.js ABI version that is incompatible with the currently running Node.js runtime.
fixUpgrade 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
The `oxfmt` executable is not in the system's PATH, or the package is not installed correctly for direct command-line access.
fixUse `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)
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.
fixFor 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. Audit
Dependencies
noderequiredRuntime requirement for the native Node-API bindings, specifying compatible Node.js versions.