Oxfmt differences with Prettier

[Dunqing]

This issue tracks formatting differences between Oxfmt and Prettier, and documents decisions on whether to align or accept the differences.

Background

Oxfmt is ported from Biome, but we aim to make Oxfmt 99.99% compatible with Prettier to ease migration pain. However, after testing Oxfmt on popular repositories, we've found cases where Prettier's output looks weird or isn't "pretty" enough, and we believe Oxfmt should not align with those behaviors.

Philosophy

Oxfmt is not trying to be another opinionated formatter. We are open to discussing different approaches and potentially producing output different from both current Oxfmt and Prettier. However, changes are impactful to the Prettier ecosystem, so we'll carefully consider each difference.

How We Decide

When evaluating differences, we consider:

1. Readability - Which output is clearer and easier to understand?
2. Consistency - Does it match similar patterns in the same codebase?
3. Ecosystem impact - How many projects would be affected by the change?
4. Prettier rationale - Is there a documented reason for Prettier's behavior?
5. Edge case vs common case - How often does this pattern appear in real code?

Decisions are made through community discussion and core team review. We err on the side of Prettier compatibility unless there's a compelling reason to diverge.

Bugs in Prettier

As of now, we've found a lot of prettier bugs that produced incorrect outputs, which caused the output to be different. Know more at Prettier

---

Important

Always assume that differences between prettier's output and oxfmt's output are a bug, except when you find differences in the Prettier issues which we reported, or the cases already listed here. Please create a GitHub issue for those differences! If we decide that it is an expected output and better than prettier's output, then we will post here.

[Dunqing]

Original file

https://github.com/vuejs/core/blob/45547e69b25baa99a0ed52ba5110c5bd8b4a35e4/packages/compiler-core/src/ast.ts#L483-L504

Options:

Default

Input:

With a leading line comment before the TSUnionType

export interface DirectiveArgumentNode extends ArrayExpression {
  elements: // dir, exp, arg, modifiers
  | [string]
    | [string, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode, ObjectExpression]
}

Oxfmt output:

export interface DirectiveArgumentNode extends ArrayExpression {
  elements: // dir, exp, arg, modifiers
    | [string]
    | [string, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode, ObjectExpression]
}

Prettier output:

export interface DirectiveArgumentNode extends ArrayExpression {
  elements: // dir, exp, arg, modifiers
  | [string]
    | [string, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode, ObjectExpression];
}

Prettier output without // dir, exp, arg, modifiers comment:

export interface DirectiveArgumentNode extends ArrayExpression {
  elements: 
    | [string]
    | [string, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode]
    | [string, ExpressionNode, ExpressionNode, ObjectExpression];
}

The Oxfmt is exactly the same as Biome for this case, and we think the current Oxfmt output is better than Prettier's from a readability and consistency perspective.

[vjeux]

Definitely a bug that should be fixed in prettier! cc @fisker

[fisker]

Tracking in prettier/prettier#18106

[Dunqing]

Original file

https://github.com/vuejs/core/blob/45547e69b25baa99a0ed52ba5110c5bd8b4a35e4/packages/runtime-core/src/componentEmits.ts#L193-L202

Options:

Default

Input:

props[handlerName = toHandlerKey(event)]

Oxfmt output:

props[handlerName = toHandlerKey(event)]

Prettier output:

props[(handlerName = toHandlerKey(event))]

The assignment inside the brackets of ComputedMemberExpression does not need to be wrapped in parentheses. There are no semantic changes regarding whether to wrap a parenthesis or not, and I have not found a reason why Prettier did it.

[vjeux]

I have not found a reason why Prettier did it

We wrap assignment expression in parenthesis in order to prevent accidental mistakes. It makes it very explicit that there's an assignment going on.

[Dunqing]

Thank you for explaining; now it makes sense. I will follow it.

[fengmk2]

Input

export default {
  head: [
    [
      'meta', { name: 'robots', content: 'index, follow' },
    ],
    [
      'meta', { name: 'viewport', content: 'width=device-width, initial-scale=1.0' },
    ],
  ],
};

oxfmt output:

export default {
  head: [
    ['meta', { name: 'robots', content: 'index, follow' }],
    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1.0' }],
  ],
};

Prettier output:

export default {
  head: [
    ['meta', { name: 'robots', content: 'index, follow' }],
    [
      'meta',
      { name: 'viewport', content: 'width=device-width, initial-scale=1.0' },
    ],
  ],
};

"lineWidth": 120, I think oxfmt is better.

[Boshen]

oxfmt is better but we need to make it compatible first, then introduce better line wrappings :-/

[GermanJablo]

Are you comparing the same lineWidth limit in both cases?

[vjeux]

I'm curious what algorithm do you use to not expand the second one? Do you check if the first element fits in a line and if yes, inline all the ones after? So if you swap the two elements it's going to be displayed differently?

This is one of the things in prettier that's suboptimal but I haven't found a good way to solve this.

[sandstrom]

we've found cases where Prettier's output looks weird or isn't "pretty" enough, and we believe Oxfmt should not align with those behaviors.

I think this is great, because while Prettier is a great idea, sometimes it's just annoying and will produce some really weird-looking code.

Another general problem with it is that sometimes small changes will 'cascade', i.e. you're changing a small thing and it'll rewrite 20 lines of code. I know this is vague, but hopefully still a decent description of this tendency. I realize it's not always possible to avoid, but still something where it would be neat if oxc handled it better.

[Dunqing]

Options:

Default

Input:

const defaultColorDecoratorsEnablement = accessor
  .get(IConfigurationService)
  .getValue<"auto" | "always" | "never">(
    "longlonglonglonglonglonglonglonglong",
  );

Oxfmt and Biome's output:

const defaultColorDecoratorsEnablement = accessor
  .get(IConfigurationService)
  .getValue<"auto" | "always" | "never">(
    "longlonglonglonglonglonglonglonglong",
  );

Prettier output:

const defaultColorDecoratorsEnablement = accessor
  .get(IConfigurationService)
  .getValue<
    "auto" | "always" | "never"
  >("longlonglonglonglonglonglonglonglong");

I found this case in the VSCode repo. From my first look, I think Oxfmt's output is prettier than Prettier's, but considering compatibility, I already fixed the issue in #14983. However, I suspect this is actually a bug in Prettier and wrote my thoughts in its description, so track the problem here. Learn more at #14983.

[Dunqing]

I created an issue in Prettier prettier/prettier#18136

[AndreyMay]

Couple of examples I'm seeing after trying oxfmt on large codebase.

1. The comment at the end of the return () statement is moved outside of )

2. Different wrap at 120 chars

3. ): and comment

4. HTML rearranged

[Dunqing]

Thank you for giving it a try and reporting these differences. The description mentioned that it should always be assumed that differences are caused by the Oxfmt bug, so please create issues for each case. That would help us track and fix it quickly! You can use this issue template https://github.com/oxc-project/oxc/issues/new?template=formatter_diff_report.yaml to create an issue about the difference between Oxfmt and Prettier.

[NMinhNguyen]

[Dunqing]

Please create a separate issue! That would help us track and fix it quickly!

[NMinhNguyen]

Thanks for the quick reply! I followed the template and created an issue and deleted my original comment.