Configuration

astro-doctor looks for a doctor.config.* file in the directory you scan. All configuration is optional — the defaults are sensible out of the box.

Supported formats

Any of the following file names are detected, in priority order:

doctor.config.ts
doctor.config.js
doctor.config.mjs
doctor.config.cjs
doctor.config.json
doctor.config.jsonc

Schema

// doctor.config.ts
import type { AstroDoctorConfig } from '@santi020k/astro-doctor'

export default {
  // 'recommended' | 'strict' | 'ci' | 'all'
  preset: 'recommended',

  // Override rule severities
  rules: {
    'astro-doctor/no-client-load-overuse': 'error',   // upgrade to error
    'astro-doctor/prefer-class-list': 'off',           // disable a rule
  },

  // Apply template-rule overrides to matching Astro files
  overrides: [
    {
      files: ['src/legacy/**'],
      rules: {
        'astro-doctor/no-set-html': 'off',
      },
    },
  ],

  // Glob patterns to ignore (relative to scanned directory)
  ignore: ['src/legacy/**', 'src/vendor/**'],

  // When to exit with code 1: 'error' | 'warning' | 'off'
  // CLI flag --fail-on overrides this
  failOn: 'error',
} satisfies AstroDoctorConfig

Fields

preset

Select the rule surface: recommended uses the high-signal defaults,strict adds accessibility, security, and best-practice checks,all enables every non-deprecated official Astro rule, andci uses recommended coverage while failing on warnings.

rules

Override the default severity of any rule. Accepted values: 'error','warn', 'off'.

ignore

An array of glob patterns (relative to the scanned directory) to exclude from the scan. Useful for generated code, vendored components, or legacy directories you're not ready to fix yet.

overrides

Apply rule severities only to matching Astro file globs. Each entry requires a non-emptyfiles array and a rules object. Project-audit rules remain project-wide.

projects

Select workspace packages by package name or relative path. Project-level configuration is layered over the root configuration, including rule overrides.

failOn

Controls when astro-doctor exits with a non-zero exit code:

The --fail-on CLI flag takes precedence over the config file value.

JSON / JSONC example

// doctor.config.jsonc
{
  "$schema": "https://doctor.santi020k.com/schema/config.json",
  // Comments are supported in .jsonc
  "rules": {
    "astro-doctor/no-client-load-overuse": "error"
  },
  "ignore": ["src/vendor/**"],
  "failOn": "warning"
}