Package

Package rules
Diagnose dependency contracts in a library's built output, its manifest, and the lockfile.

The Package Rule Pack analyzes existing files exposed by a package manifest, the manifests of a workspace, and its pnpm lockfile. It is opt-in and works with JavaScript and TypeScript libraries, including framework modules.

Build the library first, then run:

pnpm vite-doctor . --extends auto,package/recommended

From a workspace root, Doctor analyzes the root package and every workspace package declared by pnpm-workspace.yaml or the workspaces field, each against its own manifest. Run against a single library directory to limit the report to that package, or against a staged package directory when publishing transforms the manifest or output.

Doctor follows exports, main, module, browser, bin, types, typings, and typesVersions, then follows literal imports through local files. Declaration files beside JavaScript entrypoints are included. JSDoc import() types in JavaScript count as declaration references only when no published declaration covers that entrypoint, through types, typings, typesVersions, an export types condition, or a sibling .d.ts, because TypeScript reads the declaration instead. Source files and unrelated output are not scanned by these rules unless an entrypoint references them.

Doctor does not execute build scripts, import package code, install dependencies, or edit the manifest. A declared dependency range is accepted without checking its installed version. Private packages are skipped. Package analysis uses the manifest and files on disk, so rebuild before relying on its findings. It does not validate tarball inclusion, conditional export precedence, or computed import specifiers. Missing referenced output makes the report incomplete. JSON and agent reports include the missing paths under evidenceGaps. Custom loader wrappers and external browser replacements are not analyzed.

You can select the preset in trusted host configuration too:

import { doctor } from "vite-doctor";

export default {
  plugins: [doctor({ extends: ["auto", "package/recommended"] })],
};

Use a standalone Doctor Run after building when the Plugin Surface runs before output has been written.

Phantom dependencies

package/no-phantom-dependencies reports PKG0001 for an external JavaScript reference and PKG0002 for an external type reference. Consumer declarations in dependencies, peerDependencies, or optionalDependencies satisfy the rule. devDependencies do not. A declared @types provider can satisfy a type reference.

Choose dependencies when the library owns the package, and peers when the host must provide it. Doctor suggests that choice without rewriting the manifest or guessing a supported version range. Guarded imports still need a declaration, usually an optional peer.

Required optional peers

package/no-required-optional-peer reports PKG0003 when a peer marked optional is loaded unconditionally from a default entrypoint. Static imports, re-exports, top-level CommonJS loads, and direct top-level awaited imports are followed through required local chunks.

Dedicated integration subpaths that the default entrypoint does not load are allowed. Declarations, guarded loads, deferred loads, and shadowed require calls are skipped. This is a conservative rule, not a proof that every optional integration handles missing peers correctly.

PKG0003 also checks every exports subpath for packages that a dependency's subpath needs but does not install. When a subpath loads another package's subpath unconditionally, such as nitro/kv, Doctor reads that installed package's manifest and output and follows the subpath to the packages it loads unconditionally. A package that installing the dependency does not install, because it is an optional peer, only a devDependency, or undeclared there, such as unstorage for nitro/kv, is reported when the library does not declare it either. A library that declares it as an optional peer gets the same treatment as its own optional peers: only its default entrypoint is reported. A dependency's own default entrypoint is that package's concern and is not followed.

Each diagnostic names the export subpath and the import chain from its entry file to the optional package, one file:line "specifier" per hop.

Make the peer required when every consumer needs it. Otherwise isolate the integration behind a deferred load that handles absence or a dedicated subpath.

Singleton packages

These rules and package/no-unforwarded-peer read manifests, pnpm-workspace.yaml and pnpm-lock.yaml, not built output, so they need no build or install.

Some packages must load once per app: vue, vue-router, pinia, nuxt, nitro, h3, vite, react, react-dom, drizzle-orm, graphql, and yjs. A second copy splits their state or fails their identity checks, so injections, stores and app context go missing, and h3 errors or Drizzle tables from one copy are rejected by the other.

package/no-pinned-singleton reports PKG0005 for an exact version of a singleton in peerDependencies and PKG0006 for one in dependencies or optionalDependencies of a published workspace package. It resolves catalog: through pnpm-workspace.yaml and treats workspace:* as the exact version pnpm publishes. Declare the peer as a range that accepts the app's copy, such as ^3.5.44, and take singletons from the app as peers instead of dependencies.

package/no-duplicate-singleton reports PKG0008 when pnpm-lock.yaml resolves two versions of the same major of a singleton in one install: a workspace package with its dependencies and development dependencies, plus what its linked workspace dependencies publish. Each duplicate is reported once, at the package.json entry where it enters the workspace, with the lockfile path to each version. Copies of one version that differ only by pnpm's peer suffix, and different majors, are not reported. Only pnpm lockfile version 9 is read; other package managers' lockfiles are not.

Add packages to both rules with the singletons option. @scope/* matches a whole scope:

doctor.config.json
{
  "rules": {
    "package/no-pinned-singleton": ["warn", { "singletons": ["comark", "@ai-sdk/*"] }],
    "package/no-duplicate-singleton": ["warn", { "singletons": ["comark", "@ai-sdk/*"] }]
  }
}

Forwarded workspace peers

package/no-unforwarded-peer reports PKG0007 when a published workspace package depends on another workspace package and does not declare that package's required peers. Peers are resolved from the packages above the one that declares them, so an app that installs only the dependent package gets no peer under strict peers, or a copy it does not share. Declarations in dependencies, optionalDependencies, or peerDependencies satisfy the rule; devDependencies do not. Optional peers are skipped.

Add the peer to the dependent package's peerDependencies with the same specifier. If it never loads the code that needs the peer, declare an optional peer instead.

Optional import() outside a try

package/optional-peer-import-in-try reports PKG0004 when JavaScript reachable from an export calls import() with the literal name of an optional peer or optional dependency, and neither a direct await import() in a try body in the same function nor a .catch() or two-argument .then() on the import() handles a missing package. esbuild, and Wrangler and Netlify builds through it, fails a consumer's build on such an import() when the package is not installed, even if the code never runs. A try in a caller, or a loader callback passed to a helper that catches, does not count.

An export that already loads the package unconditionally is dedicated to it, so its import() calls are skipped. Computed specifiers are skipped too, because bundlers leave them for run time. So is build tooling that Node loads directly: exports with a path segment such as cli, vite, nuxt, or test, exports that load a build tool such as vite, @nuxt/kit, or vitest unconditionally, and packages named cli or *-cli.

Copyright © 2026