Formatter (oxfmt)

Overview

Oxfmt is a blazing-fast code formatter that formats JavaScript, TypeScript, JSX, and TSX code. It’s designed to be Prettier-compatible while providing significantly better performance.

Prettier Compatible

Drop-in replacement for Prettier with matching output for most code.

Multiple Languages

Formats JavaScript, TypeScript, JSX, TSX, and TOML files.

Embedded Formatting

Supports Vue, Astro, Svelte, and other embedded JS/TS contexts.

Fast

Significantly faster than Prettier on large codebases.

Oxfmt is currently in beta. While it works well for many codebases, there may be edge cases where output differs from Prettier. Always test before adopting in production.

Quick Start

Run without installation

npx oxfmt@latest

Install locally

npm install -D oxfmt

Add to your package.json:

package.json

{
  "scripts": {
    "format": "oxfmt",
    "format:check": "oxfmt --check"
  }
}

CLI Usage

Basic Commands

# Format all files in current directory (writes in place)
oxfmt

# Format specific files or directories
oxfmt src/ lib/ index.js

# Check if files are formatted (doesn't write)
oxfmt --check

# List files that would be changed
oxfmt --list-different

# Format with custom config
oxfmt -c oxfmtrc.json

CLI Options

Mode Options
Config Options
Ignore Options
Runtime Options

Flag	Description
`--write`	Format and write files in place (default)
`--check`	Check if files are formatted without writing
`--list-different`	List files that would be changed
`--stdin-filepath <PATH>`	Read from stdin and specify file path for parsing
`--lsp`	Start language server protocol server
`--init`	Initialize `.oxfmtrc.json` with default values
`--migrate <SOURCE>`	Migrate configuration from Prettier or Biome

Flag	Description
`-c, --config <PATH>`	Path to configuration file

Flag	Description
`--ignore-path <PATH>`	Path to ignore file(s) (can be specified multiple times)
`--with-node-modules`	Format code in node_modules (skipped by default)

Flag	Description
`--threads <INT>`	Number of threads to use (defaults to CPU cores)
`--no-error-on-unmatched-pattern`	Don’t exit with error when pattern is unmatched

Glob Patterns

Oxfmt supports glob patterns for flexible file selection:

# Format all TypeScript files
oxfmt "**/*.ts"

# Format JavaScript and TypeScript
oxfmt "**/*.{js,ts,jsx,tsx}"

# Exclude test files
oxfmt "src/**/*.ts" "!**/*.test.ts"

# Quote patterns to prevent shell expansion
oxfmt '**/*.ts'

Stdin/Stdout

Format code via stdin:

# Format from stdin
echo "const x=1;" | oxfmt --stdin-filepath=file.js

# Use in a pipeline
cat messy.js | oxfmt --stdin-filepath=messy.js > formatted.js

Configuration

Configuration File

Create .oxfmtrc.json in your project root:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "ignorePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.min.js"
  ]
}

Formatting Options

Basic Options
Quote & Spacing
Advanced
Sort Imports

Option	Type	Default	Description
`printWidth`	number	80	Maximum line length
`tabWidth`	number	2	Number of spaces per indentation level
`useTabs`	boolean	false	Use tabs instead of spaces
`semi`	boolean	true	Add semicolons at end of statements
`singleQuote`	boolean	false	Use single quotes instead of double

Option	Type	Default	Description
`quoteProps`	string	”as-needed”	Quote object properties: “as-needed”, “consistent”, “preserve”
`jsxSingleQuote`	boolean	false	Use single quotes in JSX
`bracketSpacing`	boolean	true	Add spaces inside object braces
`bracketSameLine`	boolean	false	Put `>` on same line in JSX

Option	Type	Default	Description
`trailingComma`	string	”all”	Trailing commas: “all”, “es5”, “none”
`arrowParens`	string	”always”	Arrow function parens: “always”, “avoid”
`endOfLine`	string	”lf”	Line ending: “lf”, “crlf”, “cr”, “auto”
`proseWrap`	string	”preserve”	Markdown wrap: “always”, “never”, “preserve”

Option	Type	Default	Description
`sortImports.enabled`	boolean	false	Enable import sorting
`sortImports.groups`	array	-	Custom import groups

Import Sorting Example:

{
  "sortImports": {
    "enabled": true,
    "groups": [
      ["^node:"],
      ["^react", "^vue"],
      ["^@/"],
      ["^\\."],
      ["^.*\\.(css\|scss)$"]
    ]
  }
}

EditorConfig Support

Oxfmt automatically reads .editorconfig files:

.editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2

[*.{js,ts,jsx,tsx}]
indent_size = 2

[*.md]
max_line_length = 80

Ignore Patterns

Configuration File
.prettierignore
Inline Comments

.oxfmtrc.json

{
  "ignorePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/coverage/**",
    "**/*.min.js",
    "!important-file.js"  // Negation
  ]
}

Oxfmt respects .prettierignore files:

.prettierignore

# Build outputs
dist
build
coverage

# Dependencies
node_modules

# Generated files
*.generated.ts

# Keep specific file
!src/important.js

Disable formatting for specific code:

// oxfmt-ignore
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
];

/* oxfmt-ignore */
function   unformatted  (  ) { }

Migration from Prettier

Automated Migration

# Migrate Prettier config to oxfmt
oxfmt --migrate prettier

This reads your .prettierrc or prettier.config.js and generates .oxfmtrc.json.

Compatibility

Oxfmt aims for Prettier compatibility:

Supported
Differences

All major formatting options
EditorConfig support
Ignore files (.prettierignore)
Glob patterns
Range formatting
Stdin/stdout formatting

Migration Steps

Install oxfmt

