[Next.js] 라우트 변경 / 새로고침 취소하기 (네비게이션 가드)

회원가입, 글쓰기 등 입력 Form 페이지에서 실수로 다른 링크를 클릭하거나, 저장하는 것을 깜빡하고 다른 페이지로 이동하면 유저 입장에서 무척 짜증나는 상황이 된다. 처음부터 폼을 다시 작성하거나 수정해야 하기 때문이다. 임시 저장 기능이 있다면 괜찮지만, 그렇지 않다면 페이지 이탈에 대한 Confirm 단계를 추가해서 사용성을 개선할 수 있다. 실제로 여러 웹 서비스에서 Form 페이지 이탈시 ‘저장하지 않은 내용은 삭제된다’는 안내 문구를 띄운다.

 

구현 방법

---

NextJS 자체적으로 여러 라우트 이벤트를 제공하는데 routeChangeStart는 라우트 변경을 시작할 때 트리거되는 이벤트다. 페이지를 언로드(새로고침)할 땐 window 객체에서 발생하는 beforeunload 이벤트를 이용하면 된다. 대략 아래 4가지 단계를 통해 구현한다.

 

단계별 과정

1. 유저가 Form을 저장하지 않은 상태에서 다른 페이지 이동(라우트 변경) 시도
   a. ⚠️ Prev/Next 버튼을 누른 시점에 이동할 페이지 주소로 주소창 경로가 바뀐다
   b. 🗄 때문에 라우트 변경 취소를 대비해 현재 경로를 임시 저장해둔다
2. routeChangeStart 이벤트 핸들러 실행
3. 유저의 선택에 따라 아래 값을 반환하는 callback 실행
   a. 확인 true : 다른 페이지로 이동(페이지 이탈)
   b. 취소 false : 페이지 이동 취소
4. 유저가 취소 버튼을 눌러 현재 페이지에 머물기로 결정했다면…
   a. 1-b 에서 임시 저장한 경로로 복구 — router.replace(...)
   b. routeChangeError 이벤트를 발생시켜서 라우트 변경 취소

 

주의할 점

임시 저장한 경로로 router.replace를 실행하면(4-a) 라우트 변경을 시도하므로 routeChangeStart 이벤트가 발생한다. 그럼 이벤트 핸들러가 실행돼서 위 과정을 또 다시 반복하며 무한 렌더링된다. 이를 방지하려면 라우트 변경을 취소했을 때만 이벤트 핸들러를 실행하도록 해야 한다. 이를 위해 isKilledRouter 같은 내부 상태로 라우트 변경 취소 여부를 관리한다.

isKilledRouter 값 (라우트 변경 취소 여부)	routeChangeStart 핸들러 실행 여부
true	❌
false	✅

유저가 페이지 이동을 취소한 후 다시 페이지 이동을 시도하는 상황도 고려해야 한다. 즉, 1~4번 단계까지 한 사이클 실행을 마친 뒤에도 다음 사이클에서 이벤트 핸들러가 실행될 수 있도록 isKilledRouter 상태를 false로 바꿔주는 작업이 필요하다.

 

push, replace 차이점 비교

💡 router.replace는 history stack에 있는 가장 마지막 요소를 이동할 경로로 대체한다. 즉 현재 페이지를 새로운 페이지로 덮어쓴다. 그 외엔 router.push와 동일하다. — 참고 포스팅

• push 이용시
  • 이동 : '/' → '/profiles' → '/profiles/smith'
  • 마지막 페이지에서 뒤로가기 후 : 'profiles'
  • history stack: ['/', 'profiles', 'profiles/smith']
• replace 이용시
  • 이동 : '/' (push) → '/profiles' (replace) → '/profiles/smith'
  • 마지막 페이지에서 뒤로가기 후 : '/'
  • history stack: ['/', 'profiles/smith']

 

구현 하기

---

참고 내용

