Biome

BiomeJS Configuration

Set up and configure BiomeJS for linting, formatting, and code style enforcement.

Version Discovery

Always discover the latest version before doing anything. Never hardcode a biome version.

npm view @biomejs/biome version

Use the discovered version for:

• Installing: npm install --save-dev --save-exact @biomejs/biome@<version>
• Schema URL: https://biomejs.dev/schemas/<version>/schema.json

New Project Setup

1. Discover the latest version (see above)
2. Install biome:

   npm install --save-dev --save-exact @biomejs/biome@<version>
   

3. Create biome.json at the project root using the baseline configuration below
4. Add package.json scripts (see Scripts section)
5. Verify with npx biome check .

Migration / Upgrade

When a project already has biome configured:

1. Discover the latest version
2. Update the dependency: npm install --save-dev --save-exact @biomejs/biome@<version>
3. Update the $schema URL in biome.json to match the new version
4. Run npx biome check . to verify nothing breaks
5. Review and modernize the config — only override what differs from biome's defaults

Baseline Configuration

Use this as the starting point for all projects. Adapt based on project context (see Adaptive Rules below).

{
  "$schema": "https://biomejs.dev/schemas/<version>/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "always"
    }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": "warn"
      },
      "correctness": {
        "noUnusedImports": "error",
        "noUnusedVariables": "warn",
        "useArrayLiterals": "error"
      },
      "style": {
        "noDefaultExport": "error",
        "noCommonJs": "error",
        "noNamespaceImport": "warn",
        "useFilenamingConvention": {
          "level": "error",
          "options": {
            "strictCase": true,
            "filenameCases": ["camelCase", "kebab-case"]
          }
        }
      },
      "suspicious": {
        "noConsole": "warn"
      }
    }
  },
  "css": {
    "linter": {
      "enabled": true
    },
    "formatter": {
      "enabled": true,
      "quoteStyle": "single"
    }
  },
  "organizeImports": {
    "enabled": true
  }
}

Adaptive Rules

Adjust the baseline based on what you detect in the project:

No CSS in project

If there are no CSS, SCSS, or similar files, remove the css section entirely.

Next.js / Remix / Astro / SvelteKit

These frameworks require default exports for pages and routes. Disable the rule or scope it:

"style": {
  "noDefaultExport": "off"
}

Or use overrides to allow default exports only in route files:

"overrides": [
  {
    "includes": ["src/app/**", "src/pages/**", "app/**", "pages/**"],
    "linter": {
      "rules": {
        "style": {
          "noDefaultExport": "off"
        }
      }
    }
  }
]

CommonJS projects

If the project uses "type": "commonjs" or lacks "type": "module" in package.json and uses require():

"style": {
  "noCommonJs": "off"
}

Tailwind CSS

No special biome config needed — Tailwind works with biome out of the box. Just ensure CSS linting is enabled if the project has CSS files.

Monorepo

Place biome.json at the workspace root. Use overrides for package-specific rules if needed.

Test files

Allow noConsole in test files:

"overrides": [
  {
    "includes": ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"],
    "linter": {
      "rules": {
        "suspicious": {
          "noConsole": "off"
        }
      }
    }
  }
]

Package.json Scripts

Add these scripts to the project's package.json:

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

Verification

After setup, always verify:

npx biome check .

If there are many existing violations, consider using --write to auto-fix what biome can:

npx biome check --write .

For remaining issues that can't be auto-fixed, either fix them or adjust rules as appropriate for the project.