Small checks.
Better foundations.
Understand what each rule catches, why it matters, and what a better pattern looks like. Start with the defaults. Tune the checks to your project.
Astro Doctor composes its rules with eslint-plugin-astro. The allpreset enables 63 unique ESLint checks after overlap deduplication, plus project audits. Each rule below includes its default severity; you can change that in your configuration.
Performance5 checks
- no-client-load-overusePrefer client:idle or client:visible over client:load for interactive islands.
- use-astro-imageUse <Image> from astro:assets instead of raw <img> tags.
- require-image-dimensionsRequire dimensions for public and remote astro:assets images.
- no-blocking-scriptDisallow render-blocking <script src="..."> tags — add defer, async, or type="module".
- no-unprocessed-script-surprisesWarn when script attributes opt out of Astro script processing.
Accessibility3 checks
Security2 checks
Best Practices3 checks
Project audits11 checks
The CLI also evaluates configuration and relationships across files that an isolated ESLint rule cannot see. Preset labels show where each audit is enabled.
- no-disabled-origin-checkKeep Astro's built-in CSRF origin check enabled.
- no-insecure-session-cookieKeep secure, HTTP-only, same-site session cookie protections enabled.
- no-open-allowed-domainsConfigure explicit trusted host patterns instead of allowing every domain.
- no-legacy-astro-7-experimental-flagsMigrate experimental configuration fields removed or stabilized in Astro 7.
- prefer-env-schemaDefine an Astro env schema for variables documented in .env.example.
- prefer-pnpmUse pnpm consistently and remove competing package-manager lockfiles.
- require-action-input-schemaValidate untrusted Astro Action input before the handler runs.
- require-client-router-script-lifecycleInitialize scripts on astro:page-load when using ClientRouter.
- require-content-configAdd a content config when src/content contains entries.
- require-fetch-default-exportRequire a default export from Astro 7 advanced-routing entrypoints.
- no-public-secret-envWarn when PUBLIC_ environment variables appear to contain secrets.
Make the rules yours
Override individual severities in your eslint.config.js:
import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'
export default [
astroDoctorPlugin.configs.recommended,
{
rules: {
'astro-doctor/no-client-load-overuse': 'error',
'astro-doctor/prefer-class-list': 'off',
},
},
]For CLI settings and project audits, use adoctor.config.* file. Use --fix to apply automatic fixes offered by supported rules.