vercel / vercel/next.js

Fast Refresh breaks in presence of top level await

Open
#84,658 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

React
Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

Link to the code that reproduces this issue

https://github.com/rnbrady/next-15-tla

To Reproduce

Start in dev mode with pnpm dev and open the page:

Step 1: Click to increment the counter
Step 2: Edit the message in the lib/with-tla.ts and save the file
Step 3: Return to the page, you will find the counter has been reset, meaning the Fast Refresh has failed.
Step 4: Edit the code to use lib/without-tla.ts. You will notice the counter no longer resets.

Current vs. Expected behavior

Expected:
Counter state should be preserved. Fast refresh should work.

Current:
Counter state resets. The following is shown which does not explain the problem:

[Fast Refresh] performing full reload

Fast Refresh will perform a full reload when you edit a file that's imported by modules outside of the React rendering tree. You might have a file which exports a React component but also exports a value that is imported by a non-React component file. Consider migrating the non-React component export to a separate file and importing it into both files.

It is also possible the parent component of the component you edited is a class component, which disables Fast Refresh. Fast Refresh requires at least one parent function component in your React tree.

Provide environment information
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0: Thu Dec 19 20:44:10 PST 2024; root:xnu-10063.141.1.703.2~1/RELEASE_ARM64_T6000
  Available memory (MB): 32768
  Available CPU cores: 10
Binaries:
  Node: 24.4.1
  npm: 11.4.2
  Yarn: 3.6.0
  pnpm: 10.15.1
Relevant Packages:
  next: 15.6.0-canary.53 // Latest available version is detected (15.6.0-canary.53).
  eslint-config-next: 15.5.4
  react: 19.1.0
  react-dom: 19.1.0
  typescript: 5.9.3
Next.js Config:
  output: N/A
Which area(s) are affected? (Select all that apply)

React

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

Happens with and without Turbopack.

If TLA is present anywhere in projects or deps, Fast Refresh will fail everywhere, regardless of whether page being refreshed imports the TLA module.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked reproduction by running pnpm dev, then compare lib/with-tla.ts with lib/without-tla.ts while following the next dev Fast Refresh behavior. Confirm that editing the top-level-await version preserves the counter and no longer triggers a full reload, including when Turbopack is disabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nextjs, react
Domain
developer-experience, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.