Astro Plugin Peer Dependency Pinning

The Lesson

In the Astro ecosystem, plugin packages (@astrojs/*) release independently of the core framework and frequently break peer dependency compatibility. Pin plugin versions explicitly and test upgrades in isolation rather than accepting latest.

Context

An Astro 5 static site used @astrojs/mdx for rendering MDX content collections across 12 regulatory topic pages. During a routine dependency update, the latest version of @astrojs/mdx was installed, which declared a peer dependency incompatible with the installed Astro 5 version.

What Happened

1. The project was set up with Astro 5 and @astrojs/mdx at a compatible version.
2. A dependency update pulled in a newer @astrojs/mdx that required a different Astro version range.
3. The build broke with peer dependency resolution errors — npm could not reconcile the version constraints.
4. The fix was downgrading @astrojs/mdx to version 4.3.14, the last release compatible with Astro 5.
5. The downgrade removed 193 lines of unnecessary lock file entries and restored a clean build.

Key Insights

• Astro plugins version independently of Astro core. Unlike monorepo-managed plugin ecosystems (e.g., Gatsby), @astrojs/* packages can release breaking peer dependency bumps without a corresponding Astro core release. You cannot assume "latest plugin works with latest framework."
• Lock file churn is a signal of dependency trouble. The fix reduced package-lock.json by 193 lines — the bloat came from npm trying to resolve incompatible peer trees. Large lock file diffs after a minor update warrant investigation.
• Pin with ~ or exact versions, not ^. For Astro integrations, "@astrojs/mdx": "~4.3.14" prevents accidental minor-version jumps that introduce peer conflicts. Use ^ only when you've verified the next minor works.
• Test plugin upgrades separately from feature work. Mixing "upgrade dependencies" with "add new feature" makes it hard to isolate which change broke the build. Upgrade plugins in a dedicated commit.

Applicability

Applies to any project in a framework ecosystem where plugins/integrations version independently (Astro, Next.js plugins, Vite plugins). Less relevant for ecosystems with lockstep versioning (e.g., Angular's synchronized package releases).