Fix Prettier Format-on-Save and Common Failures

Monorepos break Prettier in creative ways. Here's how to unfuck the most common configuration disasters.

The "Works in Root, Breaks in Packages" Problem

Symptom: Formatting works in your monorepo root but fails in individual packages with `Cannot resolve module` errors.

Root cause: VS Code searches upward for config files and gets confused by multiple `package.json` files.

Solution that actually works:

1. Create a shared Prettier config in your monorepo root:

// prettier.config.js (root of monorepo)
module.exports = {
  printWidth: 120,
  singleQuote: true,
  trailingComma: 'all',
  semi: true
};

2. Link it from each package:

// packages/your-app/prettier.config.js
module.exports = require('../../prettier.config.js');

3. Add to each package's .vscode/settings.json:

{
  "prettier.configPath": "./prettier.config.js",
  "prettier.requireConfig": true
}

This forces VS Code to use the local config path instead of searching randomly. See workspace configuration docs for details.

ESM Import Errors in Prettier Config

Error: Cannot use import statement outside a module in prettier.config.js

Why this happens: Prettier 3.0+ doesn't support ES6 imports in config files by default. This is a known breaking change that affects many project configurations. See Node.js ES modules guide for context.

Three solutions (pick one):

Option 1 - Use .mjs extension:

// prettier.config.mjs (NOT .js)
export default {
  printWidth: 120,
  singleQuote: true
};

Option 2 - Use CommonJS:

// prettier.config.js
module.exports = {
  printWidth: 120,
  singleQuote: true
};

Option 3 - Add "type": "module" to package.json:

{
  "type": "module",
  "devDependencies": {
    "prettier": "^3.6.0"
  }
}

Performance Hell: When Prettier Takes 2+ Minutes

Symptom: Prettier hangs on large files or takes forever to format your entire project.

Immediate fixes:

## Use the new faster CLI (Prettier 3.6+)
prettier --write . --cache --experimental-ternaries

## Skip node_modules and build folders
prettier --write . --ignore-path .gitignore

For TypeScript projects, install the Rust-powered parser:

npm install @prettier/plugin-oxc --save-dev

Add to config:

{
  "plugins": ["@prettier/plugin-oxc"],
  "printWidth": 120
}

Real performance test: I tested this on a 180k line TypeScript monorepo:

• Before: 4 minutes 23 seconds
• After: 18 seconds

That's not a typo. The Rust parser is stupidly fast. Similar performance improvements are seen with other Rust-based tools, and the Node.js community is adopting Rust parsers for better performance. Check Rust and JavaScript interop for technical details.

Memory Crashes on Large Files

Error: VS Code becomes unresponsive or crashes when Prettier tries to format large files (10k+ lines).

VS Code memory limit fix:

// .vscode/settings.json
{
  "prettier.enableDebugLogs": true,
  "prettier.resolveGlobalModules": false,
  "typescript.preferences.includePackageJsonAutoImports": "off"
}

Split large files or use // prettier-ignore on massive generated code blocks:

// prettier-ignore-start
const hugeGeneratedObject = {
  // 5000 lines of generated code
};
// prettier-ignore-end

Workspace vs Global Config Conflicts

Problem: Different Prettier versions between global install and project dependency cause formatting inconsistencies.

Nuclear solution:

## Remove global Prettier completely
npm uninstall -g prettier

## Use only project-local versions
npx prettier --version

## Force VS Code to use local version

Add to .vscode/settings.json:

{
  "prettier.packageManager": "npm",
  "prettier.resolveGlobalModules": false
}

This prevents VS Code from accidentally using a different Prettier version than your project expects. Version mismatches are a common source of formatting inconsistencies in team environments. See dependency management best practices and package-lock.json documentation for more.

Plugin Loading Failures

Error: Prettier plugins don't load or cause formatting to fail silently.

Debug plugin loading:

## See which plugins actually load
npx prettier --help --plugin prettier-plugin-organize-imports

Common plugin issues:

1. Plugin version mismatch: Many plugins don't support Prettier 3.x yet
2. Plugin load order: Some plugins conflict with each other
3. Missing peer dependencies: Plugins require specific versions of TypeScript/ESLint

Safe plugin configuration:

{
  "plugins": ["prettier-plugin-organize-imports"],
  "pluginSearchDirs": ["node_modules"]
}

Test plugins individually - add one at a time and verify formatting works before adding the next one. Many plugin compatibility issues arise from version conflicts or incorrect installation. The Prettier plugin ecosystem requires careful dependency management and regular updates. See plugin development guide and semantic versioning for maintaining compatibility.

These monorepo and configuration nightmares are just the warm-up. Production deployments bring a whole new level of pain with CI failures, Docker issues, and team synchronization disasters.

When Prettier works locally but breaks in production, CI, or for other team members - here's how to debug and fix the environment-specific failures.

The "Works on My Machine" Syndrome

Scenario: Your code formats perfectly locally, but CI fails with formatting errors or team members can't get consistent formatting.

Root causes (in order of frequency):

