tRPC Request Header Logging & Router Size Optimization

Overview

BlueClerk's tRPC server automatically logs the X-Fetch-Snapshot header from incoming requests to help diagnose Next.js partial prerendering (PPR) and fetch caching behavior. This header indicates whether a request is being served from Next.js's snapshot cache versus a dynamic fetch, making it easier to debug stale data issues and unexpected caching behavior.

Additionally, BlueClerk splits large router files to keep each under Vercel's 4.5MB deployment limit. When routers grow too large with many procedures and imported dependencies, they're refactored into smaller focused files - keeping deployments fast and maintaining code organization.

What Gets Logged

X-Fetch-Snapshot Header

When a tRPC request includes this header:

• Header value - Typically "1" when serving from snapshot cache
• Request context - Which tRPC procedure was called
• Logged to console - Appears in Vercel runtime logs for debugging

Router File Size Management

Why Router Splitting Matters

tRPC routers with many procedures can exceed Vercel's 4.5MB function size limit after bundling with dependencies. When this happens, deployments fail with size errors. BlueClerk keeps routers lean by:

• Splitting query procedures into separate -queries.ts files
• Splitting mutation procedures into separate -mutations.ts files
• Extracting action procedures into separate -actions.ts files
• Moving helper functions to shared utility files

Example: Invoice Router

The invoice router was split into focused files:

• invoice.ts - Main router that merges sub-routers
• invoice-queries.ts - List, getById, search, and filter queries
• invoice-actions.ts - Send, void, duplicate, and status actions
• invoice-line-items.ts - Line item CRUD operations
• invoice-qb-sync.ts - QuickBooks sync procedures
• invoice-payment-link.ts - Payment link generation
• invoice-photos.ts - Photo attachment handling
• invoice-statement.ts - Customer statement generation
• invoice-payment-queries.ts - Unpaid invoice queries
• invoice-payment-mutations.ts - Payment recording

This keeps each file under the size limit while maintaining logical separation of concerns.

When to Split a Router

Split a router when:

• Bundle size approaches 4MB - Check during local builds or deployment logs
• Router has 20+ procedures - Hard to navigate and likely approaching size limits
• Procedures naturally group - Queries vs mutations vs actions
• Imports are heavy - External libraries like Sharp, pdf-lib, or AI clients add significant weight

Benefits

• Faster deployments - Smaller bundles deploy quicker
• Better code navigation - Find procedures faster in focused files
• Clearer organization - Related functionality grouped together
• Vercel compliance - Stay under platform limits without workarounds