discord.js v14 migration blocked by lagging ecosystem plugins

Decision Criteria: Stay on v13 vs Migrate Core and Bridge Plugins

Choose stay on v13 only if all three conditions hold:

• The bot runs in a fully isolated, non‑internet‑facing environment (no external traffic, no webhook exposure).
• Every critical plugin has an active v13 maintenance fork or the maintainer has committed to backporting security fixes.
• A hard migration deadline exists within 6 months (e.g., a scheduled rewrite or platform change).

Otherwise, migrate core to v14 and bridge plugin gaps. This path carries lower long‑term risk when:

• Your code uses less than 30 % of each lagging plugin’s public API surface.
• You can type shim layers with TypeScript interfaces that match v14 signatures.
• The team can allocate 1–2 sprints for fork maintenance and incremental replacement.

Safe Stubbing / Forking Patterns

Thin Adapter Package

Create a local package (e.g., mybot-discord-shim) that re‑exports only the subset of v13 plugin APIs your code actually calls, implemented against v14 primitives. This isolates churn and lets you replace the shim incrementally.

Minimal Fork with Patch Entry

If a plugin is unresponsive for >90 days, fork only the files you need. Add a patch: entry in package.json pointing to the local fork and open upstream PRs for any fixes. Avoid forking entire repositories.

Replacement Candidates (Active v14 Support)

• Command framework: @sapphire/framework
• Voice/audio: @discordjs/voice (≥0.8) or discord-player

Verification Steps Before Committing

1. List every third‑party plugin in package.json; check GitHub for branches/tags named v14, next, or main with commits <6 months old.
2. Run npm ls discord.js (or Yarn/pnpm equivalent) to see the full dependency tree and identify strict peer‑dependency ranges.
3. Create a test branch: upgrade discord.js to ^14, install with --legacy-peer-deps, run the test suite. Count runtime errors vs compile errors.
4. For each failing plugin, grep your codebase for imports from that package. If <5 distinct symbols are used, a shim is viable.
5. Confirm Node.js version in CI/CD and hosting — v14 requires ≥16.9.0.

One Diagnostic Detail Needed

How many distinct plugin APIs (imported symbols) does your codebase actually consume from each lagging dependency? This number determines whether a shim is practical or a full fork/replacement is required.