TIL

Next.js 15에서 after 메서드 활용하는 최신 방법 2025

Next.js 15에서 after 메서드 활용하는 최신 방법 2025
TILPosted On Apr 22, 20258 min read

after

after는 응답(response)이나 프리렌더(prerender)가 완료된 후에 작업을 예약해서 실행할 수 있게 해주는 기능입니다. 쉽게 말해, 사용자에게 응답을 보내는 데 방해가 되지 않아야 하는 작업들—예를 들어 로그 기록, 분석 데이터 수집 같은 부수 효과들—을 뒤로 미룰 때 유용해요.

이 기능은 Server Components (예: generateMetadata 포함), Server Actions, Route Handlers, 그리고 Middleware에서도 사용할 수 있습니다.

사용법은 간단해요. after 함수에 콜백 함수를 넘겨주면, 응답이 끝난 뒤에 그 콜백이 실행됩니다. 그래서 응답 속도를 늦추지 않고도 필요한 작업을 뒤에서 처리할 수 있죠.

추가 팁!

  • 예를 들어, 사용자의 방문 기록을 DB에 저장하는 로직을 after로 실행하면, 방문자 입장에선 페이지가 빠르게 로드되고, 백엔드에서는 기록 작업이 조용히 이루어져 좋은 UX를 만들 수 있어요.
  • 하지만 너무 무거운 작업을 after에 넣으면 서버 자원을 불필요하게 잡아먹을 수 있으니, 적절한 용도로 사용해야 합니다.
  • 만약 처리 중 에러가 나도 응답에는 영향을 주지 않습니다. 에러 핸들링도 따로 챙겨주면 좋아요.

필요하면 예제 코드도 공유해 드릴게요—함께 공부해봅시다!

안녕하세요! 오늘은 Next.js의 서버 컴포넌트에서 after 함수를 어떻게 활용할 수 있는지 간단하게 알려드릴게요.

import { after } from 'next/server'
// 커스텀 로깅 함수
import { log } from '@/app/utils'

export default function Layout({ children }: { children: React.ReactNode }) {
  after(() => {
    // 레이아웃이 렌더링되고 사용자에게 전송된 후에 실행됩니다.
    log()
  })
  return <>{children}</>
}

핵심 포인트!

after 함수는 렌더링이 끝난 다음, 클라이언트에게 응답을 보낸 후 콜백 함수를 실행시키는 역할을 해요. 예를 들면, 로그를 남기거나 데이터를 트래킹할 때 유용하겠죠.

참고: after는 동적 API가 아니에요. 그러니까 이걸 호출한다고 해서 페이지가 자동으로 동적 라우트(dynamic route)가 되는 건 아닙니다.
만약 static page 내에서 사용하면, 이 콜백 함수는 빌드 타임이나 페이지가 다시 검증(revalidate) 될 때 실행됩니다.

after 함수 주요 특징 정리!

파라미터설명
콜백 함수렌더링 직후 실행할 함수. 비동기 콜백도 지원하지만, 응답을 막지는 않음

더 알아두면 좋은 점

  • 서버 컴포넌트라서 클라이언트에서 확인할 수 없는 서버 정보도 수집하기 편합니다.
  • 로그 외에도 꼭 필요한 후처리를 비동기적으로 깔끔하게 처리하고 싶을 때 좋습니다.
  • after의 콜백은 사용자에게 페이지가 전달된 후 실행되니 렌더링 성능에 영향을 주지 않고, 부담 없이 후처리를 맡길 수 있어요.

Next.js로 서버 사이드 렌더링을 다룰 때 이런 후처리 방법을 알고 있으면 성능 튜닝이나 디버깅에 큰 도움이 됩니다. 오늘도 좋은 개발하시길 바라요! 😊

  • 응답(또는 프리렌더링)이 완료된 후 실행될 콜백 함수입니다.

실행 시간(Duration)

after 함수는 기본적으로 플랫폼에서 설정된 최대 실행 시간(또는 라우트별로 설정된 최대 지속 시간) 동안 실행됩니다. 만약 사용하는 플랫폼이 지원한다면, 라우트의 maxDuration 설정을 통해 타임아웃 제한을 조절할 수 있어요.

참고하면 좋은 점

  • 콜백 함수가 너무 오래 실행되면 타임아웃이 발생할 수 있으니, 작업이 오래 걸리는 경우 최대 실행 시간을 적절히 설정하는 것이 중요합니다.
  • 이 기능은 서버리스 환경이나 프리렌더링 작업에서 특히 유용해요. 예를 들어, 데이터를 미리 가져오거나 로깅 작업을 비동기적으로 처리할 때 활용할 수 있답니다.
  • maxDuration 설정이 없는 경우에는 플랫폼 기본값이 적용되니, 꼭 확인해 보세요!

  • after는 응답이 정상적으로 완료되지 않아도 실행이 됩니다. 에러가 발생하거나 notFound 또는 redirect가 호출된 경우에도 마찬가지에요.
  • React 캐시를 활용해서 after 내부에서 호출되는 함수들의 중복 실행을 방지할 수 있어요.
  • after는 중첩해서 사용할 수도 있어요. 예를 들어, after 호출을 감싸는 유틸리티 함수를 만들어서 추가 기능을 덧붙일 수도 있죠.