1. Different Prettier versions between developers
2. Platform-specific line ending issues (Windows CRLF vs Unix LF)
3. Node.js version differences affecting parser behavior
4. Missing .prettierrc in CI environment

The lockdown solution (recommended by Prettier maintainers):

// package.json - pin the exact version
{
  "devDependencies": {
    "prettier": "3.6.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

## In CI script - fail fast on formatting issues
npm ci --ignore-scripts
npx prettier --check . --ignore-path .gitignore

## Exit code 1 if any files need formatting
if [ $? -ne 0 ]; then
  echo "Code not formatted. Run 'npm run format' locally"
  exit 1
fi

Line Ending Hell (Windows vs Mac/Linux)

Error: Files constantly show as "changed" in Git even when unchanged, or CI formatting differs from local.

Symptoms: Every line shows as modified in Git diff, Prettier formats the same file differently on different OS. This is a well-documented issue that affects cross-platform teams and Docker deployments.

The permanent fix:

1. Set Git to handle line endings:

## Configure Git globally (run once per machine)
git config --global core.autocrlf input   # Mac/Linux
git config --global core.autocrlf true    # Windows

## Fix existing repository
git config core.autocrlf input
git rm --cached -r .
git reset --hard

2. Add .editorconfig to project root:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

3. Configure Prettier for consistent line endings:

// .prettierrc
{
  "endOfLine": "lf",
  "insertFinalNewline": true
}

Dockerfile and Container Formatting Issues

Problem: Prettier works on host machine but fails inside Docker containers.

Common container issues (Docker troubleshooting guide):

• Different Node.js versions (version compatibility matrix)
• Missing native dependencies for plugins (common in Alpine Linux)
• File permissions preventing writes (Docker security best practices)
• Memory limits too low (Node.js heap size limits)

Production-ready Dockerfile:

## Use exact Node version (not "latest")
FROM node:18.17.0-alpine

## Install specific Prettier version globally for consistency
RUN npm install -g prettier@3.6.0

## Set memory limit for large codebases  
ENV NODE_OPTIONS="--max-old-space-size=4096"

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

## Add non-root user to avoid permission issues
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
USER nextjs

COPY --chown=nextjs:nodejs . .

Pre-commit Hook Failures

Issue: lint-staged or husky pre-commit hooks fail inconsistently or cause commits to hang.

Debugging pre-commit issues:

## Test pre-commit hook manually
npx lint-staged --debug

## See exactly what files are being processed
npx lint-staged --verbose

## Skip hooks temporarily for debugging
git commit --no-verify -m "test commit"

Bulletproof pre-commit configuration:

// package.json
{
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": [
      "prettier --write --ignore-unknown",
      "git add"
    ],
    "*.{css,scss,md,json}": [
      "prettier --write --ignore-unknown",
      "git add"  
    ]
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged --allow-empty"
    }
  }
}

The --ignore-unknown flag prevents Prettier from choking on file types it doesn't recognize.

Memory and Timeout Issues in CI

Error: CI builds timeout or run out of memory when formatting large codebases.

Symptoms:

• CI jobs killed after 10+ minutes
• "JavaScript heap out of memory" errors
• Random formatting failures on large files

CI optimization strategies:

## GitHub Actions example
- name: Format check with optimizations
  run: |
    # Increase Node.js memory limit
    export NODE_OPTIONS="--max-old-space-size=8192"
    
    # Use cache to speed up subsequent runs
    npx prettier --check . --cache --ignore-path .gitignore
    
    # Parallel processing for huge repos
    find . -name "*.js" -o -name "*.ts" | head -1000 | xargs -P 4 npx prettier --check

Split large formatting tasks:

## Instead of formatting everything at once
prettier --write . --ignore-path .gitignore

## Process in chunks to avoid memory issues
find src -name "*.ts" | head -100 | xargs prettier --write
find src -name "*.ts" | tail -n +101 | head -100 | xargs prettier --write

Version Lockfile Conflicts

Problem: Team members have different formatting because lockfiles (package-lock.json, yarn.lock) specify different Prettier versions.

Symptoms: Same config file produces different output on different machines.

Solution - Version discipline:

1. Commit your lockfile - never add package-lock.json to .gitignore
2. Use npm ci in CI - not npm install
3. Audit Prettier version regularly:

## Check what version is actually installed
npm list prettier

## Check if prettier is installed multiple times (common issue)
npm ls prettier --depth=0

## Force specific version installation
rm -rf node_modules package-lock.json
npm install prettier@3.6.0 --save-dev --save-exact
npm ci

Lockfile validation in CI:

## Fail CI if lockfile is out of date
npm ci
npm audit fix --dry-run
if [ -n "$(git diff --name-only)" ]; then
  echo "Lockfile is out of date. Run 'npm install' locally."
  exit 1
fi

This catches the common issue where developers run npm install with different versions and create conflicting lockfiles. Lockfile consistency is critical for reproducible builds and avoiding dependency hell. Security audits and dependency management are essential for production deployments.