npm run prettier behaves inconsistently between local and CI

[marcaaron]

Problem

Running npm run prettier locally reports success and doesn't make or report any changes, but CI fails with "Prettier diff detected" on the same file. The local and CI prettier behavior is inconsistent.

This could be caused by different prettier/node versions, different config being picked up, or something in scripts/runPrettier.sh behaving differently between environments.

Example workflow failure: https://github.com/Expensify/App/actions/runs/22363352177/job/64722629957

Solution

Investigate why prettier behaves differently locally vs CI. Ensure npm run prettier produces the same results in both environments.

Workaround: Run npx prettier --write <file> directly on the affected file instead of using npm run prettier.

cc @Expensify/mobile-deployers

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @hoangzinh (External)

[melvin-bot]

Triggered auto assignment to @jliexpensify (Bug), see https://stackoverflow.com/c/expensify/questions/14418 for more details. Please add this bug to a GH project, as outlined in the SO.

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022026361538173601277

[MelvinBot]

Proposal

Please re-state the problem that we are trying to solve in this issue.

Running npm run prettier (which invokes scripts/runPrettier.sh) reports "Prettier finished successfully" but does not reliably format all files. Running npx prettier --check <file> afterward still detects formatting issues, and CI fails with "Prettier diff detected." Developers must fall back to npx prettier --write <file> (without --experimental-cli) to actually fix formatting.

What is the root cause of that problem?

The root cause is that scripts/runPrettier.sh uses the --experimental-cli flag (npx prettier --experimental-cli --write .), which activates a completely separate CLI implementation (from @prettier/cli, bundled at node_modules/prettier/internal/experimental-cli.mjs) rather than the legacy CLI (internal/legacy-cli.mjs). This experimental CLI has two critical behavioral differences:

1. Caching is enabled by default.
At experimental-cli.mjs:5125, the experimental CLI defaults cache to true:

const cache3 = "cache" in options ? !!options.cache : true;

The legacy CLI defaults cache to false (legacy-cli.mjs:836-838). When the cache says a file is already formatted and its content hash matches, writeWithPath (experimental-cli.mjs:11707-11709) skips the file entirely without reading, formatting, or writing it:

const data = await cache3.get(filePath);
if (data?.formatted)
  return true; // skips the file

The cache lives at node_modules/.cache/prettier/.prettier-caches/<hash>.json and persists across runs. While the cache uses SHA1 content hashing and invalidates on config/version changes, runPrettier.sh only clears the cache on prettier failure (non-zero exit). Since --write always exits 0 (experimental-cli.mjs:12510 — totalUnformatted && !options.write is always false when write is on), a poisoned cache entry is never automatically cleared.

2. Known formatting differences from the legacy CLI.
GitHub Discussion #17687 confirms that the experimental CLI produces different formatting output for ~10% of files in some projects, even with identical config. This means:

• Files formatted by the experimental CLI may fail npx prettier --check (which uses the legacy CLI)
• Running npx prettier --write <file> (legacy CLI) re-formats to the legacy standard, resolving the issue
• CI runs the experimental CLI on a fresh checkout with no cache, so it processes all files and may produce different formatting than what the user committed

Additionally, Issue #17669 documents that the experimental CLI can silently fall back to default options when loading certain config formats, and prettier-cli Issue #82 reports that --ignore-path doesn't work correctly with the experimental CLI.

What changes do you think we should make in order to solve the problem?

Option A (Recommended — minimal, safe): Add --no-cache to the prettier invocation in scripts/runPrettier.sh to disable the experimental CLI's default caching. Change line 15 from:

npx prettier --experimental-cli --write . "$@"

to:

npx prettier --experimental-cli --no-cache --write . "$@"

This eliminates the cache as a variable while preserving the performance benefits of the experimental CLI's parallel processing. The runPrettier.sh script's existing cache-clearing retry logic (which targets a different cache path than what the experimental CLI uses) would also become unnecessary but can remain as a safety net.

Option B (More conservative): Remove --experimental-cli entirely from scripts/runPrettier.sh and the other npm scripts in package.json (prettier-changed, prettier-watch), falling back to the well-tested legacy CLI. This sacrifices performance but guarantees consistent formatting behavior.

Both options should also remove the --experimental-cli references in .claude/settings.json (the post-tool-use hook for prettier formatting).

What alternative solutions did you explore? (Optional)

• Clearing cache before every run: Adding clear_cache at the start of main() in runPrettier.sh would work but negates the cache's purpose entirely. --no-cache is the cleaner approach.
• Switching the CI check to use --check instead of --write + git diff: This wouldn't address the local developer experience issue and would require the experimental CLI's --check to also use caching consistently.
• Waiting for Prettier 4.0: The experimental CLI is slated to become the default in Prettier 4.0, which should resolve the formatting differences. However, the caching-by-default behavior would likely persist, so --no-cache may still be needed in the runPrettier.sh wrapper.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, or @MelvinBot <your feedback> to refine this analysis.

[roryabraham]

@MelvinBot runPrettier.sh was created with the intention of clearing a poisoned cache if prettier fails and retrying. But it seems like the tricky thing is we don't have a reliable way to detect a poisoned cache. So please implement a PR to get rid of runPrettier.sh and instead invoke the --experimental-cli with --no-cache. Make sure you update all invocations of prettier accordingly (package.json and CI usages) and get rid of the no-longer-used script.