Configuration options for Oxfmt.

Most options are the same as Prettier's options, but not all of them. In addition, some options are our own extensions.

arrowParens

type: "always" | "avoid"

Include parentheses around a sole arrow function parameter.

• Languages: JS, JSX, TS, TSX
• Default: "always"

associations

type: array

Format matched files as the given language, instead of detecting it from the file name. e.g. Angular templates named *.html, or *.wxml files formatted as HTML. When a file matches multiple associations, the later one takes precedence (array order matters).

• Default: []

associations[n]

type: object

associations[n].excludeFiles

type: string[]

Glob patterns to exclude from this association.

A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory.

associations[n].files

type: string[]

Glob patterns to match files for this association.

A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory.

associations[n].language

type: "javascript" | "jsx" | "typescript" | "tsx" | "json" | "jsonc" | "json5" | "css" | "scss" | "less" | "graphql" | "yaml" | "markdown" | "toml" | "html" | "angular-html" | "vue" | "svelte" | "astro" | "handlebars" | "mdx"

The language to format matched files as, named by its Shiki id (as in Markdown code fences).

astro

type: object | boolean

Options for prettier-plugin-astro.

Pass true or an object to enable .astro file formatting, false to disable (handy in overrides). Setting true resets to defaults, dropping options inherited from a parent scope.

NOTE: prettier-plugin-astro requires the @astrojs/compiler-rs package at runtime. Oxfmt does NOT bundle it, so install it in your project, otherwise formatting fails.

• Languages: Astro
• Default: Disabled

astro.allowShorthand

type: boolean

Whether to normalize matching identifier attributes to shorthand or explicit form. When unset, the form that was written stays as-is.

• Default: Unset

astro.compressHTML

type: "jsx" | "html" | "none"

Mirror of Astro's compressHTML config. Tells the formatter which whitespace the compiler will collapse.

• Default: "jsx"

astro.skipFrontmatter

type: boolean

Whether to skip formatting the frontmatter.

• Default: false

bracketSameLine

type: boolean

Put the > of a multi-line element at the end of the last line, instead of being alone on the next line (does not apply to self-closing elements).

• Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte, Astro
• Default: false

bracketSpacing

type: boolean

Print spaces between brackets in object literals.

• Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML
• Default: true

embeddedLanguageFormatting

type: "auto" | "off"

Control whether to format embedded parts in the file. For example:

• CSS-in-JS: template literal
• JS-in-Vue: <script> block
• JS-in-Markdown: code fence
• YAML-in-CSS/Markdown: front matter

With "off", these parts are kept as-is.

NOTE: Some languages behave differently. For Svelte, formatting fails with "off", a limitation of prettier-plugin-svelte. For Astro, the frontmatter is still formatted, but by Prettier instead of Oxfmt (use astro.skipFrontmatter to keep it as-is).

• Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Astro, Markdown, MDX
• Default: "auto"

endOfLine

type: "lf" | "crlf" | "cr"

Which end of line characters to apply.

NOTE: "auto" is not supported.

• Languages: All
• Default: "lf"
• Overrides .editorconfig.end_of_line

experimentalOperatorPosition

type: "start" | "end"

When expressions wrap lines, print operators at the start of new lines ("start") or at the end of previous lines ("end").

• Languages: JS, JSX, TS, TSX
• Default: "end"

htmlWhitespaceSensitivity

type: "css" | "strict" | "ignore"

Specify the global whitespace sensitivity.

• Languages: HTML, Angular, Vue, Handlebars, Svelte
• Default: "css"

ignorePatterns

type: string[]

Ignore files matching these glob patterns. Patterns use gitignore-style matching, rooted at the directory containing the configuration file. Files outside that directory cannot be matched; patterns containing .. are rejected as a configuration error.

• Default: []

insertFinalNewline

type: boolean

Whether to insert a final newline at the end of the file.

