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.

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
Copyright © 2026