sp-next-auth-refresh

클라이언트 사이드에서 NextAuth 세션을 자동 갱신하기 위한 헬퍼입니다. Suzag 계열 Next.js 애플리케이션에서 access token 만료 전에 미리 refresh를 호출하여 /no-access로 튕기는 문제를 방지합니다.

설치

pnpm add sp-next-auth-refresh

Next.js 프로젝트에서는 next.config.js(또는 next.config.ts)에 transpilePackages 옵션을 추가하는 것을 권장합니다.

const nextConfig = {
  transpilePackages: ['sp-next-auth-refresh'],
};
module.exports = nextConfig;

사용법

SessionProvider 하위에 AutoRefreshSessionProvider를 배치하면 됩니다.

import { SessionProvider } from 'next-auth/react';
import { AutoRefreshSessionProvider } from 'sp-next-auth-refresh';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <SessionProvider>
      <AutoRefreshSessionProvider>
        {children}
      </AutoRefreshSessionProvider>
    </SessionProvider>
  );
}

기본 설정은 access token 만료 2분 전에 자동으로 refresh를 시도하며, 실패 시 /login으로 리다이렉트합니다.

옵션

<AutoRefreshSessionProvider
  refreshBufferMs={120_000}
  refreshEndpoint="/api/auth/session?update=true"
  redirectOnError="/login"
  onRefreshSuccess={() => console.log('refreshed')}
  onRefreshError={(error) => console.error(error)}
  refreshOnFocus
  refreshOnVisibility
>
  {children}
</AutoRefreshSessionProvider>

• refreshBufferMs: 만료 몇 ms 전에 refresh 할지 설정합니다.
• refreshEndpoint: refresh 전에 호출할 엔드포인트입니다. 기본은 NextAuth 세션 엔드포인트입니다.
• redirectOnError: refresh 실패 시 signIn으로 이동할 URL입니다.
• onRefreshSuccess / onRefreshError: 성공/실패 콜백입니다.
• refreshOnFocus / refreshOnVisibility: 포커스, visibility 변경 시 추가로 갱신을 시도합니다.

유틸리티

JWT 만료 정보를 확인해야 하는 경우 아래 함수를 사용할 수 있습니다.

import { getTokenExpiry, shouldRefreshToken } from 'sp-next-auth-refresh';

const expiresAt = getTokenExpiry(session.accessToken);
const needsRefresh = shouldRefreshToken(session.accessToken, 120_000);

라이선스

MIT