biome-formatting（生物群系格式化）

Biome Formatting

Master Biome's fast code formatter for JavaScript, TypeScript, JSON, and other supported languages with consistent style enforcement.

Overview

Biome's formatter provides opinionated, fast code formatting similar to Prettier but with better performance. It's written in Rust and designed to format code consistently across teams.

Core Commands

Basic Formatting

# Format files and write changes
biome format --write .

# Format specific files
biome format --write src/**/*.ts

# Check formatting without fixing
biome format .

# Format stdin
echo "const x={a:1}" | biome format --stdin-file-path="example.js"

Combined Operations

# Lint and format together
biome check --write .

# Only format (skip linting)
biome format --write .

# CI mode (check both lint and format)
biome ci .

Formatter Configuration

Global Settings

{
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 80,
    "attributePosition": "auto"
  }
}

Options:

• enabled: Enable/disable formatter (default: true)
• formatWithErrors: Format even with syntax errors (default: false)
• indentStyle: "space" or "tab" (default: "tab")
• indentWidth: Number of spaces, typically 2 or 4 (default: 2)
• lineEnding: "lf", "crlf", or "cr" (default: "lf")
• lineWidth: Maximum line length (default: 80)
• attributePosition: "auto" or "multiline" for HTML/JSX

Recommended Configuration

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 100
  }
}

Language-Specific Formatting

JavaScript/TypeScript

{
  "javascript": {
    "formatter": {
      "enabled": true,
      "quoteStyle": "single",
      "jsxQuoteStyle": "double",
      "quoteProperties": "asNeeded",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "bracketSameLine": false,
      "attributePosition": "auto"
    }
  }
}

Quote Styles

{
  "javascript": {
    "formatter": {
      "quoteStyle": "single",      // 'string' vs "string"
      "jsxQuoteStyle": "double"     // <div attr="value">
    }
  }
}

Examples:

// quoteStyle: "single"
const message = 'Hello, world!';
const name = 'Alice';

// quoteStyle: "double"
const message = "Hello, world!";
const name = "Alice";

// jsxQuoteStyle: "double"
<button onClick={handleClick} label="Submit" />

// jsxQuoteStyle: "single"
<button onClick={handleClick} label='Submit' />

Trailing Commas

{
  "javascript": {
    "formatter": {
      "trailingCommas": "all"  // "all", "es5", or "none"
    }
  }
}

Examples:

// "all"
const obj = {
  a: 1,
  b: 2,
};

function fn(
  arg1,
  arg2,
) {}

// "es5"
const obj = {
  a: 1,
  b: 2,
};

function fn(
  arg1,
  arg2  // No comma (not ES5)
) {}

// "none"
const obj = {
  a: 1,
  b: 2
};

Semicolons

{
  "javascript": {
    "formatter": {
      "semicolons": "always"  // "always" or "asNeeded"
    }
  }
}

Examples:

// "always"
const x = 1;
const y = 2;

// "asNeeded"
const x = 1
const y = 2

Arrow Parentheses

{
  "javascript": {
    "formatter": {
      "arrowParentheses": "always"  // "always" or "asNeeded"
    }
  }
}

Examples:

// "always"
const fn = (x) => x * 2;
const single = (item) => item;

// "asNeeded"
const fn = x => x * 2;
const single = item => item;
const multi = (a, b) => a + b;  // Still needs parens

Bracket Spacing

{
  "javascript": {
    "formatter": {
      "bracketSpacing": true  // true or false
    }
  }
}

Examples:

// bracketSpacing: true
const obj = { a: 1, b: 2 };

// bracketSpacing: false
const obj = {a: 1, b: 2};

Bracket Same Line

{
  "javascript": {
    "formatter": {
      "bracketSameLine": false  // true or false
    }
  }
}

Examples:

// bracketSameLine: false
<Button
  onClick={handleClick}
  label="Submit"
>
  Click me
</Button>

// bracketSameLine: true
<Button
  onClick={handleClick}
  label="Submit">
  Click me
</Button>

Quote Properties

{
  "javascript": {
    "formatter": {
      "quoteProperties": "asNeeded"  // "asNeeded" or "preserve"
    }
  }
}

Examples:

// "asNeeded"
const obj = {
  validIdentifier: 1,
  'invalid-identifier': 2,
  'needs quotes': 3,
};

// "preserve"
const obj = {
  'validIdentifier': 1,
  'invalid-identifier': 2,
  'needs quotes': 3,
};

JSON Formatting

{
  "json": {
    "formatter": {
      "enabled": true,
      "indentStyle": "space",
      "indentWidth": 2,
      "lineWidth": 80,
      "trailingCommas": "none"
    }
  }
}

Note: JSON doesn't support trailing commas, so always use "none".

CSS Formatting

{
  "css": {
    "formatter": {
      "enabled": true,
      "indentStyle": "space",
      "indentWidth": 2,
      "lineWidth": 80,
      "quoteStyle": "double"
    }
  }
}

Common Configurations

Prettier-like Configuration

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "trailingCommas": "es5",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "bracketSameLine": false
    }
  }
}

