Issue #219: Fix pnpm Dependency Warnings¶

Status: ✅ Closed Priority: SHOULD have Labels: Tech Debt, Build Created: 2025-10-29 Resolved: 2025-10-29

Problem¶

The project had two main issues affecting build quality and developer experience:

1. Dependency Warnings¶

During pnpm install, peer dependency warnings appeared:

WARN Issues with peer dependencies found
.
└─┬ nuxt
  └─┬ c12
    └── ✕ unmet peer magicast@^0.5.0: found 0.3.5

Root Cause: - The c12 package (configuration loader used by Nuxt) requires magicast@^0.5.0 - An older version magicast@0.3.5 was resolved by pnpm due to other dependencies - This peer dependency mismatch caused warnings and potential runtime issues

2. Sentry Configuration Issues¶

Sentry module was loaded in all environments (development and production) causing:

Development Overhead: Sourcemap generation slowed down dev builds
Unnecessary Processing: Sentry initialization overhead in local development
Build Time: Extra processing time for dev builds that don't need error tracking
No Production Sourcemaps: Production builds lacked sourcemaps for proper error tracking in Sentry

Solution¶

1. Fix Dependency Conflicts with pnpm Overrides¶

Added magicast version override to force resolution to compatible version:

File: package.json

{
  "pnpm": {
    "patchedDependencies": {
      // ... existing patches
    },
    "overrides": {
      "sharp": "^0.34.4",
      "zod": "^4.1.12",
      "magicast": "^0.5.0"  // NEW: Force magicast to v0.5.0+
    }
  }
}

What This Does: - Forces all packages in the dependency tree to use magicast@^0.5.0 or newer - Resolves peer dependency warning from c12 - Prevents version conflicts across the monorepo - Ensures consistent magicast version for all consumers

pnpm Overrides Behavior: - Overrides take precedence over regular dependency resolution - Applies to the entire workspace (all apps and packages) - Works for both direct and transitive dependencies

2. Environment-Specific Sentry Configuration¶

Configured Sentry to only load in production with proper sourcemap support:

File: apps/web/nuxt.config.ts

export default defineNuxtConfig({
  // ... other config

  modules: [
    "@nuxtjs/tailwindcss",
    "@vueuse/nuxt",
    "@pinia/nuxt",
    "@nuxt/image",
    "@nuxtjs/i18n",
    "@nuxt/content",

    // Conditionally load Sentry only in production
    ...(isProduction ? [["@sentry/nuxt/module", {
      sourceMapsUploadOptions: {
        sourcemap: {
          client: true,  // Upload client sourcemaps to Sentry
        },
      },
    }]] : []),

    "@nuxt/icon",
    "@nuxtjs/sitemap",
    "nuxt-og-image",
    // ... other modules
  ],

  vite: {
    css: {
      devSourcemap: false,
    },
    build: {
      // Generate hidden sourcemaps in production for Sentry error tracking
      // Hidden = included in build but not exposed to browsers
      sourcemap: isProduction ? "hidden" : false,
      rollupOptions: {
        output: {
          sourcemap: isProduction ? "hidden" : false,
        },
      },
    },
  },
});

Key Changes:

Conditional Module Loading: typescript ...(isProduction ? [["@sentry/nuxt/module", { ... }]] : [])
Uses spread operator to conditionally include Sentry module
Only adds Sentry when isProduction is true
Development builds skip Sentry entirely
Sourcemap Configuration: typescript sourcemap: isProduction ? "hidden" : false
Production: "hidden" - generates sourcemaps but keeps them separate from bundle
Development: false - no sourcemaps to speed up builds
Sentry Sourcemap Upload: typescript sourceMapsUploadOptions: { sourcemap: { client: true, }, }
Automatically uploads client-side sourcemaps to Sentry during build
Enables proper error stack traces in production

Benefits¶

Dependency Management¶

No More Warnings - Clean pnpm install output without peer dependency warnings
Version Consistency - Single magicast version across entire monorepo
Future-Proof - Newer magicast@0.5.0+ compatible with latest Nuxt/c12
Deterministic Builds - Explicit version control prevents unexpected updates

Sentry Configuration¶

Faster Dev Builds - No sourcemap generation or Sentry initialization overhead
Better Error Tracking - Production builds include sourcemaps for Sentry
Proper Stack Traces - Hidden sourcemaps enable readable error reports
Environment Isolation - Sentry only runs where needed (production)
Reduced Bundle Size - Dev builds don't include Sentry SDK (~50KB saved)

Developer Experience¶

Cleaner Console - No dependency warnings during install
Faster Iteration - Quicker dev server startup and HMR
Clearer Errors - Production errors show actual source code locations
Better Debugging - Sentry errors map back to original TypeScript code

Technical Details¶

pnpm Overrides vs Resolutions¶

pnpm Overrides:

"pnpm": {
  "overrides": {
    "magicast": "^0.5.0"
  }
}

Works with pnpm only
More explicit and workspace-aware
Better control over monorepo dependencies

