Package · PKG0003

Keep optional peers optional at the default entrypoint

Find optional peers loaded unconditionally by a package's default JavaScript entrypoint or its required local imports.
PKG0003vite-doctor/packagedependencieswarnSuggestion

Run this rule

pnpm vite-doctor . --extends package/recommended --rules package/no-required-optional-peer

Why it matters

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.

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");
  }
}
Copyright © 2026