• router.events는 Router 생성자 및 useRouter 훅이 반환하는 인스턴스로 접근할 수 있다.
• then 후속 메서드의 콜백은 마이크로태스크큐에 들어갔다가 콜스택이 비었을 때 실행된다
• NextJS에서 라우팅이 발생하면 데이터 패칭 메서드(get...Props)가 실행된다. 데이터 패칭 메서드를 실행하지 않고 URL을 변경하고 싶을 땐 shallow: true 옵션을 넘긴다. — 참고글
• next/router는 Context API를 사용한다. router.* 메서드를 실행하면 내부 상태 값을 변경하므로 리렌더링이 발생한다. window.history.replaceState를 사용하면 리액트와 상관없는 히스토리 객체를 핸들링하기 때문에 리렌더링이 발생하지 않는다. — 참고글

 

router.replace 사용

커스텀훅이 받는 shouldStopNavigation 파라미터가 true라면 routeChangeStart 이벤트 핸들러가 등록된다. 그 후 유저가 페이지 이동(라우트 변경)을 시도하면 onRouteChange 이벤트 핸들러를 실행한다.

 

❶ onRouteChange() 이벤트 핸들러 실행 — 페이지 이동(유저 액션으로 인해)

• 라우트 변경을 취소한 적이 없으므로 if 조건 통과 후 callback 함수 실행
• 유저가 취소 버튼을 눌러 페이지에 머무르기로 했다면 if(!confirmed) 조건문 실행(2번~)

 

❷ recoverToCurrentPath() 함수 실행

• router.replace(...) 실행
• then 메서드 핸들러는 마이크로태스크 큐에서 대기

 

❸ killRouterEvent() 함수 실행

• isKilledRouter 상태 true로 변경
• routeChangeError 이벤트를 발생 시킴

 

❹ onRouteChange() 이벤트 핸들러 실행 — currentPath 복구

• 2번에서 라우트 변경(router.replace)을 시도했으므로 핸들러가 실행됨
• 3번에서 isKilledRouter 상태를 변경했으므로 if 조건 통과 못하고 종료

 

🔁 ⑷ currentPath 복구에 대한 라우트 변경 완료

🔁 ⑴ 페이지 이동에 대한 ⑶ 라우트 변경 에러 발생 및 clean-up & effect 실행

 

❺ then() 메서드 핸들러 실행

• isKilledRouter 상태 false로 변경 — 다음 라우트 변경시 이벤트 핸들러 실행을 위해
• then 핸들러의 res 인자는 replace 성공 여부를 나타내는 boolean 값 반환

 

💡 /profile/edit 페이지에서 뒤로가기(/profile) 했다고 가정하고 콘솔 출력 내용 작성

// 유틸리티 함수
const getWindow = () => (typeof window !== 'undefined' ? window : null);

// useNavigationInterceptor.ts

