Prettier 24 🎨 The -insert-pragma Option — Marking formatted files incrementally - KandZ

⏱️ Estimated read: 11 min | |

The --insert-pragma flag is the forward half of Prettier’s gradual adoption mechanism. It formats the file and then inserts the marker that the --require-pragma flag looks for. The marker is @format, and it is placed in the file’s first docblock comment. If the file has no docblock, Prettier creates one. If the file already has a docblock, Prettier adds a new line to it with the marker . The flag was introduced in Prettier v1.8.0, one version after the --require-pragma flag that it complements . The two flags are designed to be used in tandem during a migration, but they are not used at the same time. The --insert-pragma flag is for the developers who are actively touching files; the --require-pragma flag is for the CI pipeline and the rest of the team, which should only format files that have already been opted in.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The mechanism is small: format the file, add the marker, write the result. The effect is large: the file is now permanently opted in to Prettier. The --require-pragma flag will format it on every subsequent run, and the CI check will enforce it. The file’s formatting behavior is determined by a comment that lives inside the file, not by a path in a .prettierignore file. When the file is moved or renamed, the marker moves with it, and the formatting behavior persists.

Key point: --insert-pragma formats the file and inserts @format into the first docblock comment. It is the companion to --require-pragma, and it is used by the developers who are migrating files during a gradual adoption. The flag does not format the whole codebase; it formats the files it is given and marks them as opted in.

Why the flag exists

The opt-in problem. A gradual adoption needs a mechanism for files to join the formatted set. The --require-pragma flag provides the filter: only files with the marker are formatted. The --insert-pragma flag provides the mechanism that adds the marker. Without it, the developer would have to add the @format comment manually before running Prettier, which is an extra step that is easy to forget. The flag combines the formatting and the marking into a single command .

The marker placement problem. The marker must be in the file’s first docblock comment for --require-pragma to recognize it. A manual edit can place the marker in a line comment or in a later comment, and the --require-pragma flag will not find it. The --insert-pragma flag handles the placement automatically: it finds the first docblock, or creates one if none exists, and inserts the marker in the correct position . The automatic placement eliminates the class of errors where the marker is present but not recognized.

The same-commit problem. The migration workflow requires the formatting change and the marker to be in the same commit as the developer’s actual change. A separate commit that adds the markers to a set of files would conflict with the open pull requests, which is the problem the gradual adoption is trying to avoid. The --insert-pragma flag makes the formatting and the marking a single operation, so the developer can run one command on the file they are already editing and commit the result alongside their logic change .

The trade-off. The flag is not a replacement for the --require-pragma flag, and it does not enforce anything. It marks the files it is given. If the developer forgets to run it, the file remains unmarked and unformatted. The flag is a convenience for the migration, not a guarantee that the migration is complete.

a. The basic usage and the marker format

The flag is passed on the command line alongside the file paths and the --write flag. The --write flag is required to modify the file; without it, the formatted output with the marker is printed to stdout.

# Format the file, insert the @format marker, and write the result.
npx prettier src/app.js --insert-pragma --write

The marker is placed in the first docblock comment. For JavaScript and TypeScript, the marker is /** @format */. For HTML and Markdown, the marker is . For YAML, the marker is # @format . The flag writes the correct form for the file type it is formatting.

// Before --insert-pragma --write
const user = { name: "Ada", "user-id": 7 };

// After --insert-pragma --write
/**
 * @format
 */

const user = { name: "Ada", "user-id": 7 };

The docblock is created if the file does not have one. If the file already has a docblock, the marker is added as a new line within it. The flag does not add a second docblock or place the marker in a line comment .

b. The companion relationship with `--require-pragma`

The two flags are designed to work together, but they are not used in the same command. The --insert-pragma flag is for the file that is being migrated. The --require-pragma flag is for the codebase as a whole.

# The migrating developer runs this on the file they are editing.
npx prettier src/app.js --insert-pragma --write

# The CI pipeline runs this on the whole codebase.
npx prettier "src/**/*.js" --require-pragma --check

The CI check skips the unmarked files because --require-pragma is set. It checks the marked files because they have the marker. The marked set grows as developers run --insert-pragma on the files they touch. The CI enforcement grows with it .

// A Git-based script that marks the files changed in the branch.
import { execSync } from "node:child_process";

const changedFiles = execSync(
  "git diff --name-only origin/main...HEAD",
  { encoding: "utf8" }
)
  .split("\n")
  .filter((f) => f.endsWith(".js") || f.endsWith(".ts"));