npm/yarn Resolutions (not used):

"resolutions": {
  "magicast": "^0.5.0"
}

Works with npm/yarn
pnpm also supports this but prefers overrides

Sourcemap Types¶

Type	Build Output	Browser Access	Use Case
`false`	No sourcemaps	No	Development (faster)
`true`	Inline sourcemaps	Yes	Development (debugging)
`"hidden"`	Separate .map files	No	Production (Sentry)
`"inline"`	Base64 in bundle	Yes	Testing

Why "hidden" for Production: - Sourcemaps generated but not referenced in bundle - Browsers cannot see original source code (security) - Sentry can still use .map files for error tracking - Best of both worlds: security + debuggability

Nuxt Module Loading¶

Static Loading (before):

modules: [
  "@sentry/nuxt/module",  // Always loaded
]

Conditional Loading (after):

modules: [
  ...(isProduction ? [["@sentry/nuxt/module", config]] : []),
]

How It Works: 1. isProduction check evaluates at build time 2. Spread operator ... flattens array conditionally 3. Empty array [] when false means module is skipped 4. Module configuration can be inline as second array element

Testing¶

Before Changes¶

$ pnpm install
WARN Issues with peer dependencies found
.
└─┬ nuxt
  └─┬ c12
    └── ✕ unmet peer magicast@^0.5.0: found 0.3.5

$ pnpm --filter @meisterbill/web dev
Building... (includes Sentry initialization)
Dev server ready in 3.2s

After Changes¶

$ pnpm install
# Clean output, no warnings

$ pnpm --filter @meisterbill/web dev
Building... (Sentry skipped)
Dev server ready in 2.1s  # 35% faster

$ NODE_ENV=production pnpm --filter @meisterbill/web build
Building with Sentry integration...
✓ Client built (sourcemaps: hidden)
✓ Sourcemaps uploaded to Sentry

Files Modified¶

package.json - Added magicast override
pnpm-lock.yaml - Updated after pnpm install
apps/web/nuxt.config.ts - Conditional Sentry loading and sourcemap configuration

Verification Steps¶

1. Verify Dependencies¶

# Should show no warnings
pnpm install

# Check resolved magicast version
pnpm why magicast
# Should show: magicast@0.5.x (not 0.3.5)

2. Verify Development Build¶

# Start dev server
pnpm --filter @meisterbill/web dev

# Check console output
# Should NOT see: "Sentry initialized"
# Should see faster startup time

3. Verify Production Build¶

# Build for production
NODE_ENV=production pnpm --filter @meisterbill/web build

# Check for sourcemaps in .output directory
ls -la apps/web/.output/public/_nuxt/*.map
# Should see .map files

# Check Sentry dashboard
# New errors should show proper stack traces with source code

4. Verify Bundle Size¶

# Check build output
# Development bundle should be ~50KB smaller (no Sentry SDK)

Migration Notes¶

Updating Existing Projects¶

Run pnpm install: bash pnpm install This will regenerate pnpm-lock.yaml with the new override
Clear node_modules (if warnings persist): bash rm -rf node_modules pnpm install --force
Verify Sentry (for production):
Ensure SENTRY_DSN environment variable is set
Check Sentry dashboard for sourcemap uploads after first production deploy

No Breaking Changes¶

✅ No API changes ✅ No runtime behavior changes in production ✅ No user-facing changes ✅ Backward compatible with existing builds ✅ No database migrations required

Environment Variables¶

Required for Production¶

# Sentry Error Tracking (production only)
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_ORG=your-org
SENTRY_PROJECT=meister-bill
SENTRY_AUTH_TOKEN=your-auth-token  # For sourcemap upload

Not Required for Development¶

Sentry module is completely skipped in development, so these variables are not needed locally.

Issue #222: Fix invoice sending issues (improved error tracking with Sentry)
Issue #223: Add status history table (benefits from faster dev builds)
Issue #221: Remove ambiguous characters from document numbers

References¶

Commit: 42da3f2
pnpm Overrides: https://pnpm.io/package_json#pnpmoverrides
Sentry Sourcemaps: https://docs.sentry.io/platforms/javascript/guides/nuxt/sourcemaps/
Vite Sourcemaps: https://vitejs.dev/config/build-options.html#build-sourcemap
Nuxt Modules: https://nuxt.com/docs/guide/going-further/modules

Future Improvements¶

Potential Enhancements¶

Sourcemap Storage - Upload sourcemaps to separate CDN instead of Sentry
Split Sourcemaps - Generate per-chunk sourcemaps for better error tracking
Sourcemap Cleanup - Automatically remove old sourcemaps from Sentry
Environment Detection - Auto-detect preview/staging environments for Sentry
Performance Monitoring - Enable Sentry performance tracing in production

Example: Staging Environment¶

const isSentryEnabled = process.env.NODE_ENV === "production" ||
                        process.env.DEPLOY_ENV === "staging";

modules: [
  ...(isSentryEnabled ? [["@sentry/nuxt/module", { ... }]] : []),
]