const useNavigationInterceptor = (
  shouldStopNavigation: boolean, // 라우트 변경 관련 이벤트 감지 여부(Hook 활성 여부)
  callback: () => boolean, // *ex) () => confirm('...')*
) => {
  const router = useRouter();
  const currentPath = useRef(router.asPath); // 현재 경로 저장
  const isKilledRouter = useRef(false); // 라우트 변경 취소 여부

  const killRouterEvent = useCallback(() => {
    console.log(`killRouterEvent | path: ${location.pathname}`); // ⑶ /profile
    isKilledRouter.current = true;
    Router.events.emit('routeChangeError'); // 라우트 변경 에러 이벤트를 발생시킴
    throw 'Abort route change. You can ignore this error'; // 콘솔에 에러 출력
  }, []);

  const recoverToCurrentPath = useCallback(() => {
    console.log(`beforeReplace | path: ${location.pathname}`); // ⑵ /profile
    router
      .replace(currentPath.current, undefined, { shallow: true })
      .then((res: boolean) => {
        // replace 작업 성공 여부
        isKilledRouter.current = false;
        console.log(`afterReplace | path: ${location.pathname}`); // ⑸ /profile/edit (경로 복구됨)
      });
  }, [router]);

  // 라우트 변경시 실행될 핸들러
  const onRouteChangeStart = useCallback(
    (toUrl: string) => {
      // 라우트 변경을 시작하는 시점에 이동할 경로가 주소창에 미리 반영됨
      console.log(`onRouteChange | path: ${location.pathname}`); // ⑴ /profile, ⑷ /profile
      if (isKilledRouter.current) return;

      const confirmed = callback(); // Confirm 창 선택 결과

      if (!confirmed) {
        recoverToCurrentPath();
        killRouterEvent();
      }
    },
    [callback, killRouterEvent, recoverToCurrentPath],
  );

  // 새로고침시 실행될 핸들러
  const onBeforeUnload = useCallback((e: BeforeUnloadEvent) => {
    e.preventDefault(); // HTML 표준 명세 준수(unload 이벤트 취소)
    e.returnValue = ''; // for Chrome
  }, []);

  useEffect(() => {
    if (shouldStopNavigation) {
      console.log(`effect | path: ${location.pathname}`); // (4-3) /profile/edit
      getWindow()?.addEventListener('beforeunload', onBeforeUnload); // 새로고침
      Router.events.on('routeChangeStart', onRouteChangeStart); // 페이지 이동

      return () => {
        console.log(`cleanup | path: ${location.pathname}`); // (4-2) /profile/edit
        getWindow()?.removeEventListener('beforeunload', onBeforeUnload);
        Router.events.off('routeChangeStart', onRouteChangeStart);
      };
    }
  }, [onBeforeUnload, onRouteChangeStart, shouldStopNavigation]);
};

// useNavigationInterceptor.ts 훅 사용

// isDirty는 react-hook-form의 formState가 반환하는 상태다.
// 필드를 수정했다면 isDirty 값은 true가 된다
useNavigationInterceptor(isDirty, () => {
  return confirm('Warning! You have unsaved changes');
});

 

리팩토링 — history.replaceState 사용 ⭐️

currentPath를 복구할 때 router.replace() 메서드를 호출하면 리렌더링을 트리거하므로 effect 함수가 실행된다. 또한 onRouteChange 이벤트 발생으로 핸들러 중복 호출을 방지하기 위해 isKilledRouter 같은 추가적인 내부 상태도 필요하다.

 

History API의 replaceState() 메서드를 사용하면 조금 더 최적화할 수 있다. replaceState() 메서드는 리액트와 상관없는 히스토리 객체를 핸들링하므로 리렌더링이 발생하지 않는다. 또한 popstate 이벤트를 발생시키기 때문에 onRouteChange 이벤트 핸들러는 호출하지 않는다. 그럼 isKilledRouter 상태도 필요 없어진다.

addEventListener('popstate', (event) => {
  /* replaceState() 메서드 호출시 실행 */
});

 

한편 currentPath에는 router.asPath 값을 저장하고 있다. asPath는 locale과 basePath를 포함하지 않지만, router.replace()를 사용하면 locale을 그대로 유지하므로 큰 문제가 없다.

 

반면 replaceState()를 사용하면 asPath 값이 그대로 주소창에 들어가므로 locale을 포함하지 않게 된다. asPath 대신 location.pathname을 사용하면 locale을 포함한 주소창으로 변경되도록 할 수 있다.

 

// useNavigationInterceptor.ts 개선 코드

// (제거) const isKilledRouter = useRef(false);
const currentPath = useRef(router.asPath); // router.asPath 값으로 임시 할당

const killRouterEvent = useCallback(() => {
  // (제거) isKilledRouter.current = true;
  Router.events.emit('routeChangeError');
  throw 'Abort route change. You can ignore this error';
}, []);

const recoverToCurrentPath = useCallback(() => {
  // (교체) router.replace(...)
  getWindow()?.history.replaceState(null, '', currentPath.current);
}, []);