대안들

after의 주된 용도는 주 응답을 막지 않고 부수적인 작업을 처리하는 거예요. 이 점에서 플랫폼의 waitUntil()이나 프로미스에서 await을 빼는 것과 비슷하지만, 중요한 차이점이 있어요:

구분설명
waitUntil()프로미스를 받아서 요청 수명주기 동안 실행할 작업을 예약해요.
after응답이 완전히 끝난 후에 실행할 콜백을 받아요.
await 제거응답 중에 실행을 시작해 리소스를 이용해요. 또한 서버리스 환경에서는 응답 후 함수 실행을 바로 멈추기 때문에 작업이 중단될 위험이 있어요.

쉽게 말해서 waitUntil()은 백그라운드에서 요청과 함께 작업을 처리하지만 after는 응답이 끝난 후에 작업을 처리해요. await을 쓰지 않는 건 리소스 낭비와 안정성 문제를 초래할 수 있으니 상황에 맞게 선택하는 게 중요해요.

참고로, 서버리스 환경에서는 특히 이런 비동기 작업이 응답 직후에 중단될 위험이 크기 때문에 after나 waitUntil() 같은 명확한 처리방식을 사용하는 게 좋아요. 그리고 React 캐시를 적극 활용하면 함수 호출 중복도 줄이고 성능도 높일 수 있으니 꼭 활용해보세요!

Next.js에서는 'after'를 사용하는 걸 추천해요. 이유는 'after'가 Next.js의 다른 API나 컨텍스트들을 잘 고려해서 설계되었기 때문이죠. 즉, 더 안정적이고 일관성 있게 동작할 수 있다는 뜻이에요.

예제

요청(Request) API와 함께 사용하기

서버 액션(Server Actions)이나 라우트 핸들러(Route Handlers) 내에서 'after' 블록 안에 쿠키(cookies)나 헤더(headers) 같은 요청 관련 API를 사용할 수 있어요. 예를 들어, 어떤 데이터 변경(mutation) 작업 후에 활동 기록을 로그로 남기고 싶을 때 유용하답니다.

실제로 이걸 어떻게 활용할 수 있는지 살짝 보여드릴게요. 간단한 예제로, 사용자가 데이터를 변경한 뒤에 로그를 남기는 경우를 생각해 볼 수 있죠.

(여기에 간단한 코드 예제가 들어가면 더 이해가 쏙쏙 될 텐데, 혹시 필요하면 알려주세요! 제가 바로 준비해드릴게요.)

참고로, Next.js에서 이렇게 'after'를 활용하면 요청에 대한 응답 처리 후에 후처리를 자연스럽게 할 수 있어서, 코드가 깔끔해지고 유지보수도 쉬워진답니다. 여러분도 프로젝트에 적용해 보시면 좋을 것 같아요!

Next.js의 after 훅을 활용해서 서버 액션 후에 로깅 작업을 진행하는 예제를 보여드렸는데요, 여기서 주의할 점이 있어요.

import { after } from 'next/server'
import { logUserAction } from '@/app/utils'

export async function POST(request: Request) {
  // Perform mutation
  after(async () => {
    const userAgent = (await headers().get('user-agent')) || 'unknown'
    const sessionCookie =
      (await cookies().get('session-id'))?.value || 'anonymous'

    logUserAction({ sessionCookie, userAgent })
  })

  return new Response(JSON.stringify({ status: 'success' }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  })
}

문제는 after에서 headers()나 cookies() 같은 request API를 사용할 수 없다는 점이에요. 왜냐하면 Next.js는 Partial Prerendering(부분 프리렌더링)을 지원하기 위해 요청 API를 어떤 컴포넌트가 사용하는지 알아야 하는데, after 훅은 React 렌더링 라이프사이클 이후에 실행되기 때문에 그 제약에 걸려버립니다.

즉, after 내부에서는 요청 관련 API를 호출하면 에러가 발생할 수 있으니 꼭 다른 곳에서 요청 정보를 추출하고, after에는 순수히 후처리 로직만 넣어주는 게 안전해요.

아래는 간단히 Next.js 버전별 after 훅 관련 히스토리를 정리한 표입니다.

Version HistoryDescription
v15.1.0after가 안정화됨 (stable)
v15.0.0-rcunstable_after가 도입됨

이 내용 참고하셔서, after 훅을 활용할 때는 request API 접근 제한을 명심하고, 코드를 설계해보세요. 혹시 after에서 request 정보를 꼭 사용해야 할 경우엔, 요청 데이터를 미리 받고 전달하는 구조로 만들어야 작업이 가능하답니다.

더불어, 이런 구조적 제한은 Next.js가 최적화를 위해 도입한 부분이라, Partial Prerendering 덕분에 페이지 로딩 성능이 좋아지는 장점도 있으니 이해하고 활용하면 유용해요!