Package · dependencies
PKG0003Keep optional peers optional at the default entrypoint
Find optional peers loaded unconditionally by a package's default JavaScript entrypoint or its required local imports.
vite-doctor/packagedependencieswarnSuggestion
Why it happens
peerDependenciesMeta.optional lets consumers omit a peer. A static import, re-export, or unconditional load from the default entrypoint still requires that peer, so loading the library can fail before an optional integration is used.
Fix
Remove optional: true if every consumer needs the peer. Otherwise defer loading it until the integration is requested and handle absence, or expose that integration through a dedicated subpath that the default entrypoint does not load. Doctor conservatively skips guarded and deferred loads; it does not prove that their error handling is correct.
Example
Load an optional peer only when its integration is requested
Before
import peer from "optional-peer";
export const core = () => "ready";
export const integration = () => peer();
After
export const core = () => "ready";
export async function integration() {
try {
const { default: peer } = await import("optional-peer");
return peer();
} catch {
throw new Error("Install optional-peer to use this integration");
}
}
Verify the fix
Run only this rule after editing so the report stays focused on the diagnostic you are closing:
pnpm vite-doctor . --extends package/recommended --rules package/no-required-optional-peer