• Languages: All
• Default: true
• Overrides .editorconfig.insert_final_newline

jsdoc

type: object | boolean

Enable JSDoc comment formatting.

Normalizes JSDoc comments: tag aliases are canonicalized, descriptions are capitalized, long lines are wrapped, and short comments are collapsed to single-line.

Pass true or an object to enable, false to disable.

• Languages: JS, JSX, TS, TSX
• Default: Disabled

jsdoc.addDefaultToDescription

type: boolean

Append default values to @param descriptions (e.g. "Default is value").

• Default: true

jsdoc.bracketSpacing

type: boolean

Add spaces inside JSDoc type braces: {string} → { string }.

• Default: false

jsdoc.capitalizeDescriptions

type: boolean

Capitalize the first letter of tag descriptions.

• Default: true

jsdoc.commentLineStrategy

type: "singleLine" | "multiline" | "keep"

How to format comment blocks.

• "singleLine": Convert to single-line /** content */ when possible
• "multiline": Always use multi-line format
• "keep": Preserve original formatting

By default, comments are collapsed to a single line when possible.

• Default: "singleLine"

jsdoc.descriptionTag

type: boolean

Emit @description tag instead of inline description.

• Default: false

jsdoc.descriptionWithDot

type: boolean

Add a trailing dot to the end of descriptions.

• Default: false

jsdoc.keepUnparsableExampleIndent

type: boolean

Preserve indentation in unparsable @example code.

• Default: false

jsdoc.lineWrappingStyle

type: "greedy" | "balance"

Strategy for wrapping description lines at print width.

• "greedy": Always re-wrap text to fit within print width
• "balance": Preserve original line breaks if all lines fit within print width

By default, description lines are always re-wrapped.

• Default: "greedy"

jsdoc.preferCodeFences

type: boolean

