vite-plugin-dependency-guard

Proactive supply-chain security for your Vite projects

vite-plugin-dependency-guard monitors your project dependencies at build time with multiple security layers. It automatically detects supply-chain risks, maintenance issues, tampering attempts, and known vulnerabilities — all integrated directly into your Vite development workflow.

Why this plugin?

Modern frontend projects rely heavily on third-party packages. Managing dependency security across an entire project tree is complex. This plugin acts as an automated quality gate that runs during vite dev/build and (through Nuxt's Vite integration) nuxt dev/build, helping you catch issues early without replacing traditional tools like npm audit.

Think of it as continuous dependency monitoring — like having a security checkpoint integrated into your development loop.

Features

The plugin performs 6 independent security checks on your dependency tree:

1. Fresh Release Detection 🆕

Detects newly published package versions to identify potential zero-day compromise windows. Brand-new releases are more likely to contain unvetted code.

• What it checks: Release age (how many days old is the latest version?)
• Default threshold: 3 days
• When useful: Catching compromised packages moments after being published to npm

2. Unmaintained Package Detection 🏚️

Flags packages that haven't received updates in a long time, indicating potential abandonment or stale dependencies.

• What it checks: Days since the last release
• Default threshold: 2 years without an update
• When useful: Finding deprecated packages before they become a compliance or security risk

3. NPM Registry Availability 🌐

Reports connection failures or missing packages when querying the npm registry, alerting you to network issues or typos in dependency names.

• What it checks: HTTP response status from npm registry
• Reports: 404 errors (package not found), network timeouts, etc.
• When useful: Catching misconfigured or misnamed dependencies during development

4. Phantom Dependency Detection 👻

Warns when code imports packages that are NOT explicitly declared in your package.json dependencies or peerDependencies. These transitive imports can break unexpectedly during upgrades.

• What it checks: Imports (import "packageName") against declared dependencies
• Scope: Tracks direct imports, not nested transitive imports
• When useful: Catching implicit dependencies that cause "works on my machine" issues

5. File Integrity Baselines 🔐

Detects tampering or unexpected modifications in imported node_modules files by comparing SHA-256 hashes against a stored baseline. Useful for detecting supply-chain attacks or local corruption.

• What it checks: SHA-256 hash of every imported file from node_modules
• Storage: .cache/vite-plugin-dependency-guard/integrity-baseline.json
• When useful: Detecting if a malicious package, npm hijack, or local issue modified your dependencies
• First run: Baseline is automatically created on first load
• Subsequent runs: Hashes are verified; mismatches trigger warnings

6. OSV Live Vulnerability Audit ⚠️

Queries the Open Source Vulnerability (OSV) database for known CVEs and security advisories affecting your dependencies. Runs asynchronously in the background by default.

• What it checks: Known vulnerabilities from osv.dev
• Ecosystem: npm packages
• Caching: Results cached for 24 hours to avoid API rate limits
• Block behavior: Does NOT block vite serve by default (use waitForAuditOnBuild: true to block vite build)
• When useful: Real-time security scanning without depending on external tools

Installation

pnpm add -D vite-plugin-dependency-guard

Usage

Minimal setup

// vite.config.js
import { defineConfig } from 'vite';
import dependencyGuard from 'vite-plugin-dependency-guard';

export default defineConfig({
  plugins: [dependencyGuard()]
});

Advanced setup

// vite.config.js
import { defineConfig } from 'vite';
import dependencyGuard from 'vite-plugin-dependency-guard';

export default defineConfig({
  plugins: [
    dependencyGuard({
      // Error handling
      behavior: 'error',
      
      // Fresh release detection
      minAgeDays: 7,
      
      // Maintenance checks
      maxUnmaintainedYears: 1,
      
      // Exclusions
      exclude: ['vite', '@types/node'],
      
      // Dependency scope
      checkDevDeps: true,
      
      // Caching
      cacheTtlMs: 24 * 60 * 60 * 1000,
      disableCache: false,
      
      // Phantom dependency detection
      detectPhantomDependencies: true,
      
      // File integrity checks
      enableIntegrityCheck: true,
      integrityMaxFileSizeBytes: 2 * 1024 * 1024,
      
      // OSV vulnerability audit
      enableLiveAudit: true,
      waitForAuditOnBuild: false
    })
  ]
});

Nuxt setup (nuxt.config.ts)

// nuxt.config.ts
import dependencyGuard from 'vite-plugin-dependency-guard';

export default defineNuxtConfig({
  vite: {
    plugins: [
      dependencyGuard({
        behavior: 'warn',
        minAgeDays: 3
      })
    ]
  }
});

Options

Cache Management

The plugin uses local caching to avoid repeated registry/API requests:

Set disableCache: true to bypass this cache completely.

Registry & OSV Cache

node_modules/.cache/vite-plugin-dependency-guard/cache.json

• Stores npm registry metadata and OSV vulnerability data
• Each entry cached for cacheTtlMs (default: 24 hours)
• Automatically invalidated and refreshed when TTL expires
• Cleared on npm install / pnpm install

Integrity Baseline

node_modules/.cache/vite-plugin-dependency-guard/integrity-baseline.json

• Stores SHA-256 hashes of imported node_modules files
• Created automatically on first plugin load
• Persists across cache clears (intentionally)
• To regenerate baseline, manually delete this file:

  rm node_modules/.cache/vite-plugin-dependency-guard/integrity-baseline.json

Behavior & Output

During vite dev / nuxt dev (development)

• All 6 checks run synchronously during Vite startup
• Fresh release, maintenance, registry, and phantom dependency issues are reported immediately
• OSV audit runs asynchronously in the background by default
• Does not block the dev server from starting

During vite build / nuxt build (production)

• All 6 checks run as configured
• By default (waitForAuditOnBuild: false), OSV audit runs in background; build proceeds
• With waitForAuditOnBuild: true, build waits for audit to complete before exiting
• If behavior: 'error', any issue will fail the build with exit code 1

Example Console Output

✓ All 42 dependencies passed the configured checks.
(Live audit found no known vulnerabilities from OSV.)

Or with issues:

⚠ react@18.0.0 is only 2 days old (minAgeDays=3).
⚠ some-old-package appears unmaintained: last release was 3.2 years ago (maxUnmaintainedYears=2).
⚠ Phantom dependency detected: lodash is imported but is not declared in dependencies/peerDependencies.
⚠ Integrity mismatch for node_modules/package/index.js: hash changed since baseline. Possible local node_modules tampering.
⚠ OSV: react affected by CVE-2024-1234 (XSS vulnerability in event handling)

Use Cases

🏢 Enterprise Supply-Chain Security

Integrate into your CI/CD pipeline with behavior: 'error' to enforce:

• Minimum release age before internal use
• No unmaintained dependencies
• All packages must have integrity baselines
• Zero known vulnerabilities (OSV audit)

👨‍💻 Development Team Alerts

Use with behavior: 'warn' as a non-blocking safety net:

• Alert developers to risky package versions during local development
• Warn about transitive imports to catch breaking changes early
• Detect local tampering (integrity checks)

📊 Dependency Compliance

Track dependency health metrics:

• How many unmaintained packages in your tree?
• When was each package last updated?
• Which packages have known vulnerabilities?

Compatibility

• Node.js: >=18.0.0
• Vite: ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0

Limitations & Notes

• OSV audit: Runs asynchronously in the background by default and does not block vite serve. Set waitForAuditOnBuild: true if you want vite build to wait for completion.
• Phantom dependencies: Only detects direct imports, not nested transitive re-exports.
• Integrity checks: First run creates the baseline; subsequent runs compare against it. Regenerate the baseline if dependencies are legitimately updated offline.
• npm registry: Fresh release detection depends on accurate publish timestamps in the npm registry.

What This Plugin Does NOT Do

• ❌ Replace npm audit (use both together)
• ❌ Check for license compliance
• ❌ Analyze code for security vulnerabilities (only checks known CVEs via OSV)
• ❌ Enforce version constraints beyond age/maintenance
• ❌ Automatically update or pin dependencies

License

MIT