Configuration

Oxfmt works out of the box, but most teams commit a configuration file to keep formatting consistent across local runs, editors, and CI.

This page focuses on project configuration: formatting options, ignore patterns, and experimental features.

Create a config file

To generate a starter config in the current directory:

oxfmt --init

Oxfmt automatically looks for the following files starting from the directory of the file being formatted and walking up the tree:

• .oxfmtrc.json
• .oxfmtrc.jsonc
• oxfmt.config.ts
• oxfmt.config.mts

You can use only one config file per directory: JSON and TypeScript configs cannot coexist, nor can oxfmt.config.ts and oxfmt.config.mts.

The nearest config file to each formatted file wins. This means you can place different config files at different levels of your project tree. For example, a root config for the whole repo and a more specific one inside a subdirectory:

my-repo/
├── oxfmt.config.ts         # default for the whole repo
├── src/
│   └── app.ts              # uses root config
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # overrides for this package
        └── index.ts        # uses packages/fancy-app/.oxfmtrc.json

If you don't need nested config, pass --disable-nested-config to only look upward from the current working directory. This is faster because Oxfmt can resolve the config once instead of per file.

You can also pass a config explicitly with -c, which also disables nested config lookup. This accepts any supported format (.json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs):

oxfmt -c path/to/yourconfig.json

A minimal JSON configuration looks like this:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}

JavaScript / TypeScript config files use a default export. defineConfig is optional but gives you type checking and editor autocomplete:

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

Configuration file format

A configuration file is a JSON object. The most common top-level fields are:

• printWidth: Line width limit (default: 100)
• tabWidth: Spaces per indentation level (default: 2)
• useTabs: Use tabs instead of spaces (default: false)
• semi: Add semicolons (default: true)
• singleQuote: Use single quotes (default: false)
• trailingComma: Trailing commas in multi-line structures (default: "all")
• ignorePatterns: Glob patterns to exclude from formatting
• sortImports: Configure import sorting (disabled by default)
• sortTailwindcss: Configure Tailwind class sorting (disabled by default)
• sortPackageJson: Configure package.json sorting (enabled by default)

For a complete list of fields, see the Config file reference.

JSON schema

Add a $schema field for editor validation and autocomplete:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}

.editorconfig

Oxfmt reads these .editorconfig properties:

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

Both root section and glob-based overrides are supported.

[*]
indent_size = 4

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

Oxfmt uses only the nearest .editorconfig from the current directory:

• root = true is not respected
• Nested .editorconfig files are not merged

Overrides

Use the overrides field to apply different formatting options to specific files:

.oxfmtrc.json

{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});

Each override entry has:

• files (required): Glob patterns to match files
• excludeFiles (optional): Glob patterns to exclude from this override
• options: Formatting options to apply

Glob patterns are resolved relative to the directory containing the Oxfmt config file.

Precedence

Options are applied in order (lowest to highest priority):

1. Defaults
2. Config file root options
3. Config file overrides options
4. fallback to options supported by .editorconfig for unset fields

Oxfmt-specific options

insertFinalNewline

Controls whether a final newline is added to formatted files. Defaults to true.

This is a frequently requested Prettier feature, as some environments (e.g., Salesforce) strip trailing newlines.

printWidth

Oxfmt defaults to printWidth: 100 (Prettier uses 80). Reasons:

• TypeScript code is longer due to type annotations
• Import statements often have many specifiers
• Modern screens are wider
• Fewer line breaks mean fewer LLM tokens

To match Prettier's default:

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

Next steps

• Ignore files: Ignore files and patterns, .gitignore and .prettierignore workflows.
• Inline ignore comments: Inline suppressions for specific code.
• Config file reference: Full schema and field documentation.
• CLI reference: Complete list of flags.