const onRouteChangeStart = useCallback(
  (toUrl: string) => {
    // (제거) if (isKilledRouter.current) return;
    const confirmed = callback();

    if (!confirmed) {
      recoverToCurrentPath();
      killRouterEvent();
    }
  },
  [callback, killRouterEvent, recoverToCurrentPath],
);

// (추가) useEffect는 화면에 페인팅을 마친 후 실행되므로 window 객체에 접근할 수 있는 시점
useEffect(() => {
  const window = getWindow();
  if (window) currentPath.current = window.location.pathname;
}, []);

// useNavigationInterceptor.ts

// 유틸리티 함수
const getWindow = () => (typeof window !== 'undefined' ? window : null);

const useNavigationInterceptor = (
  shouldStopNavigation: boolean, // 라우트 변경 관련 이벤트 감지 여부(Hook 활성 여부)
  callback: () => boolean, // ex) () => confirm('...')
) => {
  const router = useRouter();
  const currentPath = useRef(router.asPath); // router.asPath 값으로 임시 할당

  const killRouterEvent = useCallback(() => {
    console.log(`killRouterEvent | path: ${location.pathname}`); // ⑶ /profile/edit
    Router.events.emit('routeChangeError'); // 라우트 변경 에러 이벤트를 발생시킴
    throw 'Abort route change. You can ignore this error'; // 콘솔에 에러 출력
  }, []);

  const recoverToCurrentPath = useCallback(() => {
    getWindow()?.history.replaceState(null, '', currentPath.current);
    console.log(`beforeReplace | path: ${location.pathname}`); // ⑵ /profile/edit
  }, []);

  // 라우트 변경시 실행될 핸들러
  const onRouteChangeStart = useCallback(
    (toUrl: string) => {
      // 라우트 변경을 시작하는 시점에 이동할 경로가 주소창에 미리 반영됨
      console.log(`onRouteChange | path: ${location.pathname}`); // ⑴ /profile
      const confirmed = callback(); // Confirm 창 선택 결과

      if (!confirmed) {
        recoverToCurrentPath();
        killRouterEvent();
      }
    },
    [callback, killRouterEvent, recoverToCurrentPath],
  );

  // 새로고침시 실행될 핸들러
  const onBeforeUnload = useCallback((e: BeforeUnloadEvent) => {
    e.preventDefault(); // HTML 표준 명세 준수(unload 이벤트 취소)
    e.returnValue = ''; // for Chrome
  }, []);

  useEffect(() => {
    if (shouldStopNavigation) {
      getWindow()?.addEventListener('beforeunload', onBeforeUnload); // 새로고침
      Router.events.on('routeChangeStart', onRouteChangeStart); // 페이지 이동

      return () => {
        getWindow()?.removeEventListener('beforeunload', onBeforeUnload);
        Router.events.off('routeChangeStart', onRouteChangeStart);
      };
    }
  }, [onBeforeUnload, onRouteChangeStart, shouldStopNavigation]);

  useEffect(() => {
    const window = getWindow();
    if (window) currentPath.current = window.location.pathname;
  }, []);
};

 

위처럼 코드를 개선하고 라우트 변경 / 새로고침을 해보면 아래 3개 메서드만 실행된다. (/profile/edit 페이지에서 폼 수정 후 저장하지 않고 다른 페이지 이동을 시도했다고 가정)

1. onRouteChangeStart — /profile/edit → /profile
2. recoverToCurrentPath — /profile → /profile/edit
3. killRouterEvent — /profile/edit

 

Confirm 확인을 눌렀을 때만 주소창 변경

라우트 변경을 시작하면 이동할 경로가 주소창에 미리 반영된다. 현재는 Confirm 창 취소를 누르면 현재 페이지 경로로 되돌리고(이때 주소창이 바뀌는걸 유저가 확인할 수 있다), 확인을 누르면 미리 반영된 경로가 유지된다.

 