Use fenced code blocks (```) instead of 4-space indentation for code without a language tag.

• Default: false

jsdoc.separateReturnsFromParam

type: boolean

Add a blank line between the last @param and @returns.

• Default: false

jsdoc.separateTagGroups

type: boolean

Add blank lines between different tag groups (e.g. between @param and @returns).

• Default: false

jsxSingleQuote

type: boolean

Use single quotes instead of double quotes in JSX.

• Languages: JSX, TSX
• Default: false

objectWrap

type: "preserve" | "collapse"

How to wrap object literals when they could fit on one line or span multiple lines.

By default, formats objects as multi-line if there is a newline prior to the first property. Authors can use this heuristic to contextually improve readability, though it has some downsides.

• Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5
• Default: "preserve"

overrides

type: array

File-specific overrides. When a file matches multiple overrides, the later override takes precedence (array order matters).

• Default: []

overrides[n]

type: object

overrides[n].excludeFiles

type: string[]

Glob patterns to exclude from this override.

A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory.

overrides[n].files

type: string[]

Glob patterns to match files for this override.

A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory.

overrides[n].options

type: object

Format options to apply for matched files. Accepts the same options as the top-level format options.

printWidth

type: integer

Specify the line length that the printer will wrap on.

If you don't want line wrapping when formatting Markdown, you can set the proseWrap option to disable it.

• Languages: All
• Default: 100
• Overrides .editorconfig.max_line_length

proseWrap

type: "always" | "never" | "preserve"

How to wrap prose.

• "always": Wrap prose to the print width
• "never": Put each prose block on a single line, relying on editor/viewer soft wrapping
• "preserve": Keep wrapping as-is

By default, wrapping is preserved, since some services use a linebreak-sensitive renderer (e.g. GitHub comments, BitBucket).

• Languages: Markdown, MDX, YAML
• Default: "preserve"

quoteProps

type: "as-needed" | "consistent" | "preserve"

Change when properties in objects are quoted.

• Languages: JS, JSX, TS, TSX
• Default: "as-needed"

semi

type: boolean

Print semicolons at the ends of statements.

• Languages: JS, JSX, TS, TSX
• Default: true

singleAttributePerLine

type: boolean

Enforce single attribute per line.

• Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte, Astro
• Default: false

singleQuote

type: boolean

Use single quotes instead of double quotes.

For JSX, you can set the jsxSingleQuote option.

• Languages: JS, JSX, TS, TSX, CSS, Less, SCSS, Markdown, MDX, YAML, Handlebars, Svelte, Astro
• Default: false
• Overrides .editorconfig.quote_type

sortImports

type: object | boolean

Sort import statements.

Uses a similar algorithm to eslint-plugin-perfectionist/sort-imports.

Pass true or an object to enable, false to disable.

• Languages: JS, JSX, TS, TSX
• Default: Disabled

sortImports.customGroups

type: array

Define your own groups for matching very specific imports.

The first matching definition is used, and custom groups take precedence over predefined groups. To give a predefined group precedence, define an equivalent custom group and put it first.

When multiple conditions (elementNamePattern, selector, modifiers) are specified, all of them must match.

NOTE: Predefined group names (e.g. side_effect, external) and unknown are reserved and cannot be used as groupName.

• Default: []

sortImports.customGroups[n]

type: object

sortImports.customGroups[n].elementNamePattern

type: string[]

default: []

List of glob patterns to match import sources for this group.

sortImports.customGroups[n].groupName

type: string

default: ""

Name of the custom group, used in the groups option.

sortImports.customGroups[n].modifiers

type: array

Modifiers to match the import characteristics. All specified modifiers must match.

sortImports.customGroups[n].modifiers[n]

type: "side_effect" | "type" | "value" | "default" | "wildcard" | "named"

Modifier matching the import characteristics in customGroups (see sortImports.groups for semantics).

sortImports.customGroups[n].selector

type: "type" | "side_effect_style" | "side_effect" | "style" | "index" | "sibling" | "parent" | "subpath" | "internal" | "builtin" | "external" | "import"

Selector to match the import kind.

sortImports.groups

type: array

List of import groups for sorting.

Each import is assigned to a single group (or unknown if none matches), and groups are ordered as listed. Within a group, imports are sorted according to order, ignoreCase, etc.

A predefined group name is a single selector with optional modifiers, joined by - (e.g. type-external). Modifiers can be in any order, but the selector must come last.

Selectors, from most to least important:

• type: TypeScript type imports.
• side_effect_style: Side effect style imports.
• side_effect: Side effect imports.
• style: Style imports.
• index: Main file from the current directory.
• sibling: Modules from the same directory.
• parent: Modules from the parent directory.
• subpath: Node.js subpath imports.
• internal: Your internal modules.
• builtin: Node.js Built-in Modules.
• external: External modules installed in the project.
• import: Any import.

Modifiers, from most to least important:

• side_effect: Side effect imports.
• type: TypeScript type imports.
• value: Value imports.
• default: Imports containing the default specifier.
• wildcard: Imports containing the wildcard (* as) specifier.
• named: Imports containing at least one named specifier.

Wrap groups in an array to sort them together as a single group (order within the array does not matter).

To override newlinesBetween at a specific group boundary, put a { "newlinesBetween": boolean } marker object at that position.

• Default: See below

["builtin", "external", ["internal", "subpath"], ["parent", "sibling", "index"], "style", "unknown"]

sortImports.groups[n]

type: object | array | string

sortImports.groups[n].newlinesBetween

type: boolean

sortImports.ignoreCase

type: boolean

Ignore case when sorting.

• Default: true

sortImports.internalPattern

type: string[]

Prefixes for identifying internal imports.

• Default: ["~/", "@/", "#"]

sortImports.newlinesBetween

type: boolean

Add newlines between groups.

• Default: true

sortImports.order

type: "asc" | "desc"

Sort in ascending or descending order.

• Default: "asc"

sortImports.partitionByComment

type: boolean

Use comments to separate imports into logical groups.

When true, all comments are treated as delimiters.

import { b1, b2 } from "b";
// PARTITION
import { a } from "a";
import { c } from "c";

• Default: false

sortImports.partitionByNewline

type: boolean

Use empty lines to separate imports into logical groups.

When true, imports are not sorted across an empty line.

import { b1, b2 } from "b";

import { a } from "a";
import { c } from "c";

• Default: false

sortImports.sortSideEffects

type: boolean

Sort side effect imports.

Disabled by default for safety reasons.

• Default: false

sortPackageJson

type: object | boolean

Sort package.json keys.

The order is NOT compatible with prettier-plugin-packagejson, but we believe it is clearer and easier to navigate.

• Languages: JSON (package.json only)
• Default: true

sortPackageJson.sortScripts

type: boolean

Sort the scripts field alphabetically.

• Default: false

sortTailwindcss

type: object | boolean

Sort Tailwind CSS classes.

Uses the same algorithm as prettier-plugin-tailwindcss. Option names omit the tailwind prefix used in the original plugin (e.g. config instead of tailwindConfig).

Pass true or an object to enable, false to disable.

• Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Handlebars, CSS, SCSS, Less, Svelte, Astro
• Default: Disabled

sortTailwindcss.attributes

type: string[]

List of additional attributes to sort beyond class and className (exact match).

NOTE: Regex patterns are not yet supported.

• Default: []
• Example: ["myClassProp", ":class"]

sortTailwindcss.config

type: string

Path to your Tailwind CSS configuration file (v3).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

• Default: Automatically find "tailwind.config.js"

sortTailwindcss.functions

type: string[]

List of custom function names whose arguments should be sorted (exact match).

NOTE: Regex patterns are not yet supported.

• Default: []
• Example: ["clsx", "cn", "cva", "tw"]

sortTailwindcss.preserveDuplicates

type: boolean

Preserve duplicate classes.

• Default: false

sortTailwindcss.preserveWhitespace

type: boolean

Preserve whitespace around classes.

• Default: false

sortTailwindcss.stylesheet

type: string

Path to your Tailwind CSS stylesheet (v4).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

• Default: Installed Tailwind CSS's theme.css

svelte

type: object | boolean

Options for prettier-plugin-svelte.

Pass true or an object to enable .svelte file formatting, false to disable (handy in overrides). Setting true resets to defaults, dropping options inherited from a parent scope.

NOTE: prettier-plugin-svelte requires the svelte package (svelte/compiler) at runtime. Oxfmt does NOT bundle it, so install it in your project, otherwise formatting fails.

• Languages: Svelte
• Default: Disabled

svelte.allowShorthand

type: boolean

Whether to allow attribute shorthand if attribute name and expression are the same.

• Default: true

svelte.indentScriptAndStyle

type: boolean

Whether to indent code inside <script> and <style> tags.

• Default: true

svelte.sortOrder

type: string

The order in which Svelte component sections are printed. Join options, scripts, markup, styles with - in the desired order, or use none to keep the original order.

• Default: "options-scripts-markup-styles"

tabWidth

type: integer

Specify the number of spaces per indentation-level.

• Languages: All
• Default: 2
• Overrides .editorconfig.indent_size (falls back to .editorconfig.tab_width)

trailingComma

type: "all" | "es5" | "none"

Print trailing commas wherever possible in multi-line comma-separated syntactic structures.

A single-line array, for example, never gets trailing commas.

• Languages: JS, JSX, TS, TSX, JSONC, JSON5, TOML, CSS, Less, SCSS, YAML
• Default: "all"

useTabs

type: boolean

Indent lines with tabs instead of spaces.

• Languages: All
• Default: false
• Overrides .editorconfig.indent_style

vueIndentScriptAndStyle

type: boolean

Whether or not to indent the code inside <script> and <style> tags in Vue files.

• Languages: Vue
• Default: false