Standard/XO Style

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "none",
      "semicolons": "asNeeded",
      "arrowParentheses": "asNeeded",
      "bracketSpacing": true
    }
  }
}

Google Style

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always"
    }
  }
}

Airbnb Style

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "jsxQuoteStyle": "double",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true
    }
  }
}

Ignoring Formatting

Ignore Blocks

// biome-ignore format: Preserve specific formatting
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
];

// biome-ignore format: ASCII art
const banner = `
  ╔═══════════════╗
  ║   Welcome!    ║
  ╚═══════════════╝
`;

Ignore Files

In biome.json:

{
  "formatter": {
    "ignore": [
      "**/generated/**",
      "**/*.min.js",
      "**/dist/**"
    ]
  }
}

Or use files.ignore for both linting and formatting:

{
  "files": {
    "ignore": [
      "**/node_modules/",
      "**/dist/",
      "**/*.min.js"
    ]
  }
}

Line Width Strategies

Conservative (80 columns)

Good for code review, side-by-side diffs:

{
  "formatter": {
    "lineWidth": 80
  }
}

Balanced (100-120 columns)

Modern standard for most projects:

{
  "formatter": {
    "lineWidth": 100
  }
}

Relaxed (120+ columns)

For teams with large screens:

{
  "formatter": {
    "lineWidth": 120
  }
}

Indentation Strategies

Spaces (Recommended)

{
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2  // or 4
  }
}

Pros:

• Consistent across all editors
• Better for code review
• Standard in JavaScript ecosystem

Tabs

{
  "formatter": {
    "indentStyle": "tab"
  }
}

Pros:

• Users can set preferred width
• Smaller file sizes
• Accessibility benefits

Migration from Prettier

Compare Configuration

Prettier .prettierrc.json:

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 80
}

Equivalent Biome config:

{
  "formatter": {
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "always",
      "quoteStyle": "single",
      "trailingCommas": "all"
    }
  }
}

Migration Steps

1. Install Biome:

npm install -D @biomejs/biome

1. Create Config:

npx biome init

1. Match Prettier Settings: Update biome.json with equivalent config
2. Format Codebase:

npx biome format --write .

1. Update Scripts:

{
  "scripts": {
    "format": "biome format --write .",
    "format:check": "biome format ."
  }
}

1. Remove Prettier (after validation):

npm uninstall prettier
rm .prettierrc.json .prettierignore

Best Practices

1. Consistent Configuration - Same settings across all packages
2. Line Width Balance - 80-120 based on team preference
3. Use Spaces - More consistent than tabs for JavaScript
4. Enable in CI - Check formatting in pipelines
5. Pre-commit Hooks - Auto-format before commit
6. Document Choices - Explain config decisions to team
7. Ignore Generated Files - Don't format build output
8. Format Incrementally - Use --changed for large codebases
9. Editor Integration - Install Biome extension for IDE
10. Review Diffs - Check formatting changes before commit

Common Pitfalls

1. Conflicting Configs - Multiple configs with different settings
2. Formatting Generated Code - Wasting time on build output
3. Too Strict Line Width - 60 or less is too restrictive
4. Mixing Tabs and Spaces - Inconsistent indentation
5. No CI Check - Not enforcing formatting in pipeline
6. Wrong File Patterns - Ignoring files that should be formatted
7. No Editor Setup - Manually running format commands
8. Large Commits - Formatting entire codebase at once
9. Ignoring Errors - formatWithErrors hides syntax issues
10. No Team Agreement - Individual preferences cause conflicts

Advanced Topics

Per-Language Overrides

{
  "formatter": {
    "indentWidth": 2
  },
  "overrides": [
    {
      "include": ["**/*.json"],
      "formatter": {
        "lineWidth": 120
      }
    },
    {
      "include": ["**/*.md"],
      "formatter": {
        "lineWidth": 80
      }
    }
  ]
}

Conditional Formatting

Format only changed files:

# Git changed files
biome format --write --changed

# Specific commit range
biome format --write --since=main

Editor Integration

VS Code settings.json:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

Monorepo Setup

Root biome.json:

{
  "formatter": {
    "enabled": true,
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all"
    }
  }
}

Package-specific override:

{
  "extends": ["../../biome.json"],
  "formatter": {
    "lineWidth": 120
  }
}

Troubleshooting

Files Not Being Formatted

Check:

1. formatter.enabled is true
2. File extension is supported
3. File not in ignore patterns
4. VCS integration not excluding it

Formatting Conflicts

If formatting keeps changing:

1. Ensure single biome.json source of truth
2. Update all team members' Biome version
3. Run biome migrate to update config
4. Clear editor cache and restart

Performance Issues

Speed up formatting:

1. Use --changed for large repos
2. Ignore node_modules and dist
3. Update to latest Biome version
4. Use VCS integration

When to Use This Skill

• Setting up code formatting for projects
• Migrating from Prettier to Biome
• Establishing team code style standards
• Configuring formatter for specific frameworks
• Troubleshooting formatting issues
• Optimizing formatting performance
• Integrating formatting into CI/CD
• Training teams on code style