for (const file of changedFiles) {
  execSync(`npx prettier "${file}" --insert-pragma --write`);
}

The script is the automation pattern. It lists the files that changed in the branch and runs --insert-pragma --write on each one. The formatted and marked files are committed with the developer’s changes. The unmarked set shrinks with the code that is actually being reviewed.

Complete Example Session

// ============================================
// PART 1: THE FILE BEFORE MIGRATION
// ============================================

// src/app.js
const user = { name: "Ada", "user-id": 7 };

// The file is unformatted and unmarked.
// The --require-pragma flag skips it.

// ============================================
// PART 2: THE INSERT PRAGMA COMMAND
// ============================================

// npx prettier src/app.js --insert-pragma --write

// The file is formatted and marked.
// The marker is in the first docblock.

// ============================================
// PART 3: THE FILE AFTER MIGRATION
// ============================================

// src/app.js
/**
 * @format
 */

const user = { name: "Ada", "user-id": 7 };

// The marker is in the first docblock.
// The file is now opted in to Prettier.

// ============================================
// PART 4: THE CI CHECK
// ============================================

// npx prettier "src/**/*.js" --require-pragma --check
//
// The marked file is checked.
// The unmarked files are skipped.
// The CI passes for the marked set.

// ============================================
// PART 5: THE MARKER PLACEMENT
// ============================================

// If the file already has a docblock:
/**
 * @file Description
 */
const x = 1;

// After --insert-pragma --write:
/**
 * @file Description
 * @format
 */
const x = 1;

// The marker is added to the existing docblock.

// ============================================
// PART 6: THE LANGUAGE VARIATION
// ============================================

// JavaScript:  /** @format */
// HTML:        <!-- @format -->
// Markdown:    <!-- @format -->
// YAML:        # @format

// The flag writes the correct form for the file type.

// ============================================
// PART 7: THE PRIORITY RULE
// ============================================

// If both flags are set:
// npx prettier src/app.js --insert-pragma --require-pragma
//
// --require-pragma takes priority.
// --insert-pragma is ignored.
// The file must already have the marker to be formatted.

// ============================================
// PART 8: THE MIGRATION COMPLETION
// ============================================

// When the unmarked set is small enough:
// 1. Remove --require-pragma from the CI script.
// 2. Run prettier --write . on the remaining files.
// 3. Remove --insert-pragma from the developer workflow.
// 4. The pragmas are inert after --require-pragma is removed.

// ============================================
// PART 9: THE EDITOR INTEGRATION
// ============================================

// The VS Code Prettier extension has an "Insert Pragma" setting.
// It adds the marker when the file is formatted.
// The setting is the editor equivalent of the CLI flag.

// ============================================
// PART 10: THE VERIFICATION CHECKLIST
// ============================================

// [ ] The --write flag is used with --insert-pragma.
// [ ] The marker is placed in the first docblock.
// [ ] The CI uses --require-pragma to skip unmarked files.
// [ ] The migration script runs on the changed files.
// [ ] The flags are removed when the migration is complete.

The ten parts covered the before state, the command, the after state, the CI check, the marker placement, the language variation, the priority rule, the completion, the editor integration, and the verification. The through-line is that the flag formats and marks in one operation, and the marking is the opt-in.

Quick Reference

The flag

Flag	Effect	Requires
`--insert-pragma`	Format and insert `@format`	`--write` to modify the file

The marker forms

Language	Marker
JavaScript / TypeScript	`/** @format */`
HTML / Markdown	`<!-- @format -->`
YAML	`# @format`

The companion flags

Flag	Purpose	Who uses it
`--insert-pragma`	Mark the files being migrated	Developers
`--require-pragma`	Format only the marked files	CI and the team

The priority rule

Combination	Effect
Both flags set	`--require-pragma` wins; `--insert-pragma` is ignored

Best Practices

✅ Do This:

# Use --write with --insert-pragma
npx prettier src/app.js --insert-pragma --write                  // ✅

# Use --require-pragma in CI during the migration
npx prettier "src/**/*.js" --require-pragma --check             // ✅

# Run the migration script on the changed files
git diff --name-only origin/main...HEAD | xargs npx prettier --insert-pragma --write // ✅

❌ Don’t Do This:

# Use --insert-pragma without --write
npx prettier src/app.js --insert-pragma                         // ❌ (prints to stdout)

