Skip to main content

require-readme-file

Require a root-level README for the repository.

Targeted pattern scope​

This rule checks the repository root for a primary README document.

The rule accepts either of these files:

  • README.md
  • README

What this rule reports​

This rule reports repositories that do not provide any accepted README file at the root.

Why this rule exists​

A repository without a README forces contributors, users, and maintainers to guess basic project context.

Even a short README gives reviewers and automation consumers a stable place to find:

  • project purpose
  • setup or usage notes
  • contribution expectations
  • links to deeper documentation

❌ Incorrect​

// Repository files
// .
// ├── eslint.config.mjs
// ├── package.json
// └── src/
//
// Missing: README.md or README

✅ Correct​

// Repository files
// .
// ├── README.md
// ├── eslint.config.mjs
// └── package.json
// Repository files
// .
// ├── README
// ├── eslint.config.mjs
// └── package.json

ESLint flat config example​

import repoPlugin from "eslint-plugin-repo";

export default [
  repoPlugin.configs.recommended,
  {
    plugins: { "repo-compliance": repoPlugin },
    rules: {
      "repo-compliance/require-readme-file": "error",
    },
  },
];

When not to use it​

Disable this rule only if the repository is intentionally private, ephemeral, or generated and you do not want a root-level landing document.

Rule catalog ID: R001

Further reading​