Package · dependencies
PKG0004Guard import() of optional packages with try or .catch()
Find import() calls of optional peers and optional dependencies that no try block in the same function and no .catch() handles, in runtime JavaScript reachable from a package export.
vite-doctor/packagedependencieswarnSuggestion
Why it happens
esbuild, and the Wrangler, Netlify, and Vite builds that use it, fails the consumer's build when an import() names a package that is not installed. It keeps the import for run time only when the import() is directly awaited in a try body of the same function or has a .catch() or two-argument .then(). A try in a caller, or a loader callback passed to a helper that catches, does not count.
Fix
Directly await the import() of the optional package inside a try in the function that calls it, and turn a missing package into an error that names the install command. A .catch() on the import() also works.
Example
Keep the import() of an optional peer inside the try
Before
export const loadForge = () => importOptional(() => import("forge"), "forge");
After
export async function loadForge() {
try {
return await import("forge");
} catch (error) {
throw new Error("Install forge to use this integration", { cause: error });
}
}
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/optional-peer-import-in-try