만약 Confirm 창 취소 버튼을 눌렀을땐 주소창에 아무 변화가 없는 것처럼 보이고, 확인을 눌렀을 때만 주소창이 이동할 경로로 바뀌도록 하고 싶다면, replaceState 실행 순서를 살짝 바꿔주면 된다.

 

💡 routeChangeStart 이벤트 핸들러는 ❶url ❷{ shallow }를 인자로 받는다. url은 이동할 경로를 나타낸다 — 정확히 말하면 현재 브라우저에 표시되고 있는 baseUrl을 포함한 주소.

// useNavigationInterceptor.ts

// recoverToCurrentPath -> changePath로 이름 변경
const changePath = useCallback((url: string) => {
  getWindow()?.history.replaceState(null, '', url);
}, []);

const onRouteChangeStart = useCallback(
  (toUrl: string) => {
    // 이동할 경로가 주소창에 미리 반영됨 (이동할 경로 === toUrl)
    changePath(currentPath.current); // 현재 페이지 경로로 변경
    const confirmed = callback(); // Confirm 창 선택 결과

    if (!confirmed) killRouterEvent();
    else changePath(toUrl); // 확인 버튼을 눌렀을 때만 이동할 경로로 변경
  },
  [callback, changePath, killRouterEvent],
);

 

최종 코드 ⚡️

// useNavigationInterceptor.ts

// 유틸리티 함수
const getWindow = () => (typeof window !== 'undefined' ? window : null);

const useNavigationInterceptor = (
  shouldStopNavigation: boolean, // 라우트 변경 관련 이벤트 감지 여부(Hook 활성 여부)
  callback: () => boolean, // ex) () => confirm('...')
) => {
  const router = useRouter();
  const currentPath = useRef(router.asPath); // router.asPath 값으로 임시 할당

  const killRouterEvent = useCallback(() => {
    Router.events.emit('routeChangeError'); // 라우트 변경 에러 이벤트를 발생시킴
    throw 'Abort route change. You can ignore this error'; // 콘솔에 에러 출력
  }, []);

  const changePath = useCallback((url: string) => {
    getWindow()?.history.replaceState(null, '', url);
  }, []);

  // 라우트 변경시 실행될 핸들러
  const onRouteChangeStart = useCallback(
    (toUrl: string) => {
      // 이동할 경로가 주소창에 미리 반영됨 (이동할 경로 === toUrl)
      changePath(currentPath.current); // 현재 페이지 경로로 변경
      const confirmed = callback(); // Confirm 창 선택 결과

      if (!confirmed) killRouterEvent();
      else changePath(toUrl); // 확인 버튼을 눌렀을 때만 이동할 경로로 변경
    },
    [callback, changePath, killRouterEvent],
  );

  // 새로고침시 실행될 핸들러
  const onBeforeUnload = useCallback((e: BeforeUnloadEvent) => {
    e.preventDefault(); // HTML 표준 명세 준수(unload 이벤트 취소)
    e.returnValue = ''; // for Chrome
  }, []);

  useEffect(() => {
    if (shouldStopNavigation) {
      getWindow()?.addEventListener('beforeunload', onBeforeUnload); // 새로고침
      Router.events.on('routeChangeStart', onRouteChangeStart); // 페이지 이동

      return () => {
        getWindow()?.removeEventListener('beforeunload', onBeforeUnload);
        Router.events.off('routeChangeStart', onRouteChangeStart);
      };
    }
  }, [onBeforeUnload, onRouteChangeStart, shouldStopNavigation]);

  useEffect(() => {
    const window = getWindow();
    if (window) currentPath.current = window.location.pathname;
  }, []);
};

 

레퍼런스

---

• Window: beforeunload 이벤트 - Web API | MDN
• DOMContentLoaded, load, beforeunload, unload 이벤트
• Route cancellation · Discussion #32231 · vercel/next.js
• Next JS: Warn User for Unsaved Form before Route Change
• nextjs를 적용하면서 알게 된 사실들

 

---

글 수정사항은 노션 페이지에 가장 빠르게 반영됩니다. 링크를 참고해 주세요