Why has Prettier stopped formatting anything?

If requirePragma is enabled, only files whose first block comment contains @format or @prettier are formatted. Everything else is left untouched by design.

Should I use this or .prettierignore?

Use requirePragma for gradual adoption of an existing codebase, because the marker travels with the file when it is renamed. Use .prettierignore for permanently excluding paths such as generated output.

Which pragma should I write?

Either @format or @prettier, inside the first block comment in the file. insertPragma writes @format.

`requirePragma` — the option that lets a huge codebase adopt Prettier one file at a time

The Prettier Require Pragma option

requirePragma makes Prettier format only files that already carry a @format or @prettier marker in their first block comment. It exists for one purpose: introducing Prettier to a large existing codebase without a single commit that rewrites every file.

Require either '@prettier' or '@format' to be present in the file's first docblock comment in order for it to be formatted.

Prettier's own description, from the official options documentation

Default: false
Type: boolean
CLI flag: --require-pragma

The problem it solves

Adopting Prettier on a mature codebase normally means one enormous commit. Every file changes, git blame points at that commit for most lines, every open pull request conflicts, and reviewers have no way to check that nothing broke.

For a small project that is an afternoon's inconvenience. For a codebase with hundreds of thousands of lines and dozens of concurrent branches it can be enough to stop adoption entirely.

requirePragma inverts the default. With it enabled, Prettier formats nothing unless the file explicitly opts in:

/**
 * @format
 */

export function run() {}

A file that has opted in.

Either @format or @prettier works, and the comment must be the first block comment in the file.

The adoption workflow

On its own the option would mean adding pragmas by hand. Paired with insertPragma it becomes a workflow:

Enable requirePragma so nothing is formatted by default.
Enable insertPragma so that any file Prettier does format gains the marker automatically.
Run Prettier explicitly on a file when you are already changing it for other reasons. It gets formatted and marked, and stays formatted from then on.
The formatted share of the codebase grows in step with the code people are actually touching, and each reformat rides along with a change that was going to be reviewed anyway.

When the proportion of unmarked files is small enough to reformat in one go, drop both options and format the remainder.

How it differs from .prettierignore

.prettierignore is a path-based deny list: you name what to exclude. requirePragma is a content-based allow list: the file itself says whether it participates.

That difference matters when files move. A renamed or relocated file keeps its pragma and keeps its behaviour, whereas a .prettierignore entry silently stops matching. For gradual adoption, where files are being refactored constantly, the content-based marker is the more robust of the two.

Editor and CI considerations

Format-on-save quietly does nothing on unmarked files, which surprises people. Say so in your contributing guide.
A --check run in CI passes trivially for unmarked files, so CI enforces formatting only on the opted-in set — which is exactly what you want during a migration, and a gap to close once it is over.
Remember to remove both options when the migration finishes. A forgotten requirePragma means new files silently escape formatting.

Common mistakes

Enabling it and wondering why Prettier appears broken. It is working; nothing has opted in yet.
Putting the pragma in a line comment. It must be a block comment, and it must be the first one in the file.
Enabling it without insertPragma, which leaves you adding markers by hand.
Leaving it enabled indefinitely, so the codebase permanently contains two classes of file.

Use it in .prettierrc

Drop requirePragma into your Prettier config file:

{
  "requirePragma": false
}

Try it in the generator

Worked examples

The same code formatted with each value of requirePragma.

`requirePragma: true`

const user = {name: "Ada", "user-id": 7, roles: ["admin", "editor"], active: true};
const greet = name => `Hello ${name}`;
const label = user.active ? "active member of the team" : "inactive member of the team";
export function summarize(items) { return items.filter(i => i.active).map(i => i.name).join(", "); }

`requirePragma: false`

const user = {
  name: "Ada",
  "user-id": 7,
  roles: ["admin", "editor"],
  active: true,
};
const greet = (name) => `Hello ${name}`;
const label = user.active
  ? "active member of the team"
  : "inactive member of the team";
export function summarize(items) {
  return items
    .filter((i) => i.active)
    .map((i) => i.name)
    .join(", ");
}

Common questions

Why has Prettier stopped formatting anything?: If requirePragma is enabled, only files whose first block comment contains @format or @prettier are formatted. Everything else is left untouched by design.
Should I use this or .prettierignore?: Use requirePragma for gradual adoption of an existing codebase, because the marker travels with the file when it is renamed. Use .prettierignore for permanently excluding paths such as generated output.
Which pragma should I write?: Either @format or @prettier, inside the first block comment in the file. insertPragma writes @format.

Other Special options

Generated from Prettier 3.9.6.

requirePragma — the option that lets a huge codebase adopt Prettier one file at a time