Updates all instances across the codebase where debug logging is enabled by checking only the existence of the NEXT_PRIVATE_DEBUG_CACHE environment variable to instead check the truthy or falsy value of the variable.

Problem

Previously, debug logging was enabled whenever NEXT_PRIVATE_DEBUG_CACHE was set to any value, including falsy values like '0', 'false', or 'no'. This made it difficult to explicitly disable debug logging once enabled.

// Before: This would enable debug logging
process.env.NEXT_PRIVATE_DEBUG_CACHE = 'false'
const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE ? console.log : undefined

Solution

Created a centralized helper function isDebugCacheEnabled() that properly checks for specific truthy values:

• Enables debug logging when set to: '1', 'true', 'yes' (case-insensitive)
• Disables debug logging when set to: '0', 'false', 'no', empty string, or unset

// After: Proper truthy/falsy handling
process.env.NEXT_PRIVATE_DEBUG_CACHE = 'false'
const debug = isDebugCacheEnabled() ? console.log : undefined // debug is undefined

Changes Made

• Added packages/next/src/server/lib/debug-utils.ts with the isDebugCacheEnabled() helper function
• Updated 7 core files to use the helper function:
  • packages/next/src/server/use-cache/handlers.ts
  • packages/next/src/server/use-cache/use-cache-wrapper.ts
  • packages/next/src/server/app-render/app-render.tsx
  • packages/next/src/server/route-modules/app-route/module.ts
  • packages/next/src/server/lib/incremental-cache/file-system-cache.ts
  • packages/next/src/server/lib/incremental-cache/index.ts
  • packages/next/src/server/lib/cache-handlers/default.external.ts
• Updated examples/cache-handler-redis/cache-handler.js to use proper logic inline
• Added comprehensive tests to verify the new behavior

Backward Compatibility

This change maintains backward compatibility for common use cases:

• Setting NEXT_PRIVATE_DEBUG_CACHE=1 or NEXT_PRIVATE_DEBUG_CACHE=true continues to work
• The change only affects edge cases where someone was setting it to explicitly falsy values

Testing

The helper function correctly handles all edge cases including:

• Case-insensitive matching ('TRUE', 'Yes' work)
• Whitespace trimming (' true ' works)
• Proper falsy handling ('0', 'false', 'no', '', undefined)

This pull request was created as a result of the following prompt from Copilot chat.

Update all instances across the codebase where debug logging is enabled by checking only the existence of the NEXT_PRIVATE_DEBUG_CACHE environment variable (e.g., process.env.NEXT_PRIVATE_DEBUG_CACHE), so that it instead checks the truthy or falsy value of the variable. Specifically, debug logging should only be enabled if NEXT_PRIVATE_DEBUG_CACHE is set to one of: '1', 'true', 'yes' (case-insensitive), and should not be enabled if set to '0', 'false', 'no', or unset. For example, update the logic in packages/next/src/server/use-cache/handlers.ts and any other file where NEXT_PRIVATE_DEBUG_CACHE is used for enabling debug logs by mere existence. Add a helper function if multiple places use this pattern, and update all usages accordingly. Reference this request for context.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.