Biome formatter compatibility limits with complex TypeScript types

Answer to the Question

Biome does not replace the entire file with a generic layout when it encounters a type it cannot fully parse. Instead, the parser emits a warning and continues formatting the rest of the file. The unsupported type block is left largely untouched, preserving the original token stream. The fallback behavior is a best‑effort approach rather than a full reset to a basic layout.

Known Parser Boundaries

• Supported language level: up to TypeScript 4.8. Features introduced in 5.0 (variadic tuples, template literal types, etc.) are not yet parsed.
• Complex type aliases that involve:
  • Recursive references (e.g., type A = A & {…})
  • Deeply nested conditional types with multiple type parameters
  • Mapped types that remap keys or use advanced key constraints
  • Type aliases that combine several of the above in a single declaration
• When such constructs are encountered, Biome emits a warning similar to Biome: Unable to parse type alias ‘Foo’ – falling back to best‑effort formatting.

How to Verify the Behavior in Your Project

1. Create a minimal file that contains a complex type you suspect is problematic.
2. Run the formatter in check mode:

   biome format --check path/to/file.ts

3. Observe the console output. A warning line indicates a parse failure.
4. Open the formatted file (or run biome format path/to/file.ts) and confirm that:
   • The rest of the file is formatted according to Biome’s style.
   • The problematic type block remains largely unformatted but is preserved.
5. Compare the result with a reference formatter such as Prettier or the TypeScript compiler’s own formatting to see if layout differences exist.

What to Do If You Encounter a Problematic Type

• Upgrade to the latest Biome release; newer versions may have added support for the specific construct.
• If the type is critical for your code style, consider adding a // biome-ignore format comment around it to keep the original layout.
• Alternatively, refactor the type into a simpler form that stays within the supported subset.

Missing Diagnostic Detail

To tailor the recommendation further, could you share the exact Biome and TypeScript versions you are using? This will help determine if a newer release already covers the construct in question.