# Use both flags in the same command
npx prettier src/app.js --insert-pragma --require-pragma        // ❌ (require wins)

# Leave --insert-pragma in the workflow after the migration
// New files are marked, but the flag is no longer needed.       // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The file is not modified	`--write` is missing	Add `--write`
The marker is not recognized	It is in a line comment or a later comment	Use `--insert-pragma` to place it correctly
The migration never completes	The flag is left in the workflow	Set a completion date and remove it
The marker is in the wrong language syntax	The file type is not recognized	Check the file extension

Real-World Examples

1. The basic command

npx prettier src/app.js --insert-pragma --write

2. The marker

/** @format */

3. The existing docblock

/**
 * @file Description
 * @format
 */

4. The CI check

npx prettier "src/**/*.js" --require-pragma --check

5. The Git script

git diff --name-only origin/main...HEAD | xargs npx prettier --insert-pragma --write

6. The HTML marker

<!-- @format -->

7. The YAML marker

# @format

8. The priority rule

# --require-pragma wins when both are set

9. The editor setting

"prettier.insertPragma": true

10. The completion

# Remove --insert-pragma from the workflow

Visual

The Migration Flow

┌──────────────────────────────────────────────────────────────┐
│  INSERT AND REQUIRE                                           │
│                                                              │
│  Developer touches a file                                    │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ --insert-pragma     │  Formats the file                  │
│  │ --write             │  Adds the @format marker           │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The file is marked  │                                    │
│  │ and formatted       │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ CI: --require-pragma│  Only marked files checked         │
│  │ --check             │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Marker Placement

┌──────────────────────────────────────────────────────────────┐
│  THE MARKER GOES IN THE FIRST DOCBLOCK                        │
│                                                              │
│  ✅ Correct:                                                  │
│  /**                                                         │
│   * @format                                                  │
│   */                                                         │
│  const x = 1;                                                │
│                                                              │
│  ❌ Wrong (line comment):                                     │
│  // @format                                                  │
│  const x = 1;                                                │
│                                                              │
│  ❌ Wrong (later comment):                                    │
│  const x = 1;                                                │
│  /** @format */                                              │
└──────────────────────────────────────────────────────────────┘

The Two Flags

┌──────────────────────────────────────────────────────────────┐
│  INSERT VS REQUIRE                                            │
│                                                              │
│  --insert-pragma              --require-pragma               │
│  ┌─────────────────────┐     ┌─────────────────────┐        │
│  │ Formats and marks   │     │ Formats only the    │        │
│  │ the file            │     │ marked files        │        │
│  │                     │     │                     │        │
│  │ Used by developers  │     │ Used by CI          │        │
│  │ during migration    │     │                     │        │
│  └─────────────────────┘     └─────────────────────┘        │
│                                                              │
│  When both are set, --require-pragma wins.                  │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Flag	`--insert-pragma`
Introduced	v1.8.0
Marker	`@format`
Placement	First docblock comment
Companion flag	`--require-pragma`
Priority	`--require-pragma` wins when both are set
Requires	`--write` to modify the file
Purpose	Mark files during gradual adoption

Key takeaways:

--insert-pragma formats the file and inserts the marker. The marker is @format in the file’s first docblock comment. The flag is the mechanism that adds the opt-in marker that --require-pragma looks for .
The marker placement is automatic. The flag finds the first docblock and adds the marker, or creates a docblock if none exists. The automatic placement eliminates the error where the marker is present but not recognized because it is in a line comment or a later comment .
The flag is for the migration, not for the whole codebase. The developers run it on the files they are touching. The CI runs --require-pragma --check on the whole codebase, which skips the unmarked files and checks the marked ones. The marked set grows with the code that is actually being reviewed .
The two flags are not used in the same command. When both are set, --require-pragma takes priority and --insert-pragma is ignored. The flags are used in separate phases: --insert-pragma for the migration, --require-pragma for the enforcement.
The marker is language-specific. For JavaScript and TypeScript, it is /** @format */. For HTML and Markdown, it is . For YAML, it is # @format . The flag writes the correct form for the file type.

Remember: --insert-pragma is the marking mechanism for gradual adoption. It formats the file and adds the @format marker to the first docblock. The marker is the opt-in that the --require-pragma flag looks for. The two flags work together: the developers mark the files they touch, and the CI enforces formatting on the marked set. The migration ends when the unmarked set is small enough to format in one commit, and the flags are removed. The marker is the file’s permanent opt-in, and the flag is the mechanism that adds it.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!