Provide an option to log Fast Refresh debugging information

[kyleschaeffer]

Goals

1. Improve the transparency of the Fast Refresh feature
2. Provide an option to enable logging of debugging information, detailing why a particular update triggers an HMR update vs. a full page reload

Non-Goals

No response

Background

Our team performed an upgrade of a large Next.js application from version 13.4.19 to the latest 14.1.0, which appears to have included significant changes to the way the HMR server handles fast refresh vs. full page reloads. Even after several large-scale attempts to revise components and code to adhere to the limitations and tips provided by the official Next.js documentation, we continue to encounter what appear to be random full page reloads, and have thus far been unable to determine exactly what is triggering them.

We have no idea why this happens, and have unfortunately been unable to debug this issue because the HMR server provides no information as to what triggers an HMR update vs. a full page reload. The full page reloads are particularly disruptive because some tasks (such as working with features that await long-running fetch responses, or working with features that use session-based states) have become extremely difficult to perform.

Proposal

A straightforward way to provide access to HMR debugging information would be to surface a new argument in the next dev CLI command:

next dev -p 3000 --fast-refresh-logging

While enabled, I would expect the dev server output to be agumented with additional information about each incremental compilation:

 ✓ Compiled in 130ms (1261 modules)
    - Updated src/components/Button.tsx
    - Compiled src/components/Button.tsx
    - Using Fast Refresh to update application
 ✓ Compiled in 209ms (2812 modules)
    - Updated src/config/theme.ts
    - Compiled src/components/ThemeProvider.tsx
    - Compiled src/components/Card.tsx
    - Using Fast Refresh to update application
 ✓ Compiled in 670ms (3347 modules)
    - Updated src/components/Avatar.tsx
    ⚠️ File src/components/Avatar.tsx is imported by files outside of the React tree
      See https://nextjs.org/docs/architecture/fast-refresh for more information about Fast Refresh
    ⚠️ Using full page reload to update application