npm install -D oxfmt

Migrate configuration

npx oxfmt --migrate prettier

Test formatting

# Format in check mode first
npx oxfmt --check

# Review differences
git diff

Update scripts

package.json

{
  "scripts": {
    "format": "oxfmt",
    "format:check": "oxfmt --check"
  }
}

Update pre-commit hooks

package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": "oxfmt"
  }
}

Embedded Language Support

Oxfmt can format JavaScript/TypeScript in embedded contexts:

Vue Files

<template>
  <div>{{ message }}</div>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello'
    }
  }
}
</script>

Astro Files

---
import Component from './Component.astro';
const items = [1, 2, 3];
---

<div>{items.map(i => <span>{i}</span>)}</div>

Svelte Files

<script>
  let count = 0;
  $: doubled = count * 2;
</script>

<button on:click={() => count++}>
  Count: {count}
</button>

Special Features

Import Sorting

Enable automatic import sorting:

.oxfmtrc.json

{
  "sortImports": {
    "enabled": true,
    "groups": [
      ["^node:"],           // Node.js built-ins
      ["^react", "^vue"],   // Frameworks
      ["^@/"],              // Aliases
      ["^\\."],              // Relative imports
      ["^.*\\.(css|scss)$"] // Styles
    ]
  }
}

Before:

import { Button } from './Button';
import React from 'react';
import fs from 'node:fs';
import styles from './styles.css';

After:

import fs from 'node:fs';
import React from 'react';
import { Button } from './Button';
import styles from './styles.css';

Package.json Sorting

Automatically sorts package.json fields according to common conventions.

Language Server Protocol

Oxfmt includes a language server for editor integration:

# Start LSP server
oxfmt --lsp

Editor Integration

VS Code
Neovim
Other Editors

Install the oxc VS Code extension:

settings.json

{
  "[javascript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "editor.formatOnSave": true
}

require('lspconfig').oxc_language_server.setup({
  cmd = { 'oxfmt', '--lsp' },
  filetypes = { 
    'javascript', 'javascriptreact', 
    'typescript', 'typescriptreact',
    'vue', 'astro', 'svelte'
  },
  root_dir = require('lspconfig.util').root_pattern(
    '.oxfmtrc.json', 
    'package.json', 
    '.git'
  ),
})

Configure your editor’s LSP client to run oxfmt --lsp for supported file types.

CI/CD Integration

GitHub Actions

.github/workflows/format.yml

name: Format Check

on: [push, pull_request]

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx oxfmt --check

Pre-commit Hook

Using lint-staged:

package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,vue,astro,svelte}": "oxfmt"
  }
}

Using husky:

# .husky/pre-commit
#!/bin/sh
npx lint-staged

Performance

Oxfmt is significantly faster than Prettier on large codebases:

Performance improvements vary by codebase size and complexity. Larger codebases see more significant gains.

Performance Tips

Use --threads to control parallelism
Leverage ignore patterns to skip unnecessary files
Use .oxfmtrc.json instead of JS config files for faster loading

API Reference

For programmatic usage:

CLI Reference

Complete CLI command reference

Configuration

Configure oxfmt with .oxfmtrc.jsonc

FAQ

Is oxfmt stable for production use?

Oxfmt is in beta. It works well for many codebases but may have edge cases where output differs from Prettier. Test thoroughly before adopting in production.

Will oxfmt match Prettier's output exactly?

Oxfmt aims for Prettier compatibility but may differ in edge cases. The goal is to be “Prettier-compatible” rather than “pixel-perfect” identical.

Can I use oxfmt with my Prettier plugins?

Currently, oxfmt doesn’t support Prettier plugins. Built-in support for popular file types (Vue, Astro, Svelte) is included.

Does oxfmt support formatting ranges?

Yes, when used via the language server or API. CLI range formatting is planned.

Why is my file not being formatted?

Check if the file is in ignorePatterns, matches .prettierignore, or is in node_modules. Use --with-node-modules to format node_modules.

Resources

GitHub Repository

Source code and issue tracker

npm Package

Install from npm

Discord Community

Get help and discuss features

Prettier Docs

Prettier documentation for comparison

Getting Started

Architecture

Tools

Using Oxc

Core Concepts

​Overview

Prettier Compatible

Multiple Languages

Embedded Formatting

Fast

​Quick Start

​Run without installation

​Install locally

​CLI Usage

​Basic Commands

​CLI Options

​Glob Patterns

​Stdin/Stdout

​Configuration

​Configuration File

​Formatting Options

​EditorConfig Support

​Ignore Patterns

​Migration from Prettier

​Automated Migration

​Compatibility

​Migration Steps

​Embedded Language Support

​Vue Files

​Astro Files

​Svelte Files

​Special Features

​Import Sorting

​Package.json Sorting

​Language Server Protocol

​Editor Integration

​CI/CD Integration

​GitHub Actions

​Pre-commit Hook

​Performance

​Performance Tips

​API Reference

CLI Reference

Configuration

​FAQ

​Resources

GitHub Repository

npm Package

Discord Community

Prettier Docs

Build docs developers (and LLMs) love

Overview

Quick Start

Run without installation

Install locally

CLI Usage

Basic Commands

CLI Options

Glob Patterns

Stdin/Stdout

Configuration

Configuration File

Formatting Options

EditorConfig Support

Ignore Patterns

Migration from Prettier

Automated Migration

Compatibility

Migration Steps

Embedded Language Support

Vue Files

Astro Files

Svelte Files

Special Features

Import Sorting

Package.json Sorting

Language Server Protocol

Editor Integration

CI/CD Integration

GitHub Actions

Pre-commit Hook

Performance

Performance Tips

API Reference

FAQ

Resources