Capítulo 448 de 456

Fast Refresh

Core Idea

Fast Refresh is React's hot-reload mechanism, built into Next.js since 9.4+, that live-reloads edited files while preserving client-side state whenever it's safe to do so.

Key Concepts

  • File-only-exports-components: editing a file that only exports React components updates and re-renders just that file.
  • Mixed exports: editing a file with non-component exports re-runs that file and everything importing it.
  • Files imported outside the React tree: fall back to a full reload; fix by extracting the shared non-component value into its own file.
  • Syntax errors: fixed automatically without losing component state.
  • Runtime errors: show a contextual overlay; state preserved if the error wasn't during render, otherwise React remounts using updated code; error boundaries retry render on next edit.
  • // @refresh reset: directive to force remount of components in that file on every edit.
  • State preservation limits: class components never preserve state (only function components/Hooks do); files with mixed exports, HOC-wrapped class components, or anonymous default-export arrow functions (export default () => <div />) reset state.
  • Hooks behavior: useState/useRef preserve values across edits (if args/call order unchanged); useEffect/useMemo/useCallback always re-run during Fast Refresh, ignoring their dependency arrays.

Code Examples

// @refresh reset
  • O que demonstra: força remount de todos os componentes do arquivo a cada edição, útil pra ajustar animações de mount.

Anti-patterns

  • Exportar default como arrow function anônima (export default () => <div />): quebra a preservação de estado; use name-default-component codemod pra corrigir em massa.
  • Import com case incorreto ('./header' vs './Header'): quebra tanto fast quanto full refresh.

Key Takeaways

  1. Hooks com dependências sempre re-executam durante Fast Refresh, independente do array de deps, o que reforça a boa prática de escrever useEffect resiliente a re-execuções.
  2. React Strict Mode é recomendado justamente porque ajuda a expor esse tipo de re-execução involuntária.
  3. Error boundaries evitam reset total do app em erros de render, mas não devem ser granulares demais.

Connects To

  • Next.js Compiler (ch449): SWC é o compilador por trás das transformações que habilitam Fast Refresh.
AnteriorAccessibilityPróximoNext.js Compiler