dev-docs

BullMQ란 무엇인가

BullMQ는 Redis 위에 구축된 빠르고 견고한 큐 시스템을 구현한 Node.js 라이브러리입니다.

중요 참고 사항

이 큐는 "at least once" 작업 전략을 목표로 합니다. 즉, 일부 상황에서는 하나의 작업이 두 번 이상 처리될 수 있습니다. 이는 주로 워커가 작업 처리 전체 시간 동안 해당 작업의 락을 유지하지 못할 때 발생합니다.

Typescript 정의

원본 URL: https://docs.bullmq.io/bull/install

사용 중인 곳

Bull은 BullMQ의 레거시 버전입니다. 현재도 여전히 널리 사용되고 있기 때문에 새로운 주요 기능 추가는 하지 않지만 버그 수정은 계속 유지보수됩니다. 검증된 큐 라이브러리를 사용하고 싶고 더 나은 TypeScript 통합이나 최신 기능이 꼭 필요하지 않다면, 앞...

index

다음은 Bull에서 자주 구현되는 유용한 패턴의 몇 가지 예시입니다:

커스텀 백오프 전략

재시도 시 내장 백오프 전략만으로 충분하지 않다면 커스텀 전략을 정의할 수 있습니다. 커스텀 백오프 전략은 큐의 함수로 정의됩니다. 작업을 처리하기 위해 지금까지 시도한 횟수가 이 함수의 첫 번째 파라미터로 전달되고, 작업이 실패할 때 발생한 오류가 두 번째 파라미터로...

index

원본 URL: https://docs.bullmq.io/bull/patterns/debugging

작업 수동으로 가져오기

자동 프로세서에 맡기지 않고 큐에서 작업을 수동으로 가져오고 싶다면, 이 패턴이 적합합니다.

메시지 큐

Bull은 영속적인 메시지 큐로도 사용할 수 있습니다. 이는 일부 사용 사례에서 매우 유용한 기능입니다. 예를 들어, 서로 통신해야 하는 두 개의 서버가 있을 수 있습니다. 큐를 사용하면 서버들이 동시에 온라인 상태일 필요가 없으므로, 매우 견고한 통신 채널을 만들 수...

영구 연결

마이크로서비스 아키텍처에서 서브시스템의 핵심 기능 중 하나는, 다른 서비스와의 연결이 끊겨도 이를 자동으로 처리하고 서비스가 실행되는 동안 가능한 한 오랫동안 연결을 유지하는 것입니다.

Redis 클러스터

원본 URL: https://docs.bullmq.io/bull/patterns/redis-cluster

작업 완료 결과 반환

일반적인 패턴 중 하나는, 가능한 한 빠르게 작업을 처리만 하는 큐 프로세서 클러스터가 있고, 별도의 서비스들이 이 프로세서의 결과를 받아서(예: 데이터베이스에 저장) 후속 처리를 하는 경우입니다.

Redis 연결 재사용

표준 큐는 Redis 서버에 3개의 연결이 필요합니다. 일부 상황에서는 연결을 재사용하고 싶을 수 있습니다. 예를 들어 Heroku처럼 연결 수가 제한된 환경이 그렇습니다. 이는 생성자의 옵션으로 처리할 수 있습니다.

빠른 가이드

원본 URL: https://docs.bullmq.io/bull/quick-guide

새로운 배치 옵션: minSize 및 timeout

워커를 설정하여 한 번에 하나의 작업만 처리하는 대신, 한 번에 여러 작업(소위 *batch*)을 최대 지정 개수까지 처리할 수 있습니다. 배치를 사용하는 워커는 일반 워커와 의미 체계와 동작 방식이 약간 다르므로, 함정을 피하려면 아래 예제를 주의 깊게 읽어야 합니다...

변경 로그

[1.4.1](https://github.com/taskforcesh/bullmq-pro/compare/v1.4.0...v1.4.1) (2022-04-19)

원본 URL: https://docs.bullmq.io/bullmq-pro/changelog/changelog-v1

[2.7.1](https://github.com/taskforcesh/bullmq-pro/compare/v2.7.0...v2.7.1) (2022-10-13)

버그 수정

해결:

[4.0.3](https://github.com/taskforcesh/bullmq-pro/compare/v4.0.2...v4.0.3) (2022-11-19)

[5.3.5](https://github.com/taskforcesh/bullmq-pro/compare/v5.3.4...v5.3.5) (2023-06-16)

원본 URL: https://docs.bullmq.io/bullmq-pro/changelog/changelog-v5

[6.11.0](https://github.com/taskforcesh/bullmq-pro/compare/v6.10.0...v6.11.0) (2024-02-26)

ref faster priority jobs

index

그룹을 사용하면 단일 큐를 유지하면서 작업을 그룹별로 분배하여, 각 그룹에 속한 작업이 서로에 대해 하나씩 순차적으로 처리되도록 할 수 있습니다.

index

기본적으로 각 그룹마다 워커가 병렬로 실행할 수 있는 작업 수에는 제한이 없습니다. rate limit를 사용하더라도 처리 속도만 제한할 뿐, 각 그룹에서 동시에 처리되는 작업 수는 여전히 무제한일 수 있습니다.

조회 메서드

모든 그룹에 작업이 몇 개 있는지 알아야 하는 경우가 자주 있습니다:

로컬 그룹 동시성

특정 그룹에 대해 개별 동시성 값을 설정할 수도 있습니다. 이는 서로 다른 그룹을 서로 다른 동시성 계수로 실행해야 할 때 유용합니다.

로컬 그룹 rate limit

때로는 그룹마다 서로 다른 rate limit이 필요합니다. 예를 들어 그룹이 시스템의 특정 사용자를 나타내는 경우, 사용자의 quota나 기타 요인에 따라 해당 그룹에 다른 rate-limit을 적용하고 싶을 수 있습니다.

최대 그룹 크기

최대 그룹 크기를 설정할 수 있습니다. 이는 작업 수를 일정 한도 내로 유지하고, 새 작업을 버려도 되는 경우에 유용합니다.

그룹 일시 중지

BullMQ Pro는 그룹을 전역적으로 일시 중지하는 기능을 지원합니다. 그룹이 일시 중지되면 워커는 해당 일시 중지된 그룹에 속한 어떤 작업도 가져가지 않습니다. 그룹을 일시 중지하면 현재 그 그룹의 작업을 처리 중인 워커는 해당 작업이 완료(또는 실패)될 때까지 계...

그룹 내 우선순위 지정

BullMQ Pro는 그룹별 우선순위를 지원합니다. 그룹과 우선순위 옵션이 *함께* 제공되면 작업은 해당 그룹 내에서 우선순위가 적용됩니다.

속도 제한

원본 URL: https://docs.bullmq.io/bullmq-pro/groups/rate-limiting

그룹용 샌드박스

그룹을 처리할 때 샌드박스를 사용하는 것도 가능합니다. 기본적으로는 표준 BullMQ에서와 동일하게 동작하지만, 예를 들어 프로세서로 전달되는 job 객체에서 속성에 접근할 수 있습니다:

Docker 사용

BullMQ Pro를 설치하려면 taskforce.sh에서 발급한 NPM 토큰을 사용해야 합니다.

상용 라이선스

BullMQ의 상용 버전인 BullMQ Pro는 고급 기능을 제공하며, 라이브러리 작성자로부터 전담 지원을 받을 수 있습니다. 이 패키지는 표준 BullMQ를 대체하는 드롭인 방식으로 쉽게 설치할 수 있어 이러한 새로운 기능에 바로 접근할 수 있습니다.

NestJs

{% hint style="info" %}

변경 이력

프로듀서

원본 URL: https://docs.bullmq.io/bullmq-pro/nestjs/producers

Queue Events 리스너

인스턴스를 등록하려면 데코레이터를 사용해야 합니다:

새 릴리스

BullMQ Pro의 새 릴리스가 있을 때 알림을 받고 싶다면, 새 릴리스마다 자동으로 새 댓글이 작성되는 다음 GitHub 이슈에서 알림을 활성화해 주세요:

Observables

일반적인 promise를 반환하는 대신, 워커는 을 반환할 수도 있으며, 이를 통해 좀 더 고급 사용 사례를 구현할 수 있습니다.

index

앞서 언급했듯이, 는 깔끔한 취소를 가능하게 합니다. 현재는 작업이 최종적으로 취소되기 전 최대 처리 시간을 정의하는 TTL 값을 지원합니다:

index

BullMQ Pro 구독을 이용하면 상업용 지원을 받을 수 있습니다. 가장 최신이며 상세한 약관은 계정의 "BullMQ Pro" 탭을 참고하세요. 아래는 포함 사항에 대한 개괄적인 안내입니다.

텔레메트리

BullMQ 오픈 소스 에디션에서 텔레메트리를 지원하는 것과 같은 방식으로, BullMQ Pro에서도 텔레메트리를 지원합니다. 기본적으로 동일하게 동작하며, 실제로 Pro 버전에서도 BullMQ에서 사용 가능한 동일한 통합을 그대로 사용할 수 있습니다. 따라서 이를 활...

변경 로그

[1.91.1](https://github.com/taskforcesh/bullmq/compare/v1.91.0...v1.91.1) (2022-09-18)

[2.4.0](https://github.com/taskforcesh/bullmq/compare/v2.3.2...v2.4.0) (2022-10-24)

[3.15.8](https://github.com/taskforcesh/bullmq/compare/v3.15.7...v3.15.8) (2023-06-16)

[4.18.3](https://github.com/taskforcesh/bullmq/compare/v4.18.2...v4.18.3) (2025-07-19)

원본 URL: https://docs.bullmq.io/changelog/changelog-v4

변경 로그

index

아키텍처

Bull 큐의 잠재력을 최대한 활용하려면 job의 라이프사이클을 이해하는 것이 중요합니다. 프로듀서가 인스턴스에서 메서드를 호출하는 순간부터, job은 완료되거나 실패할 때까지(기술적으로는 실패한 job도 재시도되어 새로운 라이프사이클을 가질 수 있음) 여러 상태를...

maxRetriesPerRequest

원본 URL: https://docs.bullmq.io/guide/connections

이벤트 수동 trim

BullMQ의 모든 클래스는 큐에서 실행 중인 작업의 수명 주기를 알려주는 유용한 이벤트를 발생시킵니다. 모든 클래스는 이며 서로 다른 이벤트를 발생시킵니다.

커스텀 이벤트 생성

원본 URL: https://docs.bullmq.io/guide/events/create-custom-events

A FlowProducer constructor takes an optional "connection"

BullMQ는 잡 간의 부모-자식 관계를 지원합니다. 기본 아이디어는 모든 자식 잡이 성공적으로 처리될 때까지 부모 잡이 wait 상태(즉, 워커가 가져갈 수 있는 상태)로 이동되지 않는다는 것입니다. 이를 제외하면 부모 잡이나 자식 잡은 일반 잡과 다르지 않습니다.

플로우 일괄 추가

때로는 플로우를 원자적으로 대량 추가해야 할 필요가 있습니다. 예를 들어, 모든 플로우가 생성되거나 아무것도 생성되지 않아야 하는 요구사항이 있을 수 있습니다. 또한 플로우를 대량으로 추가하면 Redis로의 왕복 횟수를 줄일 수 있어 더 빠를 수 있습니다.

부모 작업 계속 진행

{% hint style="info" %}

부모 작업 실패 처리

특정 워크플로에서는 자식 작업 중 하나라도 실패하면 부모 작업이 즉시 실패해야 할 수 있습니다. 옵션을 사용하면 이 동작을 구현할 수 있습니다. 자식 작업에서 이 값을 true로 설정하면, 해당 자식이 실패할 때 부모 작업도 실패로 표시됩니다. 이 효과는 작업 계층 ...

Flow 트리 가져오기

일부 상황에서는 하나의 job과 그 모든 자식, 손자식 등을 함께 가져와야 할 수 있습니다.

의존성 무시

일부 상황에서는 부모 작업이 있을 때, 자식 작업 중 하나가 실패하더라도 이를 무시해야 할 수 있습니다.

자식 의존성 제거

일부 상황에서는 부모 작업이 있고, 그 자식 중 하나의 의존성을 제거해야 할 수 있습니다.

의존성 제거

일부 상황에서는 부모 작업이 있고, 자식 작업 중 하나가 실패할 때 그 관계를 제거해야 할 수 있습니다.

프로덕션으로 배포하기

이 장에서는 BullMQ 기반 애플리케이션을 프로덕션에 배포할 때 견고한 솔루션을 구축할 수 있도록 중요한 고려 사항과 팁을 제공합니다.

index

BullMQ는 함께 사용해 다양한 문제를 해결할 수 있는 4개의 클래스를 기반으로 합니다. 이 클래스들은 *Queue*, *Worker*, *QueueEvents*, *FlowProducer*입니다.

Job Schedulers

Job Scheduler는 지정된 "repeat" 설정에 따라 작업을 생성하는 팩토리 역할을 합니다. Job Scheduler는 매우 유연하여, 고정 간격으로 생성되는 작업, cron 표현식에 따른 작업, 또는 사용자 정의 요구사항 기반 작업 등 다양한 시나리오를 지원...

Job Scheduler 관리

BullMQ에서는 효율적이고 체계적인 백그라운드 작업을 유지하기 위해 Job Scheduler의 수명 주기와 목록을 관리하는 것이 중요합니다. Job Scheduler를 추가하거나 업데이트할 수 있는 upsertJobScheduler 메서드 외에도, removeJobS...

반복 옵션

원본 URL: https://docs.bullmq.io/guide/job-schedulers/repeat-options

반복 전략

BullMQ에는 반복 가능 작업을 생성하기 위한 두 가지 사전 정의 전략이 있습니다. ‘every’ 전략은 간단하며, 초 단위로 측정된 특정 간격마다 작업이 반복되도록 예약할 수 있습니다. 더 복잡한 ‘cron’ 전략은 cron-parser에서 정의한 cron 표현식을...

더 알아보기:

Queue는 서로 다른 유형의 작업을 담을 수 있으며, 이 유형에 따라 작업이 처리되는 방식과 시점이 결정됩니다. 이 섹션에서는 이를 자세히 설명합니다.

중복 제거

BullMQ의 중복 제거(Deduplication)는 특정 식별자를 기준으로 작업 실행을 지연시키고 중복을 제거하는 프로세스입니다. 지정된 기간 동안, 또는 특정 작업이 완료되거나 실패할 때까지 동일한 식별자를 가진 새 작업이 큐에 추가되지 않도록 보장합니다. 대신 이...

Delayed

지연 작업(Delayed jobs)은 가능한 한 빨리 처리되는 대신, 특별한 "delayed set"에 저장되는 특수한 유형의 작업입니다. 지연 시간이 지나면 해당 작업은 일반 작업처럼 처리됩니다.

FIFO

우리가 설명할 첫 번째 작업 유형은 FIFO(*First-In, First-Out*) 유형입니다. 이는 큐에 작업을 추가할 때의 표준 유형입니다. 작업은 큐에 삽입된 순서와 동일한 순서로 처리됩니다.

Getters

큐에 작업이 추가되면, 작업 수명 주기 동안 서로 다른 상태에 있게 됩니다. BullMQ는 이러한 다양한 상태의 정보와 작업을 조회할 수 있는 메서드를 제공합니다.

Job 데이터

원본 URL: https://docs.bullmq.io/guide/jobs/job-data

Job Ids

BullMQ의 모든 job은 고유한 job id를 가져야 합니다. 이 id는 Redis에 데이터를 저장하기 위한 키를 구성하는 데 사용되며, job이 수명 주기 동안 가질 수 있는 여러 상태 사이를 이동할 때 해당 job을 가리키는 포인터로도 사용됩니다.

LIFO

일부 경우에는 작업을 LIFO (*Last-in, First-Out*) 방식으로 처리하는 것이 유용합니다. 이는 큐에 가장 최근에 추가된 작업이 더 오래된 작업보다 먼저 처리된다는 의미입니다.

우선순위 지정

작업에는 옵션도 포함할 수 있습니다. 우선순위를 사용하면 작업 처리 순서는 FIFO 또는 LIFO 패턴을 따르지 않고, 지정된 의 영향을 받습니다.

작업 제거하기

때로는 작업을 제거해야 할 필요가 있습니다. 예를 들어, 잘못된 데이터를 가진 작업이 있을 수 있습니다.

Repeatable

원본 URL: https://docs.bullmq.io/guide/jobs/repeatable

작업 재시도

BullMQ는 이미 완료되었거나 실패한 작업을 프로그래밍 방식으로 재시도할 수 있는 메서드를 제공합니다. 이는 자동 재시도 메커니즘( 옵션으로 구성)과는 다릅니다. 메서드를 사용하면 언제든지 수동으로 작업을 대기 큐로 다시 이동할 수 있습니다.

Stalled

{% hint style="danger" %}

더 읽어보기:

원본 URL: https://docs.bullmq.io/guide/metrics

Prometheus

BullMQ는 Prometheus로 메트릭을 내보낼 수 있는 간단한 API를 제공합니다. 사용하려면 웹 서버에 를 호출하는 엔드포인트를 만들고, Prometheus가 이 엔드포인트에서 메트릭을 스크랩하도록 설정하세요.

마이그레이션

BullMQ 팀은 버그 수정, 새로운 기능, 또는 때때로 호환성이 깨지는 변경 사항이 포함된 새 버전을 정기적으로 릴리스합니다. 프로덕션 환경에서 운영하는 사용자라면 서비스 연속성을 유지하면서 이러한 새 버전으로 업그레이드하는 일이 어렵게 느껴질 수 있습니다. 이 가이...

Bull에서 BullMQ로

Bull과 BullMQ는 이제 너무 많이 분기되어, 실제로 하위 호환성을 보장하기 어렵습니다.

NestJs

설치 과정이 완료되면 루트 에 을 가져올 수 있습니다.

프로듀서

작업 프로듀서는 큐에 작업을 추가합니다. 프로듀서는 일반적으로 애플리케이션 서비스(Nest provider)입니다. 큐에 작업을 추가하려면 먼저 다음과 같이 서비스에 큐를 주입합니다:

Queue 이벤트 리스너

QueueEvents 인스턴스를 등록하려면 데코레이터를 사용해야 합니다:

병렬성과 동시성

이 장에서는 병렬 실행과 동시성에 대한 몇 가지 오해를 바로잡고, 이 두 용어가 BullMQ 큐에 어떻게 적용되는지, 그리고 처리해야 하는 작업 유형에 따라 처리량을 최대화하기 위해 이를 어떻게 활용할 수 있는지 설명합니다.

더 읽어보기:

원본 URL: https://docs.bullmq.io/guide/queues

작업 일괄 추가

원본 URL: https://docs.bullmq.io/guide/queues/adding-bulks

작업 자동 제거

기본적으로 큐 작업이 완료(또는 실패)되면 와 라는 두 개의 특별한 세트에 저장됩니다. 이는 특히 개발 초기 단계에서 작업 결과를 확인하는 데 유용합니다. 하지만 솔루션이 프로덕션 수준에 도달하면, Redis를 크게 유용하지 않은 데이터로 채우지 않도록 보관할 완료된 ...

전역 동시성

전역 동시성 계수는 모든 worker 인스턴스 전체에서 병렬로 처리할 수 있는 job 수를 결정하는 queue 옵션입니다.

전역 속도 제한

원본 URL: https://docs.bullmq.io/guide/queues/global-rate-limit

더 알아보기:

원본 URL: https://docs.bullmq.io/guide/queues/meta

작업 제거

현재 queue 클래스에는 사용 가능한 메서드가 3가지 있습니다:

QueueScheduler

{% hint style="danger" %}

속도 제한

BullMQ는 큐 속도 제한을 제공합니다. 주어진 속도 제한 옵션을 따르도록 워커를 구성할 수 있습니다.

Redis™ 호환성

Redis에는 여러 대안이 있으며 BullMQ는 6.2.0 이상 버전과 완전히 Redis™ 호환되지만, 모든 대안이 제대로 동작하는 것은 아닙니다. 이 섹션에서는 BullMQ를 공식적으로 지원하고, 호환성이 계속 유지되는지 확인하기 위해 저희가 정기적으로 테스트하는 벤...

Dragonfly

Dragonfly의 기능을 최대한 활용하려면 몇 가지 특정 단계가 필요합니다. 가장 중요한 것은 큐 이름을 중괄호를 사용해 지정하는 것입니다. 이 네이밍 규칙을 사용하면 Dragonfly가 각 큐에 스레드를 할당할 수 있습니다. 예를 들어 큐 이름이 라면 로 변경하세요...

Redis™ 호스팅

AWS Elasticache

원본 URL: https://docs.bullmq.io/guide/redis-tm-hosting/aws-elasticache

AWS MemoryDB

AWS는 사용이 쉽고 BullMQ와 완전히 호환되는 Redis™ 7 호환 관리형 데이터베이스를 제공합니다.

실패한 작업 재시도

큐가 작업을 처리하는 동안, 시간이 지나면서 일부 작업이 실패하는 것은 불가피합니다. BullMQ에서 작업은 다음과 같은 경우 실패한 것으로 간주됩니다:

작업 데이터 반환

워커가 처리를 완료했을 때, 경우에 따라 일부 데이터를 반환하는 것이 편리합니다. 이렇게 반환된 데이터는 예를 들어 이벤트를 수신해 접근할 수 있습니다. 이 반환 데이터는 작업의 속성에서 확인할 수 있습니다.

텔레메트리

원본 URL: https://docs.bullmq.io/guide/telemetry

시작하기

이 가이드에서는 BullMQ를 위한 로컬 텔레메트리 환경을 설정하는 방법을 보여줍니다. 이는 더 큰 애플리케이션에 통합할 때 좋은 기반이 됩니다. OpenTelemetry는 널리 지원되는 표준이므로, 애플리케이션 실행 시 생성되는 트레이스와 스팬을 시각화할 수 있는 다...

메트릭 활성화

BullMQ는 트레이스뿐만 아니라 OpenTelemetry를 통한 메트릭 수집도 지원합니다. 메트릭은 완료/실패한 작업 수, 처리 시간과 같이 작업 처리에 대한 정량적 데이터를 제공합니다.

간단한 예제 실행하기

원본 URL: https://docs.bullmq.io/guide/telemetry/running-a-simple-example

Jaeger 실행하기

Jaeger를 실행하는 가장 쉬운 방법은 Docker compose를 사용하는 것입니다. docker가 설치되어 있다면, 이 파일을 실행하면 됩니다:

문제 해결

이 섹션에서는 BullMQ를 사용할 때 마주칠 수 있는 몇 가지 일반적인 오류에 대한 힌트와 해결 방법을 확인할 수 있습니다.

Workers

원본 URL: https://docs.bullmq.io/guide/workers

작업 자동 제거

기본적으로 큐 작업이 완료(또는 실패)되면 세트와 세트라는 두 개의 특수 세트에 저장됩니다. 이는 특히 개발 초기 단계에서 작업 결과를 확인할 수 있어 유용합니다. 하지만 솔루션이 프로덕션 수준에 도달하면, 크게 유용하지 않은 데이터로 Redis가 가득 차지 않도록...

작업 취소

원본 URL: https://docs.bullmq.io/guide/workers/cancelling-jobs

로컬 동시성 계수

BullMQ에서 Worker 인스턴스를 사용해 동시성을 달성하는 방법은 기본적으로 두 가지입니다. 계수를 1보다 크게 설정해 워커를 실행할 수 있고(기본값), 서로 다른 node 프로세스에서 여러 워커를 실행할 수도 있습니다.

정상 종료(Graceful shutdown)

BullMQ는 워커의 정상 종료를 지원합니다. 이는 어떤 이유로든 워커를 종료해야 할 때 중단(stalled) 작업을 최소화하는 데 중요합니다. 다만 "비정상 종료(ungraceful shutdown)"가 발생하더라도, BullMQ의 stalled 메커니즘을 통해 새로...

큐 일시 중지

BullMQ는 큐를 *전역적으로* 또는 *로컬로* 일시 중지하는 기능을 지원합니다. 큐가 *전역적으로* 일시 중지되면 어떤 워커도 해당 큐에서 작업을 가져오지 않습니다. 큐를 일시 중지하면, 현재 작업을 처리 중인 워커는 해당 작업이 완료(또는 실패)될 때까지 계속 처...

샌드박스 프로세서

워커를 별도 프로세스에서 실행하도록 정의하는 것도 가능합니다. 이를 *샌드박스* 프로세서라고 부르며, 나머지 코드와 격리되어 실행됩니다.

중단된 작업

NodeJS는 (일반적으로) 단일 스레드이며 비동기 작업을 처리하기 위해 이벤트 루프로 구성되어 있기 때문에, CPU를 장시간 점유하지 않도록 process 함수를 신중하게 작성해야 합니다.

서로 다른 큐에 작업을 대량으로 추가하기

때로는 여러 큐에 작업을 원자적으로 대량 추가해야 할 필요가 있습니다. 예를 들어, 모든 작업이 생성되거나 아무것도 생성되지 않아야 한다는 요구사항이 있을 수 있습니다. 또한 작업을 대량으로 추가하면 Redis로의 왕복 횟수가 줄어들어 더 빠를 수 있습니다.

중복 제거

때로는 작업 중복 제거를 언제 중단할지 결정하고 싶을 수 있습니다.

Redis가 다운되었을 때 빠르게 실패하기

설계상 BullMQ는 Redis에 자동으로 재연결합니다. 큐 인스턴스가 Redis와 연결이 끊긴 상태에서 큐에 작업이 추가되면 명령은 실패하지 않습니다. 대신, 호출은 재연결이 발생해 완료할 수 있을 때까지 계속 대기합니다.

index

{% hint style="warning" %}

멱등 작업

즉, 작업이 첫 시도에서 성공적으로 완료되든, 처음에는 실패했다가 재시도에서 성공하든 시스템의 최종 상태에는 차이가 없어야 합니다. 이를 *멱등성*이라고 합니다.

수동 재시도

작업이 처리되는 중에 즉시 재시도하는 것이 유용한 상황이 있습니다.

수동으로 job 처리하기

Worker를 생성할 때 가장 일반적인 사용 방식은 process 함수를 지정하여, 큐에 들어오는 job을 워커가 자동으로 처리하게 하는 것입니다.

네임드 프로세서

Worker를 인스턴스화할 때 가장 일반적인 사용 방식은 process 함수를 지정하는 것입니다.

단계별 작업 처리

때로는 processor 함수를, 이전에 실행된 단계에 따라 처리되는 작은 조각으로 나누는 것이 유용합니다. 이런 종류의 로직을 처리하는 한 가지 방법은 switch 문을 사용하는 것입니다.

Redis Cluster

Bull 내부 동작은 서로 다른 키에 걸친 원자적 연산을 필요로 합니다. 이 동작은 클러스터 구성에서의 Redis 규칙을 깨뜨립니다. 하지만 bull prefix 옵션을 클러스터 "hash tag"로 올바르게 사용하면 클러스터 환경을 여전히 사용할 수 있습니다. 해시 ...

작업 재시도 중지

프로세서가 복구 불가능한 예외를 던지는 경우에는 클래스를 사용해야 합니다. 이 경우 BullMQ는 작업을 failed set으로 바로 이동시키고 재시도를 수행하지 않으므로, 작업을 큐에 추가할 때 설정한 값도 무시됩니다.

작업 스로틀링

때로는 자주 발생하는 이벤트에 반응해 작업을 큐에 넣되, *모든* 이벤트마다 해당 작업을 실행하고 싶지는 않을 수 있습니다. 예를 들어 사용자가 프로필을 업데이트할 때 이메일을 보내고 싶지만, 짧은 시간에 여러 변경을 연속으로 수행하는 경우 매번 이메일을 보내고 싶지는...

샌드박스 프로세서의 타임아웃

샌드박스 프로세서를 사용할 때는 모든 작업이 별도의 프로세스에서 실행됩니다. 이로 인해 TTL(time-to-live) 메커니즘을 구현할 수 있으며, 작업이 합리적인 시간 안에 완료되지 못하면 해당 프로세스를 종료할 수 있습니다.

작업 타임아웃

BullMQ는 작업 타임아웃을 위한 특정 메커니즘을 제공하지 않지만, 많은 경우 워커의 process 함수에 커스텀 타임아웃 코드를 넣어 이를 구현할 수 있습니다.

변경 로그

옵션 1: 릴리스 다운로드(권장)

PHP 패키지는 PHP 애플리케이션에서 BullMQ 큐에 작업을 추가할 수 있는 Queue client를 제공합니다. 이렇게 추가된 작업은 Node.js, Python, 또는 Elixir로 작성된 워커가 처리할 수 있습니다.

변경 로그

원본 URL: https://docs.bullmq.io/python/changelog

[0.5.6](https://github.com/taskforcesh/bullmq/compare/vpy0.5.5...vpy0.5.6) (2023-06-21)

원본 URL: https://docs.bullmq.io/python/changelog/changelog-v0

[1.24.0](https://github.com/taskforcesh/bullmq/compare/vpy1.23.0...vpy1.24.0) (2023-12-21)

원본 URL: https://docs.bullmq.io/python/changelog/changelog-v1

시작하기

원본 URL: https://docs.bullmq.io/python/introduction

빠른 시작

{% hint style="info" %}

Codex

Codex는 소프트웨어 개발을 위한 OpenAI의 코딩 에이전트입니다. ChatGPT Plus, Pro, Business, Edu, Enterprise 플랜에는 Codex가 포함됩니다. 다음과 같은 도움을 받을 수 있습니다:

Codex 대사

Codex는 실제 워크플로와 교훈을 서로 나누는 빌더들이 주도하면서 빠르게 가장 강력한 개발 방식 중 하나가 되고 있습니다.

List models (model/list)

Codex app-server는 Codex가 풍부한 클라이언트(ex. Codex VS Code 확장)에서 사용하는 인터페이스입니다. 인증, 대화 기록, 승인, 스트리밍 에이전트 이벤트처럼 자체 제품에 깊이 통합하려면 이것을 사용하세요. app-server 구현은 Cod...

Codex 앱

Codex 앱은 병렬로 Codex 스레드 작업을 처리하기 위한 집중된 데스크톱 환경으로, 자동화, 워크트리 지원, Git 기능이 내장되어 있습니다.

작업 관리

반복 작업을 백그라운드에서 자동화합니다. Codex는 결과가 있으면 인박스에 추가하고, 보고할 내용이 없으면 작업을 자동으로 보관합니다. 더 복잡한 작업을 위해 기술과 자동화를 결합할 수 있습니다.

Codex 앱 명령

이 명령어와 키보드 단축키를 사용해 Codex 앱을 탐색하세요.

Codex 앱 기능

description: 'Codex 앱은 Codex 스레드를 병렬로 작업하기 위한 데스크톱 환경입니다,'

로컬 환경

로컬 환경을 통해 워크트리용 설정 단계와 프로젝트 공통 작업을 구성할 수 있습니다.

표시되는 변경 내용

리뷰 창은 Codex가 변경한 내용을 파악하고, 구체적인 피드백을 주며, 유지할 항목을 결정하는 데 도움을 줍니다.

Codex 앱 설정

설정 패널을 사용하여 Codex 앱의 동작 방식, 파일을 여는 방식, 도구와 연결하는 방식을 조정합니다. 앱 메뉴에서 설정을 열거나 Cmd+,를 누르세요.

문제 해결

프로젝트가 Git 리포지토리 안에 있다면 리뷰 패널이 프로젝트의 Git 상태를 기반으로 변경 사항을 자동으로 표시하며 Codex가 수정하지 않은 변경도 포함됩니다.

작업 트리

Codex 앱에서 작업 트리를 사용하면 같은 프로젝트 내에서 서로 간섭 없이 여러 개의 독립적인 작업을 실행할 수 있습니다. Git 저장소의 경우 자동화는 지속적으로 진행 중인 작업과 충돌하지 않도록 전용 백그라운드 작업 트리에서 실행됩니다. 버전 관리되지 않은 프로젝...

OpenAI 인증

Codex는 OpenAI 모델 사용 시 두 가지 로그인 방법을 제공합니다:

Codex 변경 로그

$ npm install -g @openai/codex@0.104.0

Codex CLI

description: "Codex CLI는 터미널에서 로컬로 실행할 수 있는 OpenAI의 코딩 에이전트입니다. 선택한 디렉터리에서 머신의 코드를 읽고, 변경하고, 실행할 수 있습니다..."

대화형 모드 실행

Codex는 채팅 이상의 워크플로를 지원합니다. 이 가이드를 사용하여 각 기능이 무엇을 열어주고 언제 사용해야 하는지 알아보세요.

명령줄 옵션

export const globalFlagOptions = [

Codex CLI의 슬래시 명령어

슬래시 명령어를 사용하면 Codex를 빠르고 키보드 중심으로 제어할 수 있습니다. 작성기에서 를 입력해 슬래시 팝업을 열고 명령어를 선택하면, Codex가 모델 전환, 권한 조정, 긴 대화 요약 등 터미널을 벗어나지 않고 작업을 수행합니다.

Codex 웹

Codex는 코드를 읽고, 편집하고, 실행할 수 있는 OpenAI의 코딩 에이전트입니다. 더 빠르게 빌드하고, 버그를 수정하며, 익숙하지 않은 코드를 이해하는 데 도움을 줍니다. Codex 클라우드를 사용하면 Codex가 자체 클라우드 환경에서 (병렬 포함) 백그라운드...

Cloud environments

Cloud 작업 중 Codex가 설치하고 실행하는 내용을 제어하려면 환경을 사용하세요. 예를 들어, 종속성을 추가하거나 린터 및 포매터 같은 도구를 설치하고 환경 변수를 설정할 수 있습니다.

에이전트 인터넷 액세스

기본적으로 Codex는 에이전트 단계에서 인터넷 액세스를 차단합니다. 설정 스크립트는 여전히 인터넷 액세스로 실행되어 종속성을 설치할 수 있습니다. 필요한 경우 환경별로 에이전트 인터넷 액세스를 활성화할 수 있습니다.

커뮤니티

Codex 밋업

주최 Agrim Singh & Gabriel

index

커스터마이제이션

커스터마이제이션은 Codex를 팀의 작업 방식대로 작동하게 만드는 방법입니다.

사이버 안전

안전 교육 외에도 자동 분류기 기반 모니터는 의심스러운 사이버 활동 신호를 탐지하고 고위험 트래픽을 보다 사이버 역량이 낮은 모델(GPT-5.2)로 우회시킵니다. 이러한 완화 조치의 영향을 받는 트래픽은 매우 적을 것으로 예상되며, 정책과 분류기, 제품 내 알림을 지속...

멀티 에이전트

Codex는 전문화된 에이전트를 병렬로 생성하고 결과를 하나의 응답으로 모아 멀티 에이전트 워크플로를 실행할 수 있습니다.

고급 구성

프로바이더, 정책, 통합을 더 세밀하게 제어하려면 이러한 옵션을 사용하세요. 빠른 시작은 Config basics를 참고하세요.

설정 기본

description: 'Codex는 여러 위치에서 구성 세부 정보를 읽습니다. 개인 기본 설정은 , 프로젝트 재정의는 파일로 추가할 수 있습니다. 보안상 Codex는인 프로젝트의 구성 파일만 로드합니다...'

구성 참조

이 페이지는 Codex 구성 파일을 위한 검색 가능한 참조입니다. 개념적 안내와 예제를 보려면 Config basics와 Advanced Config부터 시작하세요.

샘플 구성

이 예시 구성을 출발점으로 사용하세요. 여기에는 대부분의 Codex가 에서 읽는 키들과 기본값 및 간단한 설명이 포함되어 있습니다.

사용자 정의 프롬프트

description: '사용자 정의 프롬프트는 더 이상 지원되지 않습니다. 재사용 가능한 스킬을 사용하세요'

엔터프라이즈

관리자 설정

이 가이드는 워크스페이스에서 Codex를 설정하려는 ChatGPT Enterprise 관리자용입니다.

거버넌스

Codex는 엔터프라이즈 팀에 도입 및 영향력에 대한 가시성과 보안/규정 준수 프로그램에 필요한 감사 가능성을 제공합니다. 일상적인 추적에는 셀프 서브 대시보드를, 프로그램 보고에는 Analytics API를, 거버넌스 스택으로 상세 로그를 내보내려면 Complianc...

시작하기

정기 작업을 자동화합니다. Codex는 받은편지함에 찾은 내용을 추가하고 보고할 내용이 없는 실행은 보관합니다.

기능 성숙도

일부 Codex 기능에는 성숙도 레이블이 붙어 있어 각 기능의 신뢰도, 변경 가능성, 기대할 수 있는 지원 수준을 파악할 수 있습니다.

Codex GitHub Action

Codex GitHub Action()을 사용하여 CI/CD 작업에서 Codex를 실행하거나, 패치를 적용하거나, GitHub Actions 워크플로우에서 리뷰를 게시하세요. 이 액션은 Codex CLI를 설치하고 API 키를 제공하면 Responses API 프록시를...

index

AGENTS.md로 사용자 지침 설정

Codex는 작업을 시작하기 전에 파일을 읽습니다. 글로벌 안내와 프로젝트별 재정의를 계층화하면 어떤 리포지토리를 열든 일관된 기대치를 기반으로 작업을 시작할 수 있습니다.

Agents SDK로 Codex 사용하기

title: 'Agents SDK로 Codex 사용하기'

AI-네이티브 엔지니어링 팀 구축

AI 모델은 수행할 수 있는 작업 범위를 빠르게 확장하고 있으며, 이는 엔지니어링에 중대한 영향을 줍니다. 첨단 시스템은 현재 다중 시간의 추론을 지속할 수 있으며, 2025년 8월 기준 METR은 주요 모델들이 정답을 낼 확률이 대략 50%인 상태로 2시간 17분 정...

Codex IDE 확장

Codex는 OpenAI의 코딩 에이전트로, 코드를 읽고 수정하며 실행할 수 있습니다. 더 빠르게 개발하고 버그를 해결하며 생소한 코드를 이해하는 데 도움을 줍니다. Codex VS Code 확장 기능을 사용하면 IDE에서 Codex를 나란히 사용하거나 Codex Cl...

Codex IDE 확장 명령

title: 'Codex IDE 확장 명령'

Codex IDE 확장 기능

Codex IDE 확장을 통해 VS Code, Cursor, Windsurf 및 기타 VS Code 호환 편집기에서 Codex에 바로 접근할 수 있습니다. Codex CLI와 동일한 에이전트를 사용하며, 설정도 공유합니다.

index

Codex IDE 확장 기능 슬래시 명령

슬래시 명령을 사용하면 채팅 입력을 벗어나지 않고 Codex를 제어할 수 있습니다. 상태 확인, 로컬/클라우드 모드 전환, 피드백 전송 등에 활용하세요.

index

GitHub에서 Codex 사용하기

GitHub을 떠나지 않고 Codex로 풀 리퀘스트를 검토하세요. 코멘트를 추가하면 Codex가 표준 GitHub 코드 리뷰로 응답합니다.

Linear에서 Codex 사용하기

이슈에서 작업을 Codex에 위임하려면 Linear에서 Codex를 사용하세요. 이슈를 Codex에 할당하거나 댓글에서 를 언급하면 Codex가 클라우드 태스크를 만들고 진행 상황과 결과를 답글로 알려줍니다.

Slack에서 Codex 사용하기

Slack에서 Codex를 사용해 채널과 스레드에서 코딩 작업을 시작하세요. 프롬프트와 함께 를 언급하면 Codex가 클라우드 작업을 생성하고 결과를 응답합니다.

모델 컨텍스트 프로토콜

모델 컨텍스트 프로토콜(MCP)은 모델을 도구와 컨텍스트에 연결합니다. Codex가 서드파티 문서에 접근하도록 하거나 브라우저나 Figma 같은 개발자 도구와 상호작용하게 하는 데 사용하세요.

Codex 모델

description: '최첨단 코딩 성능과 강화된 추론 및 전문 지식 역량을 결합한 지금까지 가장 능력 있는 대리 코딩 모델입니다.'

index

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize th...

비대화형 모드

비대화형 모드를 사용하면 대화형 TUI를 열지 않고도 스크립트(예: 지속적 통합(CI) 작업)에서 Codex를 실행할 수 있습니다.

index

Codex

!Codex 앱이 프로젝트 사이드바, 스레드 목록, 리뷰 창을 보여주는 모습

Codex 요금제

한시적으로 ChatGPT Free와 Go에서 Codex를 무료로 체험하거나 Plus, Pro, Business, Enterprise 구독으로

프롬프트

description: 'Codex에는 실행시키고 싶은 작업을 설명하는 프롬프트(사용자 메시지)를 보내 상호작용합니다.'

index

git checkout

규칙 파일 생성

원본 URL: https://developers.openai.com/codex/rules

Codex SDK

Codex CLI, IDE 확장 또는 Codex Web을 통해 Codex를 사용하는 경우에도 프로그램적으로 제어할 수 있습니다.

샌드박스 및 승인

Codex는 코드와 데이터를 보호하고 오용 위험을 줄입니다.

에이전트 스킬

Agent 스킬을 사용해 Codex를 작업 전용 기능으로 확장하세요. 스킬은 Codex가 워크플로를 안정적으로 따르도록 설명, 리소스, 선택적 스크립트를 꾸린 단위입니다. 스킬은 팀 간이나 커뮤니티와 공유할 수 있으며, 오픈 에이전트 스킬 표준을 기반으로 합니다.

index

Windows

Windows에서 Codex를 가장 쉽게 사용하는 방법은 IDE 확장 설정이나 CLI 설치를 통해 PowerShell에서 실행하는 것입니다.

작업 흐름

Codex는 명확한 맥락과 “완료” 정의를 갖춘 팀원처럼 다룰 때 가장 잘 작동합니다.

What is BullMQ

BullMQ is a Node.js library that implements a fast and robust queue system built on top of Redis that helps in resolving many modern age micro-service...

Important Notes

The queue aims for an "at least once" working strategy. This means that in some situations, a job could be processed more than once. This mostly happe...

Install

In order to work with Bull, you also need to have a Redis server running. For local development you can easily install it using docker.

Introduction

Bull is the legacy version of BullMQ. As it is still heavily used today, it is also maintained for bugs but not for new major features. If you want to...

Patterns

Here are a few examples of useful patterns that are often implemented with Bull:

Custom backoff strategy

When the builtin backoff strategies on retries are not sufficient, a custom strategy can be defined. Custom backoff strategies are defined by a functi...

Debugging

To see debug statements set or add to the environment variable:

Manually fetching jobs

If you want to manually fetch the jobs from the queue instead of letting the automatic processor taking care of it, this pattern is for you.

Message queue

Bull can also be used for persistent message queues. This is a quite useful feature in some use cases. For example, you can have two servers that need...

Persistent connections

A crucial feature for a subsystem in a microservice architecture is that it should automatically handle disconnections from other services and keep th...

Redis cluster

Bull internals require atomic operations that span different keys. This behavior breaks Redis's rules for cluster configurations. However, it is still...

Returning Job Completions

A common pattern is where you have a cluster of queue processors that just process jobs as fast as they can, and some other services that need to take...

Reusing Redis Connections

A standard queue requires 3 connections to the Redis server. In some situations you might want to re-use connections—for example on Heroku where the c...

Quick Guide

const Queue = require("bull");

Batches

It is possible to configure workers so that instead of processing one job at a time they can process up to a number of jobs (a so-called *batch*) in o...

Changelogs

[1.4.1](https://github.com/taskforcesh/bullmq-pro/compare/v1.4.0...v1.4.1) (2022-04-19)

[2.7.1](https://github.com/taskforcesh/bullmq-pro/compare/v2.7.0...v2.7.1) (2022-10-13)

Bug Fixes

Fixes

[4.0.3](https://github.com/taskforcesh/bullmq-pro/compare/v4.0.2...v4.0.3) (2022-11-19)

[5.3.5](https://github.com/taskforcesh/bullmq-pro/compare/v5.3.4...v5.3.5) (2023-06-16)

[6.11.0](https://github.com/taskforcesh/bullmq-pro/compare/v6.10.0...v6.11.0) (2024-02-26)

ref faster priority jobs

Groups

Groups allows you to use a single queue while distributing the jobs among groups so that the jobs are processed one by one relative to the group they ...

Concurrency

By default, there is no limit on the number of jobs that workers can run in parallel for every group. Even using a rate limit, that would only limit t...

Getters

It is often necessary to know how many jobs are in any group:

Local group concurrency

It is also possible to set a specific concurrency value to a given group. This is useful if you require that different groups should run with differen...

Local group rate limit

Sometimes it is required that different groups have different rate limits, this could be the case for example if a group represents a given user in th...

Max group size

It is possible to set a maximum group size. This can be useful if you want to keep the number of jobs within some limits and you can afford to discard...

Pausing groups

BullMQ Pro supports pausing groups globally. A group is paused when no workers will pick up any jobs that belongs to the paused group. When you pause ...

Prioritized intra-groups

BullMQ Pro supports priorities per group. A job is prioritized in a group when group and priority options are provided *together*.

Rate limiting

A useful feature when using groups is to be able to rate limit the groups independently of each other, so you can evenly process the jobs belonging to...

Sandboxes for groups

It is also possible to use Sandboxes for processing groups. It works essentially the same as in standard BullMQ, but you gain access to the "gid" prop...

Install

In order to install BullMQ Pro you need to use a NPM token from taskforce.sh.

Introduction

BullMQ Pro, the commercial version of BullMQ, boasts advanced features and offers dedicated support from the library's authors. You can easily install...

NestJs

There is a compatible module to be used in NestJs based on @nestjs/bullmq.

Changelog

Producers

Job producers add jobs to queues. Producers are typically application services (Nest providers). To add jobs to a queue, first inject the queue into t...

Queue Events Listeners

To register a instance, you need to use decorator:

New Releases

If you want to get notifications when we do a new release of BullMQ Pro, please enable notifications on this Github issue where we automatically creat...

Observables

Instead of returning regular promises, your workers can also return an , this allows for some more advanced uses cases:

Cancelation

As mentioned, allow for clean cancellation. Currently we support a TTL value that defines the maximum processing time before the job is finally cance...

Support

With your BullMQ Pro subscription, you receive commercial support. For the most recent and detailed terms, please refer to the "BullMQ Pro" tab in you...

Telemetry

In the same fashion we support telemetry in BullMQ open source edition, we also support telemetry for BullMQ Pro. It works basically the same, in fact...

Changelogs

[1.91.1](https://github.com/taskforcesh/bullmq/compare/v1.91.0...v1.91.1) (2022-09-18)

[2.4.0](https://github.com/taskforcesh/bullmq/compare/v2.3.2...v2.4.0) (2022-10-24)

[3.15.8](https://github.com/taskforcesh/bullmq/compare/v3.15.7...v3.15.8) (2023-06-16)

[4.18.3](https://github.com/taskforcesh/bullmq/compare/v4.18.2...v4.18.3) (2025-07-19)

ref faster priority jobs

Changelogs

Introduction

Architecture

In order to use the full potential of Bull queues, it is important to understand the lifecycle of a job. From the moment a producer calls the method ...

Connections

In order to start working with a Queue, a connection to a Redis instance is necessary. BullMQ uses the node module ioredis, and the options you pass t...

Events

All classes in BullMQ emit useful events that inform on the lifecycles of the jobs that are running in the queue. Every class is an and emits differe...

Create Custom Events

In BullMQ, creating a generic distributed realtime event emitter is possible by using our QueueEventsProducer class.

Flows

BullMQ supports parent - child relationships between jobs. The basic idea is that a parent job will not be moved to the wait status (i.e. where it cou...

Adding flows in bulk

Sometimes it is necessary to atomically add flows in bulk. For example, there could be a requirement that all the flows must be created or none of the...

Continue Parent

{% hint style="info" %}

Fail Parent

In certain workflows, you may need a parent job to fail immediately if any of its child jobs fail. The option allows you to achieve this behaviour. W...

Get Flow Tree

In some situations, you need to get a job and all of its children, grandchildren, and so on.

Ignore Dependency

In some situations, you may have a parent job and need to ignore when one of its children fail.

Remove Child Dependency

In some situations, you may have a parent job and need to remove the dependency of one of its children.

Remove Dependency

In some situations, you may have a parent job and need to remove the relationship when one of its children fail.

Going to production

In this chapter, we will offer crucial considerations and tips to help you achieve a robust solution when deploying your BullMQ-based application to p...

Introduction

BullMQ is based in 4 classes that together can be used to resolve many different problems. These classes are *Queue*, *Worker*, *QueueEvents* and *Flo...

Job Schedulers

A Job Scheduler acts as a factory , producing jobs based on specified "repeat" settings. The Job Scheduler is highly flexible, accommodating various s...

Manage Job Schedulers

In BullMQ, managing the lifecycle and inventory of job schedulers is crucial for maintaining efficient and organized background tasks. In addition to ...

Repeat options

There are some options that can be used on all Job Schedulers, to control some aspects of the repetitions. Lets review them one by one:

Repeat Strategies

BullMQ comes with two predefined strategies for creating repeatable jobs. The ‘every’ strategy is straightforward, allowing you to schedule jobs to re...

Jobs

Queues can hold different types of jobs, which determine how and when they are processed. In this section, we will describe them in detail.

Deduplication

Deduplication in BullMQ is a process where job execution is delayed and deduplicated based on specific identifiers. It ensures that within a specified...

Delayed

Delayed jobs are a special type of job that is placed into a special "delayed set", instead of being processed as fast as possible. After the delay ti...

FIFO

The first type of job we are going to describe is the FIFO (*First-In, First-Out*) type. This is the standard type when adding jobs to a queue. The jo...

Getters

When jobs are added to a queue, they will be in different statuses during their lifetime. BullMQ provides methods to retrieve information and jobs fro...

Job Data

Every job can have its own custom data. The data is stored in the attribute of the job:

Job Ids

All jobs in BullMQ need to have a unique job id. This id is used to construct a key to store the data in Redis, and as a pointer to the job as it is m...

LIFO

In some cases, it is useful to process jobs in a LIFO (*Last-in, First-Out*) fashion. This means that the newest jobs added to the queue will be proce...

Prioritized

Jobs can also include a option. Using priorities, job processing order will be affected by the specified instead of following a FIFO or LIFO pattern...

Removing jobs

Sometimes it is necessary to remove a job. For example, there could be a job that has bad data.

Repeatable

{% hint style="danger" %}

Retrying jobs

BullMQ provides a method that allows you to programmatically retry jobs that have already completed or failed. This is different from the automatic r...

Stalled

{% hint style="danger" %}

Metrics

BullMQ provides a simple metrics gathering functionality that allows you to track the performance of your queues. Workers can count the number of jobs...

Prometheus

BullMQ provides a simple API to export metrics to Prometheus. To use it, create an endpoint in your web server that calls , and configure Prometheus t...

Migrations

BullMQ's team regularly releases new versions packed with bug fixes, new features, or occasionally, breaking changes. As a user operating in a product...

Bull to BullMQ

Bull and BullMQ have diverged too much now to actually give any guarantee of backwards compatibility.

NestJs

There is a compatible module to be used in NestJs.

Producers

Job producers add jobs to queues. Producers are typically application services (Nest providers). To add jobs to a queue, first inject the queue into t...

Queue Events Listeners

To register a QueueEvents instance, you need to use the decorator:

Parallelism and Concurrency

In this chapter we would like to clean up some misconceptions regarding parallel execution and concurrency, how these two terms are applied to BullMQ ...

Queues

A Queue is nothing more than a list of jobs waiting to be processed. The jobs can be small, message like, so that the queue can be used as a message b...

Adding jobs in bulk

Sometimes it is necessary to add many jobs atomically. For example, there could be a requirement that all the jobs must be placed in the queue or none...

Auto-removal of jobs

By default, when your queue jobs are completed (or failed), they are stored in two special sets, the "completed" and the "failed" set. This is useful ...

Global Concurrency

The global concurrency factor is a queue option that determines how many jobs are allowed to be processed in parallel across all your worker instances...

Global Rate Limit

The global rate limit config is a queue option that determines how many jobs are allowed to be processed in a specific period of time.

Removing Jobs

Currently we have 3 available methods in queue class:

QueueScheduler

{% hint style="danger" %}

Rate limiting

BullMQ provides queue rate limiting. It is possible to configure workers so that they obey a given rate limiting option:

Redis™ Compatibility

There are several alternatives for Redis and even though BullMQ is full Redis™ compliant with version 6.2.0 or newer, not all the alternatives are goi...

Dragonfly

To fully leverage Dragonfly's capabilities, specific steps are necessary. Primarily, you should name your queues using curly braces. This naming conve...

Redis™ hosting

AWS Elasticache

Elasticache is a managed caching service offered by Amazon Web Services (AWS), and it can be a good option when using BullMQ within the AWS infrastruc...

AWS MemoryDB

AWS provides a Redis™ 7 compatible managed database that is easy to use and is fully compatible with BullMQ.

Retrying failing jobs

As your queues process jobs, it is inevitable that over time some of these jobs will fail. In BullMQ, a job is considered failed in the following scen...

Returning job data

When a worker is done processing, sometimes it is convenient to return some data. This data can then be accessed for example by listening to the even...

Telemetry

BullMQ provides a Telemetry interface that can be used to integrate it with any external telemetry backends. Currently we support the OpenTelemetry sp...

Getting started

In this guide we will show how to setup a local telemetry facility for BullMQ that should serve you as a good basis for how to integrate it in larger ...

Metrics

In addition to traces, BullMQ also supports collecting metrics through OpenTelemetry. Metrics provide quantitative data about your job processing, suc...

Running a simple example

For this simple example we will create a producer that will add a couple of jobs, but it will add them in bulks instead of one by one, this will help ...

Running Jaeger

The easiest way to run Jaeger is by using Docker compose. If you have docker installed, it is a matter of running this docker-compose.yaml file:

Troubleshooting

In this section, you will be able to find hints and solutions for some common errors you might encounter when using BullMQ.

Workers

Workers are the actual instances that perform some job based on the jobs that are added in the queue. A worker is equivalent to a "message" receiver i...

Auto-removal of jobs

By default, when your queue jobs are completed (or failed), they are stored in two special sets, the "completed" and the "failed" set. This is useful ...

Cancelling jobs

The job cancellation feature allows you to gracefully cancel jobs that are currently being processed by a worker. This is implemented using the standa...

Concurrency

There are basically two ways to achieve concurrency with BullMQ using Worker instances. You can run a worker with a concurrency factor larger than 1 (...

Graceful shutdown

BullMQ supports graceful shutdowns of workers. This is important so that we can minimize stalled jobs when a worker for some reason must be shutdown. ...

Pausing queues

BullMQ supports pausing queues *globally* or *locally*. When a queue is paused *globally* no workers will pick up any jobs from the queue. When you pa...

Sandboxed processors

It is also possible to define workers to run on a separate process. We call these processors *sandboxed*, because they run isolated from the rest of t...

Stalled Jobs

Due to the nature of NodeJS, which is (in general) single threaded and consists of an event loop to handle the asynchronous operations, the process fu...

Adding jobs in bulk across different queues

Sometimes it is necessary to atomically add jobs to different queues in bulk. For example, there could be a requirement that all the jobs must be crea...

Deduplication

Sometimes, you may want to decide when you want to stop deduplicating jobs.

Failing fast when Redis is down

By design, BullMQ reconnects to Redis automatically. If jobs are added to a queue while the queue instance is disconnected from Redis, the command wi...

Flows

{% hint style="warning" %}

Idempotent jobs

In order to take advantage of the ability to retry failed jobs, your jobs should be designed with failure in mind.

Manual retrying

There are situations when it is useful to retry a job right away when it is being processed.

Manually processing jobs

When a Worker is instantiated, the most common usage is to specify a process function so that the worker will automatically process the jobs that arri...

Named Processor

When a Worker is instantiated, the most common usage is to specify a process function.

Process Step Jobs

Sometimes, it is useful to break processor functions into small pieces that will be processed depending on the previous executed step. One way to hand...

Redis Cluster

Bull internals require atomic operations that span different keys. This behavior breaks Redis's rules for cluster configurations. However, it is still...

Stop retrying jobs

When a processor throws an exception that is considered unrecoverable, you should use the class. In this case, BullMQ will just move the job to the f...

Throttle jobs

Sometimes, you may want to enqueue a job in reaction to a frequently occurring event, without running that job for *every* event. For example, you may...

Timeout for Sandboxed processors

When you are working with sandboxed processors, every job is run in a separate process. This opens the possibility to implement a time-to-live (TTL) m...

Timeout jobs

BullMQ does not provide a specific mechanism to timeout jobs, however this can be accomplished in many cases with a custom timeout code in the worker'...

Changelogs

Introduction

The PHP package provides a Queue client that allows you to add jobs to BullMQ queues from your PHP applications. These jobs can then be processed by w...

Changelogs

[0.5.6](https://github.com/taskforcesh/bullmq/compare/vpy0.5.5...vpy0.5.6) (2023-06-21)

[1.24.0](https://github.com/taskforcesh/bullmq/compare/vpy1.23.0...vpy1.24.0) (2023-12-21)

ref faster priority jobs

Introduction

BullMQ is delivered as a pip package and can thus be installed using pip:

Quick Start

{% hint style="info" %}

Codex

Codex is OpenAI’s coding agent for software development. ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. It can help you:

Codex Ambassadors

Codex is rapidly becoming one of the most powerful ways to build, driven by builders who share real-world workflows and lessons with each other.

Codex App Server

Codex app-server is the interface Codex uses to power rich clients (for example, the Codex VS Code extension). Use it when you want a deep integration...

Codex app

The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functiona...

Automations

Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can...

Codex app commands

Use these commands and keyboard shortcuts to navigate the Codex app.

Codex app features

The Codex app is a focused desktop experience for working on Codex threads in parallel,

Local environments

Local environments let you configure setup steps for worktrees as well as common actions for a project.

Review

The review pane helps you understand what Codex changed, give targeted feedback, and decide what to keep.

Codex app settings

Use the settings panel to tune how the Codex app behaves, how it opens files,

Troubleshooting

If your project is inside a Git repository, the review panel automatically

Worktrees

In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, au...

Authentication

Codex supports two ways to sign in when using OpenAI models:

Codex changelog

$ npm install -g @openai/codex@0.104.0

Codex CLI

Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected dire...

Codex CLI features

Codex supports workflows beyond chat. Use this guide to learn what each one unlocks and when to use it.

Command line options

export const globalFlagOptions = [

Slash commands in Codex CLI

Slash commands give you fast, keyboard-first control over Codex. Type in the composer to open the slash popup, choose a command, and Codex will perfo...

Codex web

Codex is OpenAI's coding agent that can read, edit, and run code. It helps you build faster, fix bugs, and understand unfamiliar code. With Codex clou...

Cloud environments

Use environments to control what Codex installs and runs during cloud tasks. For example, you can add dependencies, install tools like linters and for...

Agent internet access

By default, Codex blocks internet access during the agent phase. Setup scripts still run with internet access so you can install dependencies. You can...

Community

Codex Meetups

LocationAll locations

Concepts

Customization

Customization is how you make Codex work the way your team works.

Cyber Safety

In addition to safety training, automated classifier-based monitors detect signals of suspicious cyber activity and route high-risk traffic to a less ...

Multi-agents

Codex can run multi-agent workflows by spawning specialized agents in parallel and collecting their results in one response.

Advanced Configuration

Use these options when you need more control over providers, policies, and integrations. For a quick start, see Config basics.

Config basics

Codex reads configuration details from more than one location. Your personal defaults live in , and you can add project overrides with files. For sec...

Configuration Reference

Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Con...

Sample Configuration

Use this example configuration as a starting point. It includes most keys Codex reads from , along with defaults and short notes.

Custom Prompts

Custom prompts are deprecated. Use skills for reusable

Enterprise

Admin Setup

This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.

Governance

Codex gives enterprise teams visibility into adoption and impact, plus the auditability needed for security and compliance programs. Use the self-serv...

Explore

Automate recurring tasks. Codex adds findings to the inbox and archives runs with nothing to report.

Feature Maturity

Some Codex features ship behind a maturity label so you can understand how reliable each one is, what might change, and what level of support to expec...

Codex GitHub Action

Use the Codex GitHub Action () to run Codex in CI/CD jobs, apply patches, or post reviews from a GitHub Actions workflow.

Guides

Custom instructions with AGENTS.md

Codex reads files before doing any work. By layering global guidance with project-specific overrides, you can start each task with consistent expecta...

Use Codex with the Agents SDK

You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the OpenAI Agents SDK).

Building an AI-Native Engineering Team

AI models are rapidly expanding the range of tasks they can perform, with significant implications for engineering. Frontier systems now sustain multi...

Codex IDE extension

Codex is OpenAI's coding agent that can read, edit, and run code. It helps you build faster, squash bugs, and understand unfamiliar code. With the Cod...

Codex IDE extension commands

Use these commands to control Codex from the VS Code Command Palette. You can also bind them to keyboard shortcuts.

Codex IDE extension features

The Codex IDE extension gives you access to Codex directly in VS Code, Cursor, Windsurf, and other VS Code-compatible editors. It uses the same agent ...

Codex IDE extension settings

Use these settings to customize the Codex IDE extension.

Codex IDE extension slash commands

Slash commands let you control Codex without leaving the chat input. Use them to check status, switch between local and cloud mode, or send feedback.

Integrations

Use Codex in GitHub

Use Codex to review pull requests without leaving GitHub. Add a pull request comment with , and Codex replies with a standard GitHub code review.

Use Codex in Linear

Use Codex in Linear to delegate work from issues. Assign an issue to Codex or mention in a comment, and Codex creates a cloud task and replies with p...

Use Codex in Slack

Use Codex in Slack to kick off coding tasks from channels and threads. Mention with a prompt, and Codex creates a cloud task and replies with the res...

Model Context Protocol

Model Context Protocol (MCP) connects models to tools and context. Use it to give Codex access to third-party documentation, or to let it interact wit...

Codex Models

Most capable agentic coding model to date, combining frontier coding performance with stronger reasoning and professional knowledge capabilities.

Multi-agents

Codex can run multi-agent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particul...

Non-interactive mode

Non-interactive mode lets you run Codex from scripts (for example, continuous integration (CI) jobs) without opening the interactive TUI.

Open Source

OpenAI develops key parts of Codex in the open. That work lives on GitHub so you can follow progress, report issues, and contribute improvements.

Codex

!Codex app showing a project sidebar, thread list, and review pane

Codex Pricing

For a limited time, try Codex for free in ChatGPT Free and Go, or enjoy

Prompting

You interact with Codex by sending prompts (user messages) that describe what you want it to do.

Quickstart

ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Using Codex with your ChatGPT subscription gives you access to the latest Codex ...

Rules

Use rules to control which commands Codex can run outside the sandbox.

Codex SDK

If you use Codex through the Codex CLI, the IDE extension, or Codex Web, you can also control it programmatically.

Security

Codex helps protect your code and data and reduces the risk of misuse.

Agent Skills

Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a...

Videos

Windows

The easiest way to use Codex on Windows is to set up the IDE extension or install the CLI and run it from PowerShell.

Workflows

Codex works best when you treat it like a teammate with explicit context and a clear definition of "done."

NextAuth.js

_(Google, Facebook, Auth0, Apple…)_

Adapters

Visit the authjs.dev page for the up-to-date documentation.

Callbacks

Callbacks are asynchronous functions you can use to control what happens when an action is performed.

Databases

NextAuth.js offers multiple database adapters. Check out the overview.

Events

Events are asynchronous functions that do not return a response, they are useful for audit logs / reporting or handling any other side-effects.

Initialization

The main entry point of NextAuth.js is the method that you import from . It handles different types of requests, as defined in the REST API section.

Next.js

You can create a helper function so you don't need to pass around:

Options

When deploying to production, set the environment variable to the canonical URL of your site.

Pages

NextAuth.js automatically creates simple, unbranded authentication pages for handling Sign in, Sign out, Email Verification and displaying error messa...

Credentials

The Credentials provider allows you to handle signing in with arbitrary credentials, such as a username and password, two-factor authentication or har...

Email

The Email provider sends "magic links" via email that the user can click on to sign in. You have likely seen them before if you have used software lik...

OAuth

Authentication Providers in NextAuth.js are OAuth definitions that allow your users to sign in with their favorite preexisting logins. You can use any...

Contributors

Maintaining Auth.js as an open source project is very hard work. All the core team members have regular jobs and the library is maintained and develop...

Deployment

Deploying NextAuth.js only requires a few steps. It can be run anywhere a Next.js application can. Therefore, in a default configuration using only JW...

Errors

This is a list of errors output from NextAuth.js.

Frequently Asked Questions

NextAuth.js is an open source project built by individual contributors.

Client API

The NextAuth.js client library makes it easy to interact with sessions from React applications.

Getting Started

The example code below describes how to add authentication to a Next.js app.

Introduction

NextAuth.js is a complete open-source authentication solution for Next.js applications.

REST API

NextAuth.js exposes a REST API that is used by the NextAuth.js client.

TypeScript

NextAuth.js has its own type definitions to use in your TypeScript projects safely. Even if you don't use TypeScript, IDEs like VSCode will pick this ...

Upgrade Guide (v4)

NextAuth.js version 4 includes a few breaking changes from the last major version (3.x). So we're here to help you upgrade your applications as smooth...

Guides

We have internal guides in three levels of difficulty.

Basics

Fullstack

Testing

Overview

Authentication Providers in NextAuth.js are services that can be used to sign in a user.

42 School

42 returns a field on called which is a number. See the docs. Make sure to add this field to your database schema, in case if you are using an Adapt...

Apple

The Apple Provider comes with a set of default options:

Atlassian

The Atlassian Provider comes with a set of default options:

Auth0

The Auth0 Provider comes with a set of default options:

Authentik

The Authentik Provider comes with a set of default options:

Azure Active Directory B2C

Azure AD B2C returns the following fields on :

Azure Active Directory

Azure Active Directory returns the following fields on :

Battle.net

The Battle.net Provider comes with a set of default options:

Documentation[](https://next-auth.js.org/providers/box#documentation "Direct link to heading")

The Box Provider comes with a set of default options:

BoxyHQ SAML

BoxyHQ SAML is an open source service that handles the SAML login flow as an OAuth 2.0 flow, abstracting away all the complexities of the SAML protoco...

Bungie

The Bungie Provider comes with a set of default options:

Amazon Cognito

You need to select your AWS region to go the the Cognito dashboard.

Coinbase

The Coinbase Provider comes with a set of default options:

Credentials

The Credentials provider allows you to handle signing in with arbitrary credentials, such as a username and password, domain, or two factor authentica...

Discord

The Discord Provider comes with a set of default options:

Dropbox

The Dropbox Provider comes with a set of default options:

DuendeIdentityServer6

The DuendeIdentityServer6 Provider comes with a set of default options:

Email

The Email provider uses email to send "magic links" that can be used to sign in, you will likely have seen these if you have used services like Slack ...

EVE Online

The EVE Online Provider comes with a set of default options:

Facebook

The Facebook Provider comes with a set of default options:

FACEIT

Scopes to have basic infos (email, nickname, guid and avatar) : , ,

Foursquare

Foursquare requires an additional parameter in format, which essentially states "I'm prepared for API changes up to this date".

Freshbooks

The Freshbooks Provider comes with a set of default options:

FusionAuth

The FusionAuth Provider comes with a set of default options:

GitHub

GitHub returns a field on called which is a number. See their docs. Remember to add this field to your database schema, in case if you are using an ...

GitLab

GitLab returns a field on called which is a number. See their docs. Remember to add this field as optional to your database schema, in case if you a...

Google

The "Authorized redirect URIs" used when creating the credentials must include your full domain and end in the callback path. For example;

HubSpot

HubSpot returns a limited amount of information on the token holder (see docs). One other issue is that the name and profile photo cannot be fetched t...

IdentityServer4

The IdentityServer4 Provider comes with a set of default options:

Instagram

The Instagram Provider comes with a set of default options:

Kakao

The Kakao Provider comes with a set of default options:

Keycloak

Create an openid-connect client in Keycloak with "confidential" as the "Access Type".

LINE

The Line Provider comes with a set of default options:

From the Auth tab get the client ID and client secret. On the same tab, add redirect URLs such as http://localhost:3000/api/auth/callback/linkedin so ...

Mailchimp

The Mailchimp Provider comes with a set of default options:

Mail.ru

The Mail.ru Provider comes with a set of default options:

Medium

The Medium Provider comes with a set of default options:

Naver

The Naver Provider comes with a set of default options:

Netlify

The Netlify Provider comes with a set of default options:

Okta

The Okta Provider comes with a set of default options:

OneLogin

The OneLogin Provider comes with a set of default options:

Osso

Osso is an open source service that handles SAML authentication against Identity Providers, normalizes profiles, and makes those profiles available to...

osu!

The osu! Provider comes with a set of default options:

Patreon

Create a API v2 client on Patreon Platform

The Pinterest Provider comes with a set of default options:

Pipedrive

The Pipedrive Provider comes with a set of default options:

!next-auth-reddit-provider-config

Salesforce

The Salesforce Provider comes with a set of default options:

Slack

Slack requires that the redirect URL of your app uses , even for local development. An easy workaround for this is using a service like that creates ...

Spotify

The Spotify Provider comes with a set of default options:

Strava

The Strava Provider comes with a set of default options:

Todoist

The Todoist Provider comes with a set of default options:

Trakt

If you're using the api in production by calling api.trakt.tv. Follow the example below. If you wish to develop on Trakt's sandbox environment by call...

Twitch

Add the following redirect URL into the console

Twitter

Twitter is currently the only built-in provider using the OAuth 1.0 spec. This means that you won't receive an or , but an and respectively. Rememb...

United Effects

The United Effects Provider comes with a set of default options:

Documentation[](https://next-auth.js.org/providers/vk#documentation "Direct link to heading")

The VK Provider comes with a set of default options:

Wikimedia

This provider also supports all Wikimedia projects:

WordPress.com

The Wordpress Provider comes with a set of default options:

WorkOS

The WorkOS Provider comes with a set of default options:

Yandex

The Yandex Provider comes with a set of default options:

Zitadel

The Redirect URIs used when creating the credentials must include your full domain and end in the callback path. For example:

Zoho

Zoho returns a field on called which is a string. See their docs. Remember to add this field to your database schema, in case if you are using an Ad...

Zoom

The Zoom Provider comes with a set of default options:

Search the documentation

🎉 NextAuth.js is now part of Better Auth!

Security

NextAuth.js practices responsible disclosure.

NextAuth.js

Tutorials and Explainers

> These tutorials are contributed by the community. Unless otherwise indicated, tutorials are hosted on this site. External and video based tutorials ...

Allow Email Signups Behind Corporate Link Checker

If you use Office 365 or Outlook, or potentially other Email systems, you may notice your Email invitation Links not working.

corporate-proxy

\-- id: corporate-proxy

Create an adapter

Using a custom adapter you can connect to any database back-end or even several different databases. Official adapters created and maintained by our c...

LDAP Authentication

NextAuth.js provides the ability to setup a custom Credential provider which we can take advantage of to authenticate users against an existing LDAP s...

Securing pages and API routes

You can easily protect client and server side rendered pages and API routes with NextAuth.js.

Testing with Cypress

To test an implementation of NextAuth.js, we encourage you to use Cypress.

Usage with class components

If you want to use the hook in your class components you can do so with the help of a higher order component or with a render prop.

DynamoDB

This is the AWS DynamoDB Adapter for next-auth. This package can only be used in conjunction with the primary next-auth package. It is not a standalon...

FaunaDB

This is the Fauna Adapter for . This package can only be used in conjunction with the primary package. It is not a standalone package.

Firebase

This is the Firebase Adapter for . This package can only be used in conjunction with the primary package. It is not a standalone package.

Models

Models in NextAuth.js are built for ANSI SQL but are polymorphic and are transformed to adapt to the database being used; there is some variance in sp...

Overview

An Adapter in NextAuth.js connects your application to whatever database or backend system you want to use to store data for user accounts, sessions, ...

PouchDB

This is the PouchDB Adapter for . This package can only be used in conjunction with the primary package. It is not a standalone package.

Prisma (Legacy)

You can also use NextAuth.js with the built-in Adapter for Prisma. This is included in the core package at the moment. The other adapter needs to be ...

Prisma

You can also use NextAuth.js with the new experimental Adapter for Prisma. This version of the Prisma Adapter is not included in the core package, an...

MongoDB

MongoDB is a document database and does not use schemas in the same way as most RDBMS databases.

Microsoft SQL Server

Schema for a Microsoft SQL Server (mssql) database.

MySQL

Schema for a MySQL database.

Postgres

Schema for a Postgres database.

Overview

NextAuth.js comes with a default Adapter that uses TypeORM so that it can be used with many different databases without any further configuration, you...

Callbacks

Callbacks are asynchronous functions you can use to control what happens when an action is performed.

Databases

NextAuth.js comes with multiple ways of connecting to a database:

Events

Events are asynchronous functions that do not return a response, they are useful for audit logs / reporting.

Options

When deploying to production, set the environment variable to the canonical URL of your site.

Pages

NextAuth.js automatically creates simple, unbranded authentication pages for handling Sign in, Sign out, Email Verification and displaying error messa...

Providers

Authentication Providers in NextAuth.js are services that can be used to sign in a user.

Contributors

Since Sep 26, NextAuth is now bing maintained under Better Auth. Read announcement here.

Errors

This is a list of errors output from NextAuth.js.

Frequently Asked Questions

NextAuth.js is an open source project built by individual contributors.

Client API

The NextAuth.js client library makes it easy to interact with sessions from React applications.

Example Code

The example code below describes how to add authentication to a Next.js app.

Introduction

NextAuth.js is a complete open source authentication solution for Next.js applications.

REST API

NextAuth.js exposes a REST API which is used by the NextAuth.js client.

TypeScript

NextAuth.js comes with its own type definitions, so you can safely use it in your TypeScript projects. Even if you don't use TypeScript, IDEs like VSC...

42 School

The 42 School Provider comes with a set of default options:

Apple

The Apple Provider comes with a set of default options:

Atlassian

The Atlassian Provider comes with a set of default options:

Auth0

Configure your application in Auth0 as a 'Regular Web Application' (not a 'Single Page App').

Azure Active Directory B2C

The Azure Active Directory Provider comes with a set of default options:

Basecamp

The Basecamp Provider comes with a set of default options:

Battle.net

The Battle.net Provider comes with a set of default options:

Documentation[](https://next-auth.js.org/v3/providers/box#documentation "Direct link to heading")

The Box Provider comes with a set of default options:

Bungie

The Bungie Provider comes with a set of default options:

Amazon Cognito

You need to select your AWS region to go the the Cognito dashboard.

Coinbase

The Coinbase Provider comes with a set of default options:

Credentials

The Credentials provider allows you to handle signing in with arbitrary credentials, such as a username and password, domain, or two factor authentica...

Discord

The Discord Provider comes with a set of default options:

Dropbox

The Dropbox Provider comes with a set of default options:

DuendeIdentityServer6

The DuendeIdentityServer6 Provider comes with a set of default options:

Email

The Email provider uses email to send "magic links" that can be used to sign in, you will likely have seen these if you have used services like Slack ...

EVE Online

The EVE Online Provider comes with a set of default options:

Facebook

The Facebook Provider comes with a set of default options:

FACEIT

Scopes to have basic infos (email, nickname, guid and avatar) : , ,

Foursquare

Foursquare requires an additional parameter in format, which essentially states "I'm prepared for API changes up to this date".

FusionAuth

The FusionAuth Provider comes with a set of default options:

GitHub

The Github Provider comes with a set of default options:

GitLab

The Gitlab Provider comes with a set of default options:

Google

The Google Provider comes with a set of default options:

IdentityServer4

The IdentityServer4 Provider comes with a set of default options:

Instagram

The Instagram Provider comes with a set of default options:

Kakao

The Kakao Provider comes with a set of default options:

LINE

The Line Provider comes with a set of default options:

From the Auth tab get the client ID and client secret. On the same tab, add redirect URLs such as http://localhost:3000/api/auth/callback/linkedin so ...

Mailchimp

The Mailchimp Provider comes with a set of default options:

Mail.ru

The Mail.ru Provider comes with a set of default options:

Medium

The Medium Provider comes with a set of default options:

Naver

The Naver Provider comes with a set of default options:

Netlify

The Netlify Provider comes with a set of default options:

Okta

The Okta Provider comes with a set of default options:

Osso

Osso is an open source service that handles SAML authentication against Identity Providers, normalizes profiles, and makes those profiles available to...

The Reddit Provider comes with a set of default options:

Salesforce

The Salesforce Provider comes with a set of default options:

Slack

The Slack Provider comes with a set of default options:

Spotify

The Spotify Provider comes with a set of default options:

Strava

The Strava Provider comes with a set of default options:

Twitch

Add the following redirect URL into the console

Twitter

The Twitter Provider comes with a set of default options:

Documentation[](https://next-auth.js.org/v3/providers/vk#documentation "Direct link to heading")

The VK Provider comes with a set of default options:

WordPress.com

The Wordpress Provider comes with a set of default options:

WorkOS

The WorkOS Provider comes with a set of default options:

Yandex

The Yandex Provider comes with a set of default options:

Zoho

The Zoho Provider comes with a set of default options:

Zoom

The Zoom Provider comes with a set of default options:

Tutorials and Explainers

_These tutorials are contributed by the community and hosted on this site._

Creating a database adapter

Using a custom adapter you can connect to any database backend or even several different databases. Custom adapters created and maintained by our comm...

LDAP Authentication

NextAuth.js provides the ability to setup a custom Credential provider which we can take advantage of to authenticate users against an existing LDAP s...

Refresh Token Rotation

While NextAuth.js doesn't automatically handle access token rotation for OAuth providers yet, this functionality can be implemented using callbacks.

Securing pages and API routes

You can easily protect client and server side rendered pages and API routes with NextAuth.js.

Testing with Cypress

To test an implementation of NextAuth.js, we encourage you to use Cypress.

Custom models with TypeORM

NextAuth.js provides a set of models and schemas for the built-in TypeORM adapter that you can easily extend.

Usage with class components

If you want to use the hook in your class components you can do so with the help of a higher order component or with a render prop.

Warnings

This is a list of warning output from NextAuth.js.

Warnings

This is a list of warning output from NextAuth.js.

Next.js internationalization (i18n)

is an internationalization toolkit for Next.js that helps you:

Design principles

This page provides a deep dive about the design principles that is based on.

Environments

The APIs are available in the following environments:

Server Actions, Metadata & Route Handlers

There are a few places in Next.js apps where you can apply internationalization outside of React components:

Core library

While is primarily intended to be used in Next.js apps, the core is agnostic and can be used independently—either in React apps or any other JavaScri...

Internationalization in Next.js error files

The Next.js App Router’s file convention provides two files that can be used for error handling:

Runtime requirements

The source code of is compiled for the same browsers that Next.js supports.

Internationalization of Server & Client Components

This applies to handling internationalization too.

Testing

Components that use can be used in unit tests:

Next.js internationalization (i18n)

is an internationalization toolkit for Next.js that helps you:

Next.js App Router internationalization (i18n)

DocsGetting startedApp Router

Next.js Pages Router internationalization (i18n)

DocsGetting startedPages Router

Routing

integrates with Next.js’ routing system in two places:

Routing configuration

The routing configuration that is shared between the middleware and the navigation APIs can be defined with the function.

Proxy / middleware

The middleware can be created via .

Navigation APIs

Prefer to watch a video?

Setup locale-based routing

Prefer to watch a video?

Usage guide

This guide explains how can be used in React components.

Request configuration

Configuration properties that you use across your Next.js app can be set per request.

Date and time formatting

Prefer to watch a video?

useExtracted (experimental)

As an alternative to managing namespaces and keys manually, provides an additional API that works similar to but automatically extracts messages fro...

List formatting

When working with lists of items, you can format them as conjunctions or disjunctions.

Number formatting

Prefer to watch a video?

Next.js plugin (createNextIntlPlugin)

When setting up for the App Router, you’ll add to your Next.js config.

Rendering translations

Prefer to watch a video?

Workflows & integrations

To get the most out of , you can choose from these integrations to improve your workflow.

Localization management with Crowdin

Prefer to use a fully AI-driven workflow?

Validating messages

To ensure quality and completeness of your messages, you can use i18n-check.

Storybook integration for next-intl

To set up Storybook for , you can configure a global decorator that renders to wrap your stories accordingly:

TypeScript augmentation

Prefer to watch a video?

VSCode integration

Prefer to watch a video?

Next.js Docs

Welcome to the Next.js documentation!

App Router

The App Router is a file-system based router that uses React's latest features such as Server Components, Suspense, and Server Functions.

API Reference

index

Next.js comes with two Command Line Interface (CLI) tools:

create-next-app

The CLI allow you to create a new Next.js application using the default template or an example from a public GitHub repository. It is the easiest way...

next CLI

The Next.js CLI allows you to develop, build, start your application, and more.

Components

Font Module

It includes built-in automatic self-hosting for any font file. This means you can optimally load web fonts with no layout shift.

Form Component

The component extends the HTML element to provide prefetching of loading UI, client-side navigation on submission, and progressive enhancement.

Image Component

The Next.js Image component extends the HTML element for automatic image optimization.

Link Component

is a React component that extends the HTML element to provide prefetching and client-side navigation between routes. It is the primary way to navigat...

Script Component

This API reference will help you understand how to use props available for the Script Component. For features and usage, please see the Optimizing Scr...

Configuration

ESLint Plugin

Next.js provides an ESLint configuration package, , that makes it easy to catch common issues in your application. It includes the plugin along with ...

next.config.js

Next.js can be configured through a file in the root of your project directory (for example, by ) with a default export.

experimental.adapterPath

Next.js provides an experimental API that allows you to create custom adapters to hook into the build process. This is useful for deployment platforms...

allowedDevOrigins

Next.js does not automatically block cross-origin requests during development, but will block by default in a future major version of Next.js to preve...

appDir

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

assetPrefix

> Attention: Deploying to Vercel automatically configures a global CDN for your Next.js project.

authInterrupts

> This feature is currently available in the canary channel and subject to change.

basePath

To deploy a Next.js application under a sub-path of a domain you can use the config option.

browserDebugInfoInTerminal

> This feature is currently experimental and subject to change, it is not recommended for production.

cacheComponents

The flag is a feature in Next.js that causes data fetching operations in the App Router to be excluded from pre-renders unless they are explicitly ca...

cacheHandlers

The configuration allows you to define custom cache storage implementations for and . This enables you to store cached components and functions in e...

cacheLife

The option allows you to define custom cache profiles when using the function inside components or functions, and within the scope of the directive...

compress

By default, Next.js uses to compress rendered content and static files when using or a custom server. This is an optimization for applications that ...

crossOrigin

Use the option to add a attribute in all tags generated by the component , and define how cross-origin requests should be handled.

cssChunking

> This feature is currently experimental and subject to change, it is not recommended for production.

deploymentId

The option allows you to set an identifier for your deployment. This identifier is used for version skew protection and cache busting during rolling ...

devIndicators

allows you to configure the on-screen indicator that gives context about the current route you're viewing during development.

distDir

You can specify a name to use for a custom build directory to use instead of .

index

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

expireTime

You can specify a custom expire time for CDNs to consume in the header for ISR enabled pages.

exportPathMap

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

generateBuildId

Next.js generates an ID during to identify which version of your application is being served. The same build should be used and boot up multiple cont...

generateEtags

Next.js will generate etags for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.

headers

Headers allow you to set custom HTTP headers on the response to an incoming request on a given path.

htmlLimitedBots

The config allows you to specify a list of user agents that should receive blocking metadata instead of streaming metadata.

httpAgentOptions

In Node.js versions prior to 18, Next.js automatically polyfills with undici and enables HTTP Keep-Alive by default.

images

If you want to use a cloud provider to optimize images instead of using the Next.js built-in Image Optimization API, you can configure with the follo...

Custom Next.js Cache Handler

You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple conta...

inlineCss

> This feature is currently experimental and subject to change, it is not recommended for production.

isolatedDevBuild

> This feature is currently experimental and subject to change, it is not recommended for production.

logging

You can configure the logging level and whether the full URL is logged to the console when running Next.js in development mode.

mdxRs

> This feature is currently experimental and subject to change, it is not recommended for production.

onDemandEntries

Next.js exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.

optimizePackageImports

> This feature is currently experimental and subject to change, it is not recommended for production.

output

During a build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a producti...

pageExtensions

By default, Next.js accepts files with the following extensions: , , , . This can be modified to allow other extensions like markdown (, ).

poweredByHeader

By default Next.js will add the header. To opt-out of it, open and disable the config:

productionBrowserSourceMaps

Source Maps are enabled by default during development. During production builds, they are disabled to prevent you leaking your source on the client, u...

proxyClientMaxBodySize

> This feature is currently experimental and subject to change, it is not recommended for production.

reactCompiler

Next.js includes support for the React Compiler, a tool designed to improve performance by automatically optimizing component rendering. This reduces ...

reactMaxHeadersLength

During static rendering, React can emit headers that can be added to the response. These can be used to improve performance by allowing the browser to...

reactStrictMode

> Good to know: Since Next.js 13.5.1, Strict Mode is by default with router, so the above configuration is only necessary for . You can still disabl...

redirects

Redirects allow you to redirect an incoming request path to a different destination path.

rewrites

Rewrites allow you to map an incoming request path to a different destination path.

sassOptions

allow you to configure the Sass compiler.

serverActions

Options for configuring Server Actions behavior in your Next.js application.

serverComponentsHmrCache

> This feature is currently experimental and subject to change, it is not recommended for production.

serverExternalPackages

Dependencies used inside Server Components and Route Handlers will automatically be bundled by Next.js.

staleTimes

> This feature is currently experimental and subject to change, it is not recommended for production.

staticGeneration*

> This feature is currently experimental and subject to change, it is not recommended for production.

taint

> This feature is currently experimental and subject to change, it is not recommended for production.

trailingSlash

By default Next.js will redirect URLs with trailing slashes to their counterpart without a trailing slash. For example will redirect to . You can con...

transpilePackages

Next.js can automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (). This replaces the ...

turbopack

The option lets you customize Turbopack to transform different files and change how modules are resolved.

Turbopack FileSystem Caching

Turbopack FileSystem Cache enables Turbopack to reduce work across or commands. When enabled, Turbopack will save and restore data to the folder be...

typedRoutes

> Note: This option has been marked as stable, so you should use instead of .

typescript

Configure TypeScript behavior with the option in :

urlImports

> This feature is currently experimental and subject to change, it is not recommended for production.

useLightningcss

> This feature is currently experimental and subject to change, it is not recommended for production.

viewTransition

> This feature is currently experimental and subject to change, it is not recommended for production.

Custom Webpack Config

> Good to know: changes to webpack config are not covered by semver so proceed at your own risk

webVitalsAttribution

> This feature is currently experimental and subject to change, it is not recommended for production.

TypeScript

Next.js comes with built-in TypeScript, automatically installing the necessary packages and configuring the proper settings when you create a new proj...

Directives

The following directives are available:

use cache: private

> This feature is currently experimental and subject to change, it is not recommended for production.

use cache: remote

While the directive is sufficient for most application needs, you might notice that cached operations are re-running more often than expected, or tha...

use cache

The directive allows you to mark a route, React component, or a function as cacheable. It can be used at the top of a file to indicate that all expor...

use client

The directive declares an entry point for the components to be rendered on the client side and should be used when creating interactive user interfac...

use server

The directive designates a function or file to be executed on the server side. It can be used at the top of a file to indicate that all functions in ...

Edge Runtime

Next.js has two server runtimes you can use in your application:

File-system conventions

default.js

The file is used to render a fallback within Parallel Routes when Next.js cannot recover a slot's active state after a full-page load.

Dynamic Route Segments

When you don't know the exact route segment names ahead of time and want to create routes from dynamic data, you can use Dynamic Segments that are fil...

error.js

An error file allows you to handle unexpected runtime errors and display fallback UI.

forbidden.js

> This feature is currently experimental and subject to change, it is not recommended for production.

instrumentation-client.js

The file allows you to add monitoring, analytics code, and other side-effects that run before your application becomes interactive. This is useful fo...

instrumentation.js

The file is used to integrate observability tools into your application, allowing you to track the performance and behavior, and to debug issues in p...

Intercepting Routes

Intercepting routes allows you to load a route from another part of your application within the current layout. This routing paradigm can be useful wh...

layout.js

The file is used to define a layout in your Next.js application.

loading.js

The special file helps you create meaningful Loading UI with React Suspense. With this convention, you can show an instant loading state from the ser...

mdx-components.js

The file is required to use with App Router and will not work without it. Additionally, you can use it to customize styles.

Metadata Files API Reference

This section of the docs covers Metadata file conventions. File-based metadata can be defined by adding special metadata files to route segments.

favicon, icon, and apple-icon

The , , or file conventions allow you to set icons for your application.

manifest.json

Add or generate a file that matches the Web Manifest Specification in the root of directory to provide information about your web application for th...

opengraph-image and twitter-image

The and file conventions allow you to set Open Graph and Twitter images for a route segment.

robots.txt

Add or generate a file that matches the Robots Exclusion Standard in the root of directory to tell search engine crawlers which URLs they can access...

sitemap.xml

is a special file that matches the Sitemaps XML format to help search engine crawlers index your site more efficiently.

not-found.js

Next.js provides two conventions to handle not found cases:

page.js

The file allows you to define UI that is unique to a route. You can create a page by default exporting a component from the file:

Parallel Routes

Parallel Routes allows you to simultaneously or conditionally render one or more pages within the same layout. They are useful for highly dynamic sect...

proxy.js

> Note: The file convention is deprecated and has been renamed to . See Migration to Proxy for more details.

public Folder

Next.js can serve static files, like images, under a folder called in the root directory. Files inside can then be referenced by your code starting ...

Route Groups

Route Groups are a folder convention that let you organize routes by category or team.

Route Segment Config

> * The options outlined on this page are disabled if the flag is on, and will eventually be deprecated in the future.

route.js

Route Handlers allow you to create custom request handlers for a given route using the Web Request and Response APIs.

src Folder

As an alternative to having the special Next.js or directories in the root of your project, Next.js also supports the common pattern of placing appl...

template.js

A template file is similar to a layout in that it wraps a layout or page. Unlike layouts that persist across routes and maintain state, templates are ...

unauthorized.js

> This feature is currently experimental and subject to change, it is not recommended for production.

Functions

after

allows you to schedule work to be executed after a response (or prerender) is finished. This is useful for tasks and other side effects that should no...

cacheLife

The function is used to set the cache lifetime of a function or component. It should be used alongside the directive, and within the scope of the fu...

cacheTag

The function allows you to tag cached data for on-demand invalidation. By associating tags with cache entries, you can selectively purge or revalidat...

connection

The function allows you to indicate rendering should wait for an incoming user request before continuing.

cookies

is an async function that allows you to read the HTTP incoming request cookies in Server Components, and read/write outgoing request cookies in Server...

draftMode

is an async function allows you to enable and disable Draft Mode, as well as check if Draft Mode is enabled in a Server Component.

fetch

Next.js extends the Web API to allow each request on the server to set its own persistent caching and revalidation semantics.

forbidden

> This feature is currently experimental and subject to change, it is not recommended for production.

generateImageMetadata

You can use to generate different versions of one image or return multiple images for one route segment. This is useful for when you want to avoid ha...

generateMetadata

You can use the object or the function to define metadata.

generateSitemaps

You can use the function to generate multiple sitemaps for your application.

generateStaticParams

The function can be used in combination with dynamic route segments to statically generate routes at build time instead of on-demand at request time.

generateViewport

You can customize the initial viewport of the page with the static object or the dynamic function.

headers

is an async function that allows you to read the HTTP incoming request headers from a Server Component.

ImageResponse

The constructor allows you to generate dynamic images using JSX and CSS. This is useful for generating social media images such as Open Graph images,...

NextRequest

NextRequest extends the Web Request API with additional convenience methods.

NextResponse

NextResponse extends the Web Response API with additional convenience methods.

notFound

The function allows you to render the within a route segment as well as inject a tag.

permanentRedirect

The function allows you to redirect the user to another URL. can be used in Server Components, Client Components, Route Handlers, and Server Functio...

redirect

The function allows you to redirect the user to another URL. can be used while rendering in Server and Client Components, Route Handlers, and Server...

refresh

allows you to refresh the client router from within a Server Action.

revalidatePath

allows you to invalidate cached data on-demand for a specific path.

revalidateTag

allows you to invalidate cached data on-demand for a specific cache tag.

unauthorized

> This feature is currently experimental and subject to change, it is not recommended for production.

unstable_cache

> This API has been replaced by in Next.js 16.

unstable_noStore

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

unstable_rethrow

> This feature is currently unstable and subject to change, it is not recommended for production.

updateTag

allows you to update cached data on-demand for a specific cache tag from within Server Actions.

useLinkStatus

The hook lets you track the pending state of a . Use it for subtle, inline feedback, for example a shimmer effect over the clicked link, while naviga...

useParams

is a Client Component hook that lets you read a route's dynamic params filled in by the current URL.

usePathname

is a Client Component hook that lets you read the current URL's pathname.

useReportWebVitals

The hook allows you to report Core Web Vitals, and can be used in combination with your analytics service.

useRouter

The hook allows you to programmatically change routes inside Client Components.

useSearchParams

is a Client Component hook that lets you read the current URL's query string.

useSelectedLayoutSegment

is a Client Component hook that lets you read the active route segment one level below the Layout it is called from.

useSelectedLayoutSegments

is a Client Component hook that lets you read the active route segments below the Layout it is called from.

userAgent

The helper extends the Web Request API with additional properties and methods to interact with the user agent object from the request.

Turbopack

Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. You can use Turbopack with both ...

Getting Started

Welcome to the Next.js documentation!

Cache Components

> Good to know: Cache Components is an opt-in feature. Enable it by setting the flag to in your Next config file. See Enabling Cache Components for ...

Caching and Revalidating

Caching is a technique for storing the result of data fetching and other computations so that future requests for the same data can be served faster, ...

Tailwind CSS

Next.js provides several ways to style your application using CSS, including:

Deploying

Next.js can be deployed as a Node.js server, Docker container, static export, or adapted to run on different platforms.

Error Handling

Errors can be divided into two categories: expected errors and uncaught exceptions. This page will walk you through how you can handle these errors in...

Fetching Data

This page will walk you through how you can fetch data in Server and Client Components, and how to stream components that depend on data.

Font Optimization

The module automatically optimizes your fonts and removes external network requests for improved privacy and performance.

Image Optimization

The Next.js component extends the HTML element to provide:

Installation

Create a new Next.js app and run it locally.

Layouts and Pages

Next.js uses file-system based routing, meaning you can use folders and files to define routes. This page will guide you through how to create layouts...

Linking and Navigating

In Next.js, routes are rendered on the server by default. This often means the client has to wait for a server response before a new route can be show...

Metadata and OG images

The Metadata APIs can be used to define your application metadata for improved SEO and web shareability and include:

Project structure and organization

This page provides an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project.

Proxy

> Good to know: Starting with Next.js 16, Middleware is now called Proxy to better reflect its purpose. The functionality remains the same.

Route Handlers

Route Handlers allow you to create custom request handlers for a given route using the Web Request and Response APIs.

Server and Client Components

By default, layouts and pages are Server Components, which lets you fetch data and render parts of your UI on the server, optionally cache the result,...

Updating Data

You can update data in Next.js using React's Server Functions. This page will go through how you can create and invoke Server Functions.

Upgrading

To update to the latest version of Next.js, you can use the command:

Next.js Glossary

The Next.js router introduced in version 13, built on top of React Server Components. It uses file-system based routing and supports layouts, nested r...

Guides

How to set up your Next.js project for AI coding agents

Next.js ships version-matched documentation inside the package, allowing AI coding agents to reference accurate, up-to-date APIs and patterns. An fi...

How to add analytics to your Next.js application

Next.js has built-in support for measuring and reporting performance metrics. You can either use the hook to manage reporting yourself, or alternativ...

How to implement authentication in Next.js

Understanding authentication is crucial for protecting your application's data. This page will guide you through what React and Next.js features to us...

How to use Next.js as a backend for your frontend

Next.js supports the "Backend for Frontend" pattern. This lets you create public endpoints to handle HTTP requests and return any content type—not jus...

Caching in Next.js

Next.js improves your application's performance and reduces costs by caching rendering work and data requests. This page provides an in-depth look at ...

How to configure Continuous Integration (CI) build caching

To improve build performance, Next.js saves a cache to that is shared between builds.

How to set a Content Security Policy (CSP) for your Next.js application

By using CSP, developers can specify which origins are permissible for content sources, scripts, stylesheets, images, fonts, objects, media (audio, vi...

How to use CSS-in-JS libraries

> Warning: Using CSS-in-JS with newer React features like Server Components and Streaming requires library authors to support the latest version of Re...

How to set up a custom server in Next.js

Next.js includes its own server with by default. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A ...

How to think about data security in Next.js

This guide will help you understand how to think about data security in Next.js and how to implement best practices.

How to use debugging tools with Next.js

This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using the VS Code debugger, Chrome ...

How to preview content with Draft Mode in Next.js

This page walks through how to enable and use Draft Mode.

How to use environment variables in Next.js

Next.js comes with built-in support for environment variables, which allows you to do the following:

How to create forms with Server Actions

React Server Actions are Server Functions that execute on the server. They can be called in Server and Client Components to handle form submissions. T...

How to implement Incremental Static Regeneration (ISR)

Incremental Static Regeneration (ISR) enables you to:

How to set up instrumentation

Instrumentation is the process of using code to integrate monitoring and logging tools into your application. This allows you to track the performance...

Internationalization

Next.js enables you to configure the routing and rendering of content to support multiple languages. Making your site adaptive to different locales in...

How to implement JSON-LD in your Next.js application

Our current recommendation for JSON-LD is to render structured data as a tag in your or components.

How to lazy load Client Components and libraries

It allows you to defer loading of Client Components and imported libraries, and only include them in the client bundle when they're needed. For exampl...

How to optimize your local development environment

Next.js is designed to provide a great developer experience. As your application grows, you might notice slower compilation times during local develop...

Enabling Next.js MCP Server for Coding Agents

The Model Context Protocol (MCP) is an open standard that allows AI agents and coding assistants to interact with your applications through a standard...

How to use markdown and MDX in Next.js

Next.js can support both local MDX content inside your application, as well as remote MDX files fetched dynamically on the server. The Next.js plugin ...

How to optimize memory usage

As applications grow and become more feature rich, they can demand more resources when developing locally or creating production builds.

Migrating

How to migrate from Pages to the App Router

This guide will help you:

How to migrate from Create React App to Next.js

This guide will help you migrate an existing Create React App (CRA) site to Next.js.

How to migrate from Vite to Next.js

This guide will help you migrate an existing Vite application to Next.js.

How to build multi-tenant apps in Next.js

If you are looking to build a single Next.js application that serves multiple tenants, we have built an example showing our recommended architecture.

How to build micro-frontends using multi-zones and Next.js

Multi-Zones are an approach to micro-frontends that separate a large application on a domain into smaller Next.js applications that each serve a set o...

How to set up instrumentation with OpenTelemetry

Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app.

Optimizing package bundling

Bundling is the process of combining your application code and its dependencies into optimized output files for the client and server. Smaller bundles...

Prefetching

Prefetching makes navigating between different routes in your application feel instant. Next.js tries to intelligently prefetch by default, based on t...

How to optimize your Next.js application for production

Before taking your Next.js application to production, there are some optimizations and patterns you should consider implementing for the best user exp...

How to build a Progressive Web Application (PWA) with Next.js

Progressive Web Applications (PWAs) offer the reach and accessibility of web applications combined with the features and user experience of native mob...

Building public pages

Public pages show the same content to every user. Common examples include landing pages, marketing pages, and product pages.

How to handle redirects in Next.js

There are a few ways you can handle redirects in Next.js. This page will go through each available option, use cases, and how to manage large numbers ...

How to use Sass

Next.js has built-in support for integrating with Sass after the package is installed using both the and extensions. You can use component-level Sas...

How to load and optimize scripts

To load a third-party script for multiple routes, import and include the script directly in your layout component:

How to self-host your Next.js application

When deploying your Next.js app, you may want to configure how different features are handled based on your infrastructure.

How to build single-page applications with Next.js

Next.js fully supports building Single-Page Applications (SPAs).

How to create a static export of your Next.js application

Next.js enables starting as a static site or Single-Page Application (SPA), then later optionally upgrading to use features that require a server.

How to install Tailwind CSS v3 in your Next.js application

This guide will walk you through how to install Tailwind CSS v3 in your Next.js application.

Testing

In React and Next.js, there are a few different types of tests you can write, each with its own purpose and use cases. This page provides an overview ...

How to set up Cypress with Next.js

> * Cypress versions below 13.6.3 do not support TypeScript version 5 with . However, this issue has been resolved in Cypress version 13.6.3 and later...

How to set up Jest with Next.js

Jest and React Testing Library are frequently used together for Unit Testing and Snapshot Testing. This guide will show you how to set up Jest with Ne...

How to set up Playwright with Next.js

Playwright is a testing framework that lets you automate Chromium, Firefox, and WebKit with a single API. You can use it to write End-to-End (E2E) tes...

How to set up Vitest with Next.js

Vitest and React Testing Library are frequently used together for Unit Testing. This guide will show you how to setup Vitest with Next.js and write yo...

How to optimize third-party libraries

All third-party integrations provided by have been optimized for performance and ease of use.

Upgrade Guides

Learn how to upgrade to the latest versions of Next.js following the versions-specific guides:

Codemods

Codemods are transformations that run on your codebase programmatically. This allows a large number of changes to be programmatically applied without ...

How to upgrade to version 14

To update to Next.js version 14, run the following command using your preferred package manager:

How to upgrade to version 15

To update to Next.js version 15, you can use the codemod:

How to upgrade to version 16

If you're using an AI coding assistant that supports the Model Context Protocol (MCP), you can use the Next.js DevTools MCP to automate the upgrade pr...

How to use and optimize videos

This page outlines how to use videos with Next.js applications, showing how to store and display video files without affecting performance.

Architecture

Learn about the Next.js architecture and how it works under the hood.

Accessibility

The Next.js team is committed to making Next.js accessible to all developers (and their end-users). By adding accessibility features to Next.js by def...

Fast Refresh

Fast refresh is a React feature integrated into Next.js that allows you to live reload the browser page while maintaining temporary client-side state ...

Next.js Compiler

The Next.js Compiler, written in Rust using SWC, allows Next.js to transform and minify your JavaScript code for production. This replaces Babel for i...

Supported Browsers

Next.js supports modern browsers with zero configuration.

Next.js Community

With over 5 million weekly downloads, Next.js has a large and active community of developers across the world. Here's how you can get involved in our ...

Docs Contribution Guide

Welcome to the Next.js Docs Contribution Guide! We're excited to have you here.

Rspack Integration

> This feature is currently experimental and subject to change, it is not recommended for production.

Addressing "App Container Deprecated" Error in Next.js

This document guides developers on how to resolve the "App Container Deprecated" error in Next.js by updating their custom App component.

Uncached data was accessed outside of

When the feature is enabled, Next.js expects a parent boundary around any component that awaits data that should be accessed on every user request. ...

Conflicting Public File and Page File

One of your public files has the same path as a page file which is not supported. Since only one resource can reside at the URL both public files and ...

Empty generateStaticParams with Cache Components

You're using Cache Components in your Next.js application, and one of your functions returned an empty array, which causes a build error.

Google Font Display

> Enforce font-display behavior with Google Fonts.

Google Font Preconnect

> Note: Next.js automatically adds after version .

Inline script id

> Enforce attribute on components with inline content.

Middleware Upgrade Guide

As we work on improving Middleware for General Availability (GA), we've made some changes to the Middleware APIs (and how you define Middleware in you...

Missing Suspense boundary with useSearchParams

Reading search parameters through without a Suspense boundary will opt the entire page into client-side rendering. This could cause your page to be b...

next/dynamic has deprecated loading multiple modules at once

The ability to load multiple modules at once has been deprecated in to be closer to React's implementation ( and ).

Cannot access cookies() or headers() in "use cache"

A function is trying to read from the current incoming request inside the scope of a function annotated with . This is not supported because it would ...

Using Google Analytics with Next.js (through @next/third-parties/google)

> Prefer when using the inline script for Google Analytics and Tag Manager.

No assign module variable

> Prevent assignment to the variable.

No async Client Component

> Client components cannot be async functions.

No Before Interactive Script Outside Document

> Prevent usage of 's strategy outside of or .

No Cache Detected

A Next.js build was triggered in a continuous integration environment, but no cache was detected.

No CSS Tags

> Prevent manual stylesheet tags.

No Document Import in Page

> Prevent importing outside of .

No Duplicate Head

> Prevent duplicate usage of in .

No Head Element

> Prevent usage of element.

No Head Import in Document

> Prevent usage of in .

No HTML link for pages

> Prevent usage of elements to navigate to internal Next.js pages.

No img element

> Prevent usage of element due to slower LCP and higher bandwidth.

No Page Custom Font

> Prevent page-only custom fonts.

No Script Component in Head

> Prevent usage of in component.

No styled-jsx in _document

> Prevent usage of in .

No Sync Scripts

> Prevent synchronous scripts.

No Title in Document Head

> Prevent usage of with component from .

No Unwanted Polyfill.io

> Prevent duplicate polyfills from Polyfill.io.

Dynamic APIs are Asynchronous

Learn more about why accessing certain APIs synchronously now warns.

url is deprecated

In versions prior to 6.x the property got magically injected into every component (every page inside the directory).

Webpack 5 Adoption

Next.js has adopted webpack 5 as the default for compilation. We've spent a lot of effort into ensuring the transition from webpack 4 to 5 will be as ...

Pages Router

> You're viewing the documentation for the Pages Router. See the App Router documentation for the latest features.

API Reference

index

Next.js comes with two Command Line Interface (CLI) tools:

create-next-app CLI

The CLI allow you to create a new Next.js application using the default template or an example from a public GitHub repository. It is the easiest way...

next CLI

The Next.js CLI allows you to develop, build, start your application, and more.

Components

Font Module

It includes built-in automatic self-hosting for any font file. This means you can optimally load web fonts with no layout shift.

Form

The component extends the HTML element to provide client-side navigation on submission, and progressive enhancement.

Head

We expose a built-in component for appending elements to the of the page:

Image (Legacy)

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

Image

The Next.js Image component extends the HTML element for automatic image optimization.

Link

is a React component that extends the HTML element to provide prefetching and client-side navigation between routes. It is the primary way to navigat...

Script

This API reference will help you understand how to use props available for the Script Component. For features and usage, please see the Optimizing Scr...

Configuration

ESLint

Next.js provides an ESLint configuration package, , that makes it easy to catch common issues in your application. It includes the plugin along with ...

next.config.js Options

Next.js can be configured through a file in the root of your project directory (for example, by ) with a default export.

experimental.adapterPath

Next.js provides an experimental API that allows you to create custom adapters to hook into the build process. This is useful for deployment platforms...

allowedDevOrigins

Next.js does not automatically block cross-origin requests during development, but will block by default in a future major version of Next.js to preve...

assetPrefix

> Attention: Deploying to Vercel automatically configures a global CDN for your Next.js project.

basePath

To deploy a Next.js application under a sub-path of a domain you can use the config option.

bundlePagesRouterDependencies

Enable automatic server-side dependency bundling for Pages Router applications. Matches the automatic dependency bundling in App Router.

compress

By default, Next.js uses to compress rendered content and static files when using or a custom server. This is an optimization for applications that ...

crossOrigin

Use the option to add a attribute in all tags generated by the and components, and define how cross-origin requests should be handled.

deploymentId

The option allows you to set an identifier for your deployment. This identifier is used for version skew protection and cache busting during rolling ...

devIndicators

allows you to configure the on-screen indicator that gives context about the current route you're viewing during development.

distDir

You can specify a name to use for a custom build directory to use instead of .

index

> Since the release of Next.js 9.4 we now have a more intuitive and ergonomic experience for adding environment variables. Give it a try!

exportPathMap

> This feature is exclusive to and currently deprecated in favor of with or with .

generateBuildId

Next.js generates an ID during to identify which version of your application is being served. The same build should be used and boot up multiple cont...

generateEtags

Next.js will generate etags for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.

headers

Headers allow you to set custom HTTP headers on the response to an incoming request on a given path.

httpAgentOptions

In Node.js versions prior to 18, Next.js automatically polyfills with undici and enables HTTP Keep-Alive by default.

images

If you want to use a cloud provider to optimize images instead of using the Next.js built-in Image Optimization API, you can configure with the follo...

isolatedDevBuild

The experimental option separates development and production build outputs into different directories. When enabled, the development server () writes...

onDemandEntries

Next.js exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.

optimizePackageImports

> This feature is currently experimental and subject to change, it is not recommended for production.

output

During a build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a producti...

pageExtensions

You can extend the default Page extensions (, , , ) used by Next.js. Inside , add the config:

poweredByHeader

By default Next.js will add the header. To opt-out of it, open and disable the config:

productionBrowserSourceMaps

Source Maps are enabled by default during development. During production builds, they are disabled to prevent you leaking your source on the client, u...

experimental.proxyClientMaxBodySize

When proxy is used, Next.js automatically clones the request body and buffers it in memory to enable multiple reads - both in proxy and the underlying...

reactStrictMode

> Good to know: Since Next.js 13.5.1, Strict Mode is by default with router, so the above configuration is only necessary for . You can still disabl...

redirects

Redirects allow you to redirect an incoming request path to a different destination path.

rewrites

Rewrites allow you to map an incoming request path to a different destination path.

serverExternalPackages

Opt-out specific dependencies from being included in the automatic bundling of the option.

trailingSlash

By default Next.js will redirect URLs with trailing slashes to their counterpart without a trailing slash. For example will redirect to . You can con...

transpilePackages

Next.js can automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (). This replaces the ...

turbopack

> This feature is currently experimental and subject to change, it is not recommended for production.

typescript

Configure TypeScript behavior with the option in :

urlImports

> This feature is currently experimental and subject to change, it is not recommended for production.

useLightningcss

> This feature is currently experimental and subject to change, it is not recommended for production.

Custom Webpack Config

> Good to know: changes to webpack config are not covered by semver so proceed at your own risk

webVitalsAttribution

When debugging issues related to Web Vitals, it is often helpful if we can pinpoint the source of the problem.

TypeScript

Next.js comes with built-in TypeScript, automatically installing the necessary packages and configuring the proper settings when you create a new proj...

Edge Runtime

Next.js has two server runtimes you can use in your application:

File-system conventions

instrumentation.js

The file is used to integrate observability tools into your application, allowing you to track the performance and behavior, and to debug issues in p...

Proxy

> Note: The file convention is deprecated and has been renamed to . See Migration to Proxy for more details.

public Folder

Next.js can serve static files, like images, under a folder called in the root directory. Files inside can then be referenced by your code starting ...

src Directory

As an alternative to having the special Next.js or directories in the root of your project, Next.js also supports the common pattern of placing appl...

Functions

getInitialProps

> Good to know: is a legacy API. We recommend using or instead.

getServerSideProps

When exporting a function called (Server-Side Rendering) from a page, Next.js will pre-render this page on each request using the data returned by . ...

getStaticPaths

When exporting a function called from a page that uses Dynamic Routes, Next.js will statically pre-render all the paths specified by .

getStaticProps

Exporting a function called will pre-render a page at build time using the props returned from the function:

NextRequest

NextRequest extends the Web Request API with additional convenience methods.

NextResponse

NextResponse extends the Web Response API with additional convenience methods.

useParams

is a hook that lets you read a route's dynamic params filled in by the current URL.

useReportWebVitals

The hook allows you to report Core Web Vitals, and can be used in combination with your analytics service.

useRouter

If you want to access the object inside any function component in your app, you can use the hook, take a look at the following example:

useSearchParams

is a hook that lets you read the current URL's query string.

userAgent

The helper extends the Web Request API with additional properties and methods to interact with the user agent object from the request.

Turbopack

Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. You can use Turbopack with both ...

Building Your Application

Configuring

Next.js allows you to customize your project to meet specific requirements. This includes integrations with TypeScript, ESlint, and more, as well as i...

Data Fetching

Data fetching in Next.js allows you to render your content in different ways, depending on your application's use case. These include pre-rendering wi...

Client-side Fetching

Client-side data fetching is useful when your page doesn't require SEO indexing, when you don't need to pre-render your data, or when the content of y...

getServerSideProps

is a Next.js function that can be used to fetch data and render the contents of a page at request time.

getStaticPaths

If a page has Dynamic Routes and uses , it needs to define a list of paths to be statically generated.

getStaticProps

If you export a function called (Static Site Generation) from a page, Next.js will pre-render this page at build time using the props returned by .

Automatic Static Optimization

Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the...

Client-side Rendering (CSR)

In Client-Side Rendering (CSR) with React, the browser downloads a minimal HTML page and the JavaScript needed for the page. The JavaScript is then us...

Server-side Rendering (SSR)

> Also referred to as "SSR" or "Dynamic Rendering".

Static Site Generation (SSG)

If a page uses Static Generation, the page HTML is generated at build time. That means in production, the page HTML is generated when you run . This H...

Routing

The Pages Router has a file-system based router built on concepts of pages. When a file is added to the directory it's automatically available as a r...

API Routes

> Good to know: If you are using the App Router, you can use Server Components or Route Handlers instead of API Routes.

Custom App

Next.js uses the component to initialize pages. You can override it and control the page initialization and:

Custom Document

A custom can update the and tags used to render a Page.

Custom Errors

A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server. This can result in inc...

Dynamic Routes

When you don't know the exact segment names ahead of time and want to create routes from dynamic data, you can use Dynamic Segments that are filled in...

Linking and Navigating

The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.

Pages and Layouts

The Pages Router has a file-system based router built on the concept of pages.

Getting Started - Pages Router

How to use CSS in your application

Next.js provides several ways to style your application using CSS, including:

How to deploy your Next.js application

Next.js can be deployed as a Node.js server, Docker container, static export, or adapted to run on different platforms.

How to use fonts

The module automatically optimizes your fonts and removes external network requests for improved privacy and performance.

Image Optimization

The Next.js component extends the HTML element to provide:

Create a new Next.js application

Before you begin, make sure your development environment meets the following requirements:

Project Structure and Organization

This page provides an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project.

Guides

How to set up analytics

Next.js has built-in support for measuring and reporting performance metrics. You can either use the hook to manage reporting yourself, or alternativ...

How to implement authentication in Next.js

Understanding authentication is crucial for protecting your application's data. This page will guide you through what React and Next.js features to us...

How to configure Babel in Next.js

Next.js includes the preset to your app, which includes everything needed to compile React applications and server-side code. But if you want to exte...

How to configure Continuous Integration (CI) build caching

To improve build performance, Next.js saves a cache to that is shared between builds.

How to set a Content Security Policy (CSP) for your Next.js application

By using CSP, developers can specify which origins are permissible for content sources, scripts, stylesheets, images, fonts, objects, media (audio, vi...

How to use CSS-in-JS libraries

It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:

How to set up a custom server in Next.js

Next.js includes its own server with by default. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A ...

How to use debugging tools with Next.js

This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using the VS Code debugger, Chrome ...

How to preview content with Draft Mode in Next.js

In the Pages documentation and the Data Fetching documentation, we talked about how to pre-render a page at build time (Static Generation) using and ...

How to use environment variables in Next.js

Next.js comes with built-in support for environment variables, which allows you to do the following:

How to create forms with API Routes

Forms enable you to create and update data in web applications. Next.js provides a powerful way to handle data mutations using API Routes. This guide ...

How to implement Incremental Static Regeneration (ISR)

Incremental Static Regeneration (ISR) enables you to:

How to set up instrumentation

Instrumentation is the process of using code to integrate monitoring and logging tools into your application. This allows you to track the performance...

How to implement internationalization in Next.js

Next.js has built-in support for internationalized (i18n) routing since . You can provide a list of locales, the default locale, and domain-specific l...

How to lazy load Client Components and libraries

is a composite of and Suspense. It behaves the same way in the and directories to allow for incremental migration.

How to use markdown and MDX in Next.js

Next.js can support both local MDX content inside your application, as well as remote MDX files fetched dynamically on the server. The Next.js plugin ...

Migrating

How to migrate from Pages to the App Router

This guide will help you:

How to migrate from Create React App to Next.js

This guide will help you migrate an existing Create React App (CRA) site to Next.js.

How to migrate from Vite to Next.js

This guide will help you migrate an existing Vite application to Next.js.

How to build micro-frontends using multi-zones and Next.js

Multi-Zones are an approach to micro-frontends that separate a large application on a domain into smaller Next.js applications that each serve a set o...

How to instrument your Next.js app with OpenTelemetry

Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app.

How to optimize package bundling

Bundling is the process of combining your application code and its dependencies into optimized output files for the client and server. Smaller bundles...

How to configure PostCSS in Next.js

Next.js compiles CSS for its built-in CSS support using PostCSS.

How to preview content with Preview Mode in Next.js

> This is a legacy API and no longer recommended. It is still supported for backward compatibility.

How to optimize your Next.js application for production

Before taking your Next.js application to production, there are some optimizations and patterns you should consider implementing for the best user exp...

How to handle redirects in Next.js

There are a few ways you can handle redirects in Next.js. This page will go through each available option, use cases, and how to manage large numbers ...

How to use Sass in Next.js

Next.js has built-in support for integrating with Sass after the package is installed using both the and extensions. You can use component-level Sas...

How to load and optimize scripts

To load a third-party script for all routes, import and include the script directly in your custom :

How to self-host your Next.js application

When deploying your Next.js app, you may want to configure how different features are handled based on your infrastructure.

How to create a static export of your Next.js application

Next.js enables starting as a static site or Single-Page Application (SPA), then later optionally upgrading to use features that require a server.

Tailwind CSS

This guide will walk you through how to install Tailwind CSS v3 in your Next.js application.

Testing

In React and Next.js, there are a few different types of tests you can write, each with its own purpose and use cases. This page provides an overview ...

How to set up Cypress with Next.js

> * Cypress versions below 13.6.3 do not support TypeScript version 5 with . However, this issue has been resolved in Cypress version 13.6.3 and later...

How to set up Jest with Next.js

Jest and React Testing Library are frequently used together for Unit Testing and Snapshot Testing. This guide will show you how to set up Jest with Ne...

How to set up Playwright with Next.js

Playwright is a testing framework that lets you automate Chromium, Firefox, and WebKit with a single API. You can use it to write End-to-End (E2E) tes...

How to set up Vitest with Next.js

Vitest and React Testing Library are frequently used together for Unit Testing. This guide will show you how to setup Vitest with Next.js and write yo...

How to optimize third-party libraries

All third-party integrations provided by have been optimized for performance and ease of use.

Upgrading

Learn how to upgrade to the latest versions of Next.js following the versions-specific guides:

Codemods

Codemods are transformations that run on your codebase programmatically. This allows a large number of changes to be programmatically applied without ...

How to upgrade to version 10

There were no breaking changes between versions 9 and 10.

How to upgrade to version 11

To upgrade to version 11, run the following command:

How to upgrade to version 12

To upgrade to version 12, run the following command:

How to upgrade to version 13

To update to Next.js version 13, run the following command using your preferred package manager:

How to upgrade to version 14

To update to Next.js version 14, run the following command using your preferred package manager:

How to upgrade to version 9

To upgrade to version 9, run the following command:

Installation

Playwright Test is an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling. ...

Accessibility testing

Playwright can be used to test your application for many types of accessibility issues.

Auto-waiting

Playwright performs a range of actionability checks on the elements before making actions to ensure these actions behave as expected. It auto-waits fo...

API testing

Playwright can be used to get access to the REST API of your application.

Android

Playwright has experimental support for Android automation. This includes Chrome for Android and Android WebView.

AndroidDevice

Added in: v1.9 androidDevice.close

AndroidInput

Added in: v1.9 androidInput.drag

AndroidSocket

Added in: v1.9 androidSocket.close

AndroidWebView

Added in: v1.9 androidWebView.page

APIRequest

Exposes API that can be used for the Web API testing. This class is used for creating APIRequestContext instance which in turn can be used for sending...

APIRequestContext

This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare environment or the service to you...

APIResponse

Added in: v1.16 apiResponse.body

APIResponseAssertions

The APIResponseAssertions class provides assertion methods that can be used to make assertions about the APIResponse in the tests.

Browser

A Browser is created via browserType.launch(). An example of using a Browser to create a Page:

BrowserContext

BrowserContexts provide a way to operate multiple independent browser sessions.

BrowserServer

Added before v1.9 browserServer.close

BrowserType

BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwrig...

CDPSession

The instances are used to talk raw Chrome Devtools Protocol:

Clock

Accurately simulating time-dependent behavior is essential for verifying the correctness of applications. Learn more about clock emulation.

ConsoleMessage

// Listen for all console logs

Coverage

Coverage gathers information about parts of JavaScript and CSS that were used by the page.

Dialog

An example of using class:

Download

All the downloaded files belonging to the browser context are deleted when the browser context is closed.

Electron

Playwright has experimental support for Electron automation. You can access electron namespace via:

ElectronApplication

Electron application representation. You can use electron.launch() to obtain the application instance. This instance you can control main electron pro...

ElementHandle

ElementHandle represents an in-page DOM element. ElementHandles can be created with the page.$() method.

FileChooser

// Start waiting for file chooser before clicking. Note no await.

Fixtures

Playwright Test is based on the concept of the test fixtures. Test fixtures are used to establish environment for each test, giving the test everythin...

Frame

At every point of time, page exposes its current frame tree via the page.mainFrame() and frame.childFrames() methods.

FrameLocator

FrameLocator represents a view to the on the page. It captures the logic sufficient to retrieve the and locate elements in that iframe. FrameLocator...

FullConfig

Resolved configuration which is accessible via testInfo.config and is passed to the test reporters. To see the format of Playwright configuration file...

FullProject

Runtime representation of the test project configuration. It is accessible in the tests via testInfo.project and workerInfo.project and is passed to t...

GenericAssertions

The GenericAssertions class provides assertion methods that can be used to make assertions about any values in the tests. A new instance of GenericAss...

JSHandle

JSHandle represents an in-page JavaScript object. JSHandles can be created with the page.evaluateHandle() method.

Keyboard

Keyboard provides an api for managing a virtual keyboard. The high level api is keyboard.type(), which takes raw characters and generates proper , /, ...

Location

Represents a location in the source code where TestCase or Suite is defined.

Locator

Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page ...

LocatorAssertions

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

Logger

This class is deprecated. The logs pumped through this class are incomplete. Please use tracing instead.

Mouse

The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.

Page

Page provides methods to interact with a single tab in a Browser, or an extension background page in Chromium. One Browser instance might have multipl...

PageAssertions

The PageAssertions class provides assertion methods that can be used to make assertions about the Page state in the tests.

Playwright Library

Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright to drive automation:

PlaywrightAssertions

Playwright gives you Web-First Assertions with convenience methods for creating assertions that will wait and retry until the expected condition is me...

Reporter

Test runner notifies the reporter about various events during test execution. All methods of the reporter are optional.

Request

Whenever the page sends a request for a network resource the following sequence of events are emitted by Page:

Response

Added in: v1.15 response.allHeaders

Route

Whenever a network route is set up with page.route() or browserContext.route(), the object allows to handle the route.

Selectors

Selectors can be used to install custom selector engines. See extensibility for more information.

SnapshotAssertions

Playwright provides methods for comparing page and element screenshots with expected values stored in files.

Suite

is a group of tests. All tests in Playwright Test form the following hierarchy:

Playwright Test

Playwright Test provides a function to declare tests and function to write assertions.

TestCase

corresponds to every test() call in a test file. When a single test() is running in multiple projects or repeated multiple times, it will have multipl...

TestConfig

Playwright Test provides many options to configure how your tests are collected and executed, for example or . These options are described in the Tes...

TestError

Information about an error thrown during test execution.

TestInfo

contains information about currently running test. It is available to test functions, test.beforeEach(), test.afterEach(), test.beforeAll() and test.a...

TestInfoError

Information about an error thrown during test execution.

TestOptions

Playwright Test provides many options to configure test environment, Browser, BrowserContext and more.

TestProject

Playwright Test supports running multiple test projects at the same time. This is useful for running tests in multiple configurations. For example, co...

TestResult

A result of a single TestCase run.

TestStep

Represents a step in the [TestRun].

TestStepInfo

contains information about currently running test step. It is passed as an argument to the step function. provides utilities to control test step exe...

TimeoutError

TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. locator.waitFor() or browserType.launch().

Touchscreen

The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the touchscreen can only be used i...

Tracing

API for collecting and saving Playwright traces. Playwright traces can be opened in Trace Viewer after Playwright script runs.

Video

When browser context is created with the option, each page has a video object associated with it.

WebError

// Log all uncaught errors to the terminal

WebSocket

The WebSocket class represents WebSocket connections within a page. It provides the ability to inspect and manipulate the data being transmitted and r...

WebSocketRoute

Whenever a route is set up with page.routeWebSocket() or browserContext.routeWebSocket(), the object allows to handle the WebSocket, like an actual ...

Worker

The Worker class represents a WebWorker. event is emitted on the page object to signal a worker creation. event is emitted on the worker object when...

WorkerInfo

contains information about the worker that is running tests and is available to worker-scoped fixtures. is a subset of TestInfo that is available in ...

Snapshot testing

With Playwright's Snapshot testing you can assert the accessibility tree of a page against a predefined snapshot template.

Authentication

Playwright executes tests in isolated environments called browser contexts. This isolation model improves reproducibility and prevents cascading test ...

Best Practices

This guide should help you to make sure you are following our best practices and writing tests that are more resilient.

Isolation

Tests written with Playwright execute in isolated clean-slate environments called browser contexts. This isolation model improves reproducibility and ...

Browsers

Each version of Playwright needs specific versions of browser binaries to operate. You will need to use the Playwright CLI to install these browsers.

Canary releases

Playwright for Node.js has a canary releases system.

Chrome extensions

Extensions only work in Chromium when launched with a persistent context. Use custom browser args at your own risk, as some of them may break Playwrig...

Setting up CI

Playwright tests can be run on any CI provider. This guide covers one way of running tests on GitHub using GitHub Actions. If you would like to learn ...

Continuous Integration

Playwright tests can be executed in CI environments. We have created sample configurations for common CI providers.

Clock

Accurately simulating time-dependent behavior is essential for verifying the correctness of applications. Utilizing Clock functionality allows develop...

Generating tests

Playwright can generate tests automatically, providing a quick way to get started with testing. Codegen opens a browser window for interaction and the...

Test generator

Playwright comes with the ability to generate tests for you as you perform actions in the browser and is a great way to quickly get started with testi...

Debugging Tests

We recommend using the VS Code Extension for debugging for a better developer experience. With the VS Code extension you can debug your tests right in...

Dialogs

Playwright can interact with the web page dialogs such as , , as well as confirmation. For print dialogs, see Print.

Docker

This Docker image is published to Microsoft Artifact Registry.

Downloads

For every attachment downloaded by the page, page.on('download') event is emitted. All these attachments are downloaded into a temporary folder. You c...

Emulation

With Playwright you can test your app on any browser as well as emulate a real device such as a mobile phone or tablet. Simply configure the devices y...

Evaluating JavaScript

Playwright scripts run in your Playwright environment. Your page scripts run in the browser page environment. Those environments don't intersect, they...

Events

Playwright allows listening to various types of events happening on the web page, such as network requests, creation of child pages, dedicated workers...

Extensibility

Playwright supports custom selector engines, registered with selectors.register().

Frames

A Page can have one or more Frame objects attached to it. Each page has a main frame and page-level interactions (like ) are assumed to operate in the...

Getting started - VS Code

The Playwright VS Code extension brings the power of Playwright Test directly into your editor, allowing you to run, debug, and generate tests with a ...

Handles

Playwright can create handles to the page DOM elements or any other objects inside the page. These handles live in the Playwright process, whereas the...

Actions

Playwright can interact with HTML Input elements such as text inputs, checkboxes, radio buttons, select options, mouse clicks, type characters, keys a...

Installation

Playwright Test is an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling. ...

Supported languages

Playwright is available in multiple languages that share the same underlying implementation. All core features for automating the browser are supporte...

Library

Playwright Library provides unified APIs for launching and interacting with browsers, while Playwright Test provides all this plus a fully managed end...

Locators

These are the recommended built-in locators.

Mock browser APIs

Playwright provides native support for most of the browser features. However, there are some experimental APIs and APIs which are not (yet) fully supp...

Mock APIs

Web APIs are usually implemented as HTTP endpoints. Playwright provides APIs to mock and modify network traffic, both HTTP and HTTPS. Any requests tha...

Navigations

Playwright can navigate to URLs and handle navigations caused by the page interactions.

Network

Playwright provides APIs to monitor and modify browser network traffic, both HTTP and HTTPS. Any requests that a page does, including XHRs and fetch r...

Other locators

Check out the main locators guide for most common and recommended locators.

Pages

Each BrowserContext can have multiple pages. A Page refers to a single tab or a popup window within a browser context. It should be used to navigate t...

Page object models

Large test suites can be structured to optimize ease of authoring and maintenance. Page object models are one such approach to structure your test sui...

Migrating from Protractor

Migrating from Puppeteer

This guide describes migration to Playwright Library and Playwright Test from Puppeteer. The APIs have similarities, but Playwright offers much more p...

Release notes

If you're using merged reports, the HTML report Speedboard tab now shows the Timeline:

Running and debugging tests

With Playwright you can run a single test, a set of tests, or all tests. Tests can be run on one browser or multiple browsers using the flag. Tests r...

Screenshots

Here is a quick way to capture a screenshot and save it into a file:

Selenium Grid (experimental)

Playwright can connect to Selenium Grid Hub that runs Selenium 4 to launch Google Chrome or Microsoft Edge browser, instead of running browser on the ...

Service Workers

Service workers are only supported on Chromium-based browsers.

Agents

Playwright comes with three Playwright Test Agents out of the box: 🎭 planner , 🎭 generator and 🎭 healer.

Annotations

Playwright supports tags and annotations that are displayed in the test report.

Assertions

Playwright includes test assertions in the form of function. To make an assertion, call and choose a matcher that reflects the expectation. There ar...

Command line

Playwright provides a powerful command line interface for running tests, generating code, debugging, and more. The most up to date list of commands an...

Components (experimental)

Playwright Test can now test your components.

Configuration

Playwright has many options to configure how your tests are run. You can specify these options in the configuration file. Note that test runner option...

Fixtures

Playwright Test is based on the concept of test fixtures. Test fixtures are used to establish the environment for each test, giving the test everythin...

Global setup and teardown

There are two ways to configure global setup and teardown: using a global setup file and setting it in the config under or using project dependencies...

Parallelism

Playwright Test runs tests in parallel. In order to achieve that, it runs several worker processes that run at the same time. By default, test files a...

Parameterize tests

You can either parameterize tests on a test level or on a project level.

Projects

A project is logical group of tests running with the same configuration. We use projects so we can run tests on different browsers and devices. Projec...

Reporters

Playwright Test comes with a few built-in reporters for different needs and ability to provide custom reporters. The easiest way to try out built-in r...

Retries

Test retries are a way to automatically re-run a test when it fails. This is useful when a test is flaky and fails intermittently. Test retries are co...

Sharding

By default, Playwright runs test files in parallel and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater ...

Visual comparisons

Playwright Test includes the ability to produce and visually compare screenshots using . On first execution, Playwright test will generate reference s...

Timeouts

Playwright Test has multiple configurable timeouts for various tasks.

TypeScript

Playwright supports TypeScript out of the box. You just write tests in TypeScript, and Playwright will read them, transform to JavaScript and run.

UI Mode

UI Mode lets you explore, run, and debug tests with a time travel experience complete with a watch mode. All test files are displayed in the testing s...

Configuration (use)

In addition to configuring the test runner you can also configure Emulation, Network and Recording for the Browser or BrowserContext. These options ar...

Web server

Playwright comes with a option in the config file which gives you the ability to launch a local dev server before running your tests. This is ideal f...

Migrating from Testing Library

This guide describes migration to Playwright's Experimental Component Testing from DOM Testing Library, React Testing Library, Vue Testing Library and...

Touch events (legacy)

Web applications that handle legacy touch events to respond to gestures like swipe, pinch, and tap can be tested by manually dispatching TouchEvents t...

Trace viewer

Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright traces of your tests, meaning you can go back and forward through each...

Trace viewer

Playwright Trace Viewer is a GUI tool that helps you explore recorded Playwright traces after the script has run. Traces are a great way for debugging...

Videos

With Playwright you can record videos for your tests.

WebView2

The following will explain how to use Playwright with Microsoft Edge WebView2. WebView2 is a WinForms control, which will use Microsoft Edge under the...

Writing tests

Playwright tests are simple: they perform actions and assert the state against expectations.

Prisma ORM

Prisma ORM is a next-generation Node.js and TypeScript ORM that provides type-safe database access, migrations, and a visual data editor.

API patterns

How to use Prisma ORM with REST APIs, GraphQL servers, and fullstack frameworks

Data modeling

Learn how data modeling with Prisma differs from data modeling with SQL or ORMs. Prisma uses a declarative data modeling language to describe a databa...

Overview

Prisma ORM supports PostgreSQL, MySQL, SQLite, MongoDB, SQL Server, CockroachDB, and serverless databases

Database drivers

Learn how Prisma connects to your database using driver adapters

MongoDB

How Prisma ORM connects to MongoDB databases

MySQL

Use Prisma ORM with MySQL databases including self-hosted MySQL/MariaDB and serverless PlanetScale

PostgreSQL

Use Prisma ORM with PostgreSQL databases including self-hosted, serverless (Neon, Supabase), and CockroachDB

SQL Server

Use Prisma ORM with Microsoft SQL Server databases

SQLite

Use Prisma ORM with SQLite databases including local SQLite, Turso (libSQL), and Cloudflare D1

Best practices

Learn production-ready patterns for schema design, query optimization, type safety, security, and deployment with Prisma ORM.

Drizzle

Learn how Prisma ORM compares to Drizzle

Mongoose

Learn how Prisma ORM compares to Mongoose

Sequelize

Learn how Prisma ORM compares to Sequelize

TypeORM

Learn how Prisma compares to TypeORM

Editor setup

Learn how to configure your editor and IDEs for an optimal developer experience with Prisma ORM

Environment variables

Learn how to manage environment variables in your Prisma ORM project

ORM releases and maturity levels

Learn about the release process, versioning, and maturity of Prisma ORM components and how to deal with breaking changes that might happen throughout ...

Bundler issues

Solve ENOENT package error with vercel/pkg and other bundlers

Check constraints

Learn how to configure CHECK constraints for data validation with Prisma ORM and PostgreSQL

GraphQL autocompletion

Get autocompletion for Prisma Client queries in GraphQL resolvers with plain JavaScript

Many-to-many relations

Learn how to model, query, and convert many-to-many relations with Prisma ORM

Next.js

Best practices and troubleshooting for using Prisma ORM with Next.js applications

Nuxt

Learn how to integrate Prisma ORM with your Nuxt application

Raw SQL comparisons

Compare columns of the same table with raw queries in Prisma ORM

TypeScript performance

Optimize TypeScript compilation performance when working with large Prisma schemas

What are Client Extensions

Extend the functionality of Prisma Client

Add methods to Prisma Client

Extend the functionality of Prisma Client, client component

Shared packages & examples

Explore the Prisma Client extensions that have been built by Prisma and its community

Add custom methods to your models

Extend the functionality of Prisma Client, model component

Create custom Prisma Client queries

Extend the functionality of Prisma Client, query component

Add custom fields and methods to query results

Extend the functionality of Prisma Client, result component

Shared Prisma Client extensions

Share extensions or import shared extensions into your Prisma project

Fine-Grained Authorization (Permit)

Learn how to implement RBAC, ABAC, and ReBAC authorization in your Prisma applications

Type utilities

Advanced type safety: improve type safety in your custom model methods

Debugging

This page explains how to enable debugging output for Prisma Client by setting the environment variable

Handling exceptions and errors

This page covers how to handle exceptions and errors

Caveats when deploying to AWS platforms

Known caveats when deploying to an AWS platform

Deploying database changes with Prisma Migrate

Learn how to deploy database changes with Prisma Migrate

Deploy migrations from a local environment

Learn how to deploy Node.js and TypeScript applications that are using Prisma Client locally

Deploy Prisma ORM

Learn more about the different deployment paradigms for Node.js applications and how they affect deploying an application using Prisma Client

Deploy to Cloudflare Workers & Pages

Learn the things you need to know in order to deploy an app that uses Prisma Client for talking to a database to a Cloudflare Worker or to Cloudflare ...

Deploy to Deno Deploy

With this guide, you can learn how to build and deploy a REST API to Deno Deploy. The application uses Prisma ORM to manage tasks in a Prisma Postgres...

Deploy to Vercel Edge Functions & Middleware

Learn the things you need to know in order to deploy an Edge function that uses Prisma Client for talking to a database

Deploying edge functions with Prisma ORM

Learn how to deploy your Prisma-backed apps to edge functions like Cloudflare Workers or Vercel Edge Functions

Deploy to AWS Lambda

Learn how to deploy your Prisma ORM-backed applications to AWS Lambda with AWS SAM, Serverless Framework, or SST

Deploy to Azure Functions

Learn how to deploy a Prisma Client based REST API to Azure Functions and connect to an Azure SQL database

Deploy to Netlify

Learn how to deploy Node.js and TypeScript applications that are using Prisma Client to Netlify

Deploy to Vercel

Learn how to deploy a Next.js application based on Prisma Client to Vercel

Deploy to Fly.io

Learn how to deploy a Node.js server that uses Prisma ORM to Fly.io

Deploy to Heroku

Learn how to deploy a Node.js server that uses Prisma ORM to Heroku

Deploy to Koyeb

Learn how to deploy a Node.js server that uses Prisma ORM to Koyeb Serverless Platform

Deploy to Railway

Learn how to deploy an app that uses Prisma ORM and Prisma Postgres to Railway

Deploy to Render

Learn how to deploy a Node.js server that uses Prisma ORM to Render

Deploy to Sevalla

Learn how to deploy a Node.js server that uses Prisma ORM to Sevalla

Logging

Learn how to configure Prisma Client to log the raw SQL queries it sends to the database and other information

OpenTelemetry tracing

Diagnose application performance with detailed traces of each query

SQL comments

Add metadata to your SQL queries as comments for improved observability, debugging, and tracing

Query optimization using Prisma Optimize

How Prisma optimizes queries under the hood

Aggregation, grouping, and summarizing

Use Prisma Client to aggregate, group by, count, and select distinct.

CRUD

Learn how to perform create, read, update, and delete operations

CRUD

Learn how to perform create, read, update, and delete operations

Transactions and batch queries

This page explains the transactions API of Prisma Client

Custom model and field names

Learn how you can decouple the naming of Prisma models from database tables to improve the ergonomics of the generated Prisma Client API

Database polyfills

Prisma Client provides features that are not achievable with relational databases. These features are referred to as "polyfills" and explained on this...

Database connections

Learn how to manage database connections and configure connection pools

Connection management

This page explains how database connections are handled with Prisma Client and how to manually connect and disconnect your database

Connection pool

Prisma Client uses a connection pool (from the database driver or driver adapter) to store and manage database connections.

Configure Prisma Client with PgBouncer

Configure Prisma Client with PgBouncer and other poolers: when to use pgbouncer=true, required transaction mode, prepared statements, and Prisma Migra...

Configuring error formatting

This page explains how to configure the formatting of errors when using Prisma Client

Introduction to Prisma Client

Learn how to set up and configure Prisma Client in your project

Read replicas

Learn how to set up and use read replicas with Prisma Client

Fields & types

Learn how to use about special fields and types with Prisma Client

Composite types

Work with composite types and embedded documents in MongoDB

Null and undefined

How Prisma Client handles null and undefined

Working with compound IDs and unique constraints

How to read, write, and filter by compound IDs and unique constraints

Working with Json fields

How to read, write, and filter by Json fields

Working with scalar lists

How to read, write, and filter by scalar lists / arrays

Integration testing

Learn how to setup and run integration tests with Prisma and Docker

Unit testing

Learn how to setup and run unit tests with Prisma Client

Type safety Overview

Prisma Client provides full type safety for queries, even for partial queries or included relations. This page explains how to leverage the generated ...

Operating against partial structures of your model types

This page documents various scenarios for using the generated types from the Prisma namespace

How to use Prisma ORM's type system

Write your own SQL

Learn how to use raw SQL queries in Prisma Client

Raw queries

Learn how you can send raw SQL and MongoDB queries to your database using the raw() methods from the Prisma Client API

SafeQL & Prisma Client

Learn how to use SafeQL and Prisma Client extensions to work around features not natively supported by Prisma, such as PostGIS

TypedSQL

Learn how to use TypedSQL to write fully type-safe SQL queries that are compatible with any SQL console and Prisma Client

Overview of Prisma Migrate

Learn everything you need to know about Prisma Migrate

Getting started with Prisma Migrate

Learn how to migrate your schema in a development environment using Prisma Migrate

Limitations and known issues

Prisma Migrate does not currently support the MongoDB connector.

Understanding Migrations

A mental model guide for working with Prisma Migrate in your project

Migration histories

How Prisma ORM uses migration histories to track changes to your schema

About the shadow database

Learn how Prisma Migrate uses shadow databases to detect schema drift

Baselining a database

How to initialize a migration history for an existing database that contains important data.

Customizing migrations

How to edit a migration file before applying it to avoid data loss in production.

Development and production

How to use Prisma Migrate commands in development and production environments

Generating down migrations

How to generate a down migration SQL file that reverses a given migration file

Native database functions

How to enable PostgreSQL native database functions for projects that use Prisma Migrate.

Native database types

Patching & hotfixing

How to reconcile the migration history after applying a hotfix or patch to a production environment.

Prototyping your schema

Rapidly prototype your Prisma schema using db push without migrations

Seeding

Learn how to seed your database using Prisma ORM's integrated seeding functionality and Prisma Client

Squashing migrations

How to squash multiple migration files into a single migration

Troubleshooting

Troubleshooting issues with Prisma Migrate in a development environment.

Unsupported database features (Prisma Migrate)

How to include unsupported database features for projects that use Prisma Migrate

Database mapping

Learn how to map model and field names to database tables and columns

External tables

How to declare and use externally managed tables in Prisma ORM

Indexes

How to configure index functionality and add full text indexes

Models

Learn about the concepts for building your data model with Prisma: Models, scalar types, enums, attributes, functions, IDs, default values and more

Multi-schema

How to use Prisma ORM with multiple database schemas

Relations

A relation is a connection between two models in the Prisma schema. This page explains how you can define one-to-one, one-to-many and many-to-many rel...

Many-to-many relations

How to define and work with many-to-many relations in Prisma.

One-to-many relations

How to define and work with one-to-many relations in Prisma.

One-to-one relations

How to define and work with one-to-one relations in Prisma.

Referential actions

Referential actions let you define the update and delete behavior of related models on the database level

Relation mode

Manage relations between records with relation modes in Prisma

Self-relations

How to define and work with self-relations in Prisma.

Troubleshooting relations

Modelling your schema can sometimes offer up some unexpected results. This section aims to cover the most prominent of those.

Table inheritance

Learn about the use cases and patterns for table inheritance in Prisma ORM that enable usage of union types or polymorphic structures in your applicat...

Unsupported database features (Prisma Schema)

How to support database features that do not have an equivalent syntax in Prisma Schema Language

Views

How to include views in your Prisma schema

What is introspection?

Learn how you can introspect your database to generate a data model into your Prisma schema

Overview of Prisma Schema

The Prisma schema is the main method of configuration when using Prisma. It is typically called schema.prisma and contains your database connection an...

Data sources

Data sources enable Prisma to connect to your database. This page explains how to configure data sources in your Prisma schema

Generators

Generators in your Prisma schema specify what assets are generated when the command is invoked. This page explains how to configure generators

Schema location

Documentation regarding proper location of Prisma Schema including default naming and multiple files.

PostgreSQL extensions

How to install and manage PostgreSQL extensions with Prisma ORM using customized migrations, and how to use them in Prisma Client

Connection URLs

Learn about the format and syntax Prisma ORM uses for defining database connection URLs for PostgreSQL, MySQL and SQLite

Database Features

Database features supported in Prisma ORM

Environment Variables

Reference for Prisma environment variables

Error Reference

Prisma Client, Migrate, and Introspection error codes

Prisma Error Reference

Common Prisma ORM errors and how to troubleshoot them

Prisma CLI Preview features

Prisma CLI features that are currently in Preview.

Prisma Client & Prisma schema

Prisma Client and Prisma schema features that are currently in Preview

Prisma CLI reference

This page gives an overview of all available Prisma CLI commands, explains their options and shows numerous usage examples

Prisma Client API

Complete API reference for Prisma Client queries and operations

Config API

Complete reference for prisma.config.ts configuration options

Schema API

Reference for Prisma Schema Language (PSL)

Supported databases

This page lists all the databases and their versions that are supported by Prisma ORM

System requirements

System requirements for running Prisma ORM

TanStackQuery

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Overview

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Community Resources

TanStack Query Maintainers and Contributors

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

ESLint Plugin Query

TanStack Query comes with its own ESLint plugin. This plugin is used to enforce best practices and to help you avoid common mistakes.

Exhaustive dependencies for query keys

Query keys should be seen like a dependency array to your query function: Every variable that is used inside the queryFn should be added to the query ...

Ensure correct order of inference sensitive properties for infinite queries

For the following functions, the property order of the passed in object matters due to type inference:

Ensure correct order of inference-sensitive properties in useMutation()

For the following functions, the property order of the passed in object matters due to type inference:

Disallow object rest destructuring on query results

Use object rest destructuring on query results automatically subscribes to every field of the query result, which may cause unnecessary re-renders.

Disallow putting the result of query hooks directly in a React hook dependency array

The object returned from the following query hooks is not referentially stable:

Disallow returning void from query functions

Query functions must return a value that will be cached by TanStack Query. Functions that don't return a value (void functions) can lead to unexpected...

Stable Query Client

The QueryClient contains the QueryCache, so you'd only want to create one instance of the QueryClient for the lifecycle of your application - _not_ a ...

Supported TanStack Query Frameworks

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Comparison | React Query vs SWR vs Apollo vs RTK Query vs React Router

> This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be imp...

Devtools

Wave your hands in the air and shout hooray because React Query comes with dedicated devtools! 🥳

React Example: Algolia

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Auto Refetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic Graphql Request

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Chat

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Default Query Function

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Devtools Panel

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Infinite Query With Max Pages

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Load More Infinite Scroll

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs App Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs Suspense Streaming

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Offline

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Cache

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Ui

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Pagination

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Playground

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Native

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Router

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Rick Morty

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Shadow Dom

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Simple

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Star Wars

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Suspense

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

GraphQL

Because React Query's fetching mechanisms are agnostically built on Promises, you can use React Query with literally any asynchronous data fetching cl...

Advanced Server Rendering

Welcome to the Advanced Server Rendering guide, where you will learn all about using React Query with streaming, Server Components and the Next.js app...

Background Fetching Indicators

A query's state is sufficient enough to show the initial hard-loading state for a query, but sometimes you may want to display an additional indicato...

Caching Examples

> Please thoroughly read the Important Defaults before reading this guide

Default Query Function

If you find yourself wishing for whatever reason that you could just share the same query function for your entire app and just use query keys to iden...

Dependent Queries

Dependent (or serial) queries depend on previous ones to finish before they can execute. To achieve this, it's as easy as using the option to tell a ...

Disabling/Pausing Queries

If you ever want to disable a query from automatically running, you can use the option. The enabled option also accepts a callback that returns a boo...

Does TanStack Query replace Redux, MobX or other global state managers?

Well, let's start with a few important items:

Filters

Some methods within TanStack Query accept a or object.

Important Defaults

Out of the box, TanStack Query is configured with aggressive but sane defaults. Sometimes these defaults can catch new users off guard or make learnin...

Infinite Queries

Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. TanStack Quer...

Initial Query Data

There are many ways to supply initial data for a query to the cache before you need it:

Invalidations from Mutations

Invalidating queries is only half the battle. Knowing when to invalidate them is the other half. Usually when a mutation in your app succeeds, it's VE...

Migrating to React Query 3

Previous versions of React Query were awesome and brought some amazing new features, more magic, and an overall better experience to the library. They...

Migrating to React Query 4

v4 is a major version, so there are some breaking changes to be aware of:

Migrating to TanStack Query v5

v5 is a major version, so there are some breaking changes to be aware of:

Mutations

Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, TanStack Query exports a ...

Network Mode

TanStack Query provides three different network modes to distinguish how Queries and Mutations should behave if you have no network connection. This m...

Optimistic Updates

React Query provides two ways to optimistically update your UI before a mutation has completed. You can either use the option to update your cache di...

Paginated / Lagged Queries

Rendering paginated data is a very common UI pattern and in TanStack Query, it "just works" by including the page information in the query key:

Parallel Queries

"Parallel" queries are queries that are executed in parallel, or at the same time so as to maximize fetching concurrency.

Placeholder Query Data

Placeholder data allows a query to behave as if it already has data, similar to the option, but the data is not persisted to the cache. This comes in...

Prefetching & Router Integration

When you know or suspect that a certain piece of data will be needed, you can use prefetching to populate the cache with that data ahead of time, lead...

Queries

A query is a declarative dependency on an asynchronous source of data that is tied to a unique key. A query can be used with any Promise based method ...

Query Cancellation

TanStack Query provides each query function with an instance. When a query becomes out-of-date or inactive, this will become aborted. This means tha...

Query Functions

A query function can be literally any function that returns a promise. The promise that is returned should either resolve the data or throw an error.

Query Invalidation

Waiting for queries to become stale before they are fetched again doesn't always work, especially when you know for a fact that a query's data is out ...

Query Keys

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level, and can be as simple a...

Query Options

One of the best ways to share and between multiple places, yet keep them co-located to one another, is to use the helper. At runtime, this helper j...

Query Retries

When a query fails (the query function throws an error), TanStack Query will automatically retry the query if that query's request has not reached th...

Render Optimizations

React Query applies a couple of optimizations automatically to ensure that your components only re-render when they actually need to. This is done by ...

Performance & Request Waterfalls

Application performance is a broad and complex area and while React Query can't make your APIs faster, there are still things to be mindful about in h...

Scroll Restoration

Traditionally, when you navigate to a previously visited page on a web browser, you would find that the page would be scrolled to the exact position w...

Server Rendering & Hydration

In this guide you'll learn how to use React Query with server rendering.

Suspense

React Query can also be used with React's Suspense for Data Fetching APIs. For this, we have dedicated hooks:

Testing

React Query works by means of hooks - either the ones we offer or custom ones that wrap around them.

Updates from Mutation Responses

When dealing with mutations that update objects on the server, it's common for the new object to be automatically returned in the response of the muta...

Window Focus Refetching

If a user leaves your application and returns and the query data is stale, TanStack Query automatically requests fresh data for you in the background....

Installation

You can install React Query via NPM,

Overview

TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical ter...

broadcastQueryClient (Experimental)

> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at...

createAsyncStoragePersister

This utility comes as a separate package and is available under the import.

experimental_createQueryPersister

This utility comes as a separate package and is available under the import.

createSyncStoragePersister

This plugin is deprecated and will be removed in the next major version.

persistQueryClient

This is set of utilities for interacting with "persisters" which save your queryClient for later use. Different persisters can be used to store your c...

Quick Start

This code snippet very briefly illustrates the 3 core concepts of React Query:

React Native

React Query is designed to work out of the box with React Native.

hydration

creates a frozen representation of a that can later be hydrated with or . This is useful for passing prefetched queries from server to client or per...

infiniteQueryOptions

infiniteQueryOptions({

mutationOptions

You can generally pass everything to that you can also pass to .

QueryClientProvider

Use the component to connect and provide a to your application:

QueryErrorResetBoundary

When using suspense or throwOnError in your queries, you need a way to let queries know that you want to try again when re-rendering after some error ...

queryOptions

You can generally pass everything to that you can also pass to . Some options will have no effect when then forwarded to a function like , but TypeSc...

useInfiniteQuery

isFetchingPreviousPage,

useIsFetching

is an optional hook that returns the of the queries that your application is loading or fetching in the background (useful for app-wide loading indic...

useIsMutating

is an optional hook that returns the of mutations that your application is fetching (useful for app-wide loading indicators).

useMutation

useMutationState

is a hook that gives you access to all mutations in the . You can pass to it to narrow down your mutations, and to transform the mutation state.

usePrefetchInfiniteQuery

usePrefetchInfiniteQuery(options)

usePrefetchQuery

usePrefetchQuery(options)

useQueries

The hook can be used to fetch a variable number of queries:

useQuery

initialDataUpdatedAt,

useQueryClient

The hook returns the current instance.

useQueryErrorResetBoundary

This hook will reset any query errors within the closest . If there is no boundary defined it will reset them globally:

useSuspenseInfiniteQuery

const result = useSuspenseInfiniteQuery(options)

useSuspenseQueries

const result = useSuspenseQueries(options)

useSuspenseQuery

const result = useSuspenseQuery(options)

TypeScript

React Query is now written in TypeScript to make sure the library and your projects are type-safe!

TanStack Query Docs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

FocusManager

The manages the focus state within TanStack Query.

InfiniteQueryObserver

The can be used to observe and switch between infinite queries.

MutationCache

The is the storage for mutations.

NotifyManager

The handles scheduling and batching callbacks in TanStack Query.

OnlineManager

The manages the online state within TanStack Query. It can be used to change the default event listeners or to manually change the online state.

QueriesObserver

The can be used to observe multiple queries.

QueryCache

The is the storage mechanism for TanStack Query. It stores all the data, meta information and state of queries it contains.

QueryClient

The can be used to interact with a cache:

QueryObserver

The can be used to observe and switch between queries.

streamedQuery

is a helper function to create a query function that streams data from an AsyncIterable. Data will be an Array of all the chunks received. The query w...

TimeoutManager

The handles and timers in TanStack Query.

TanStackQuery

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Overview

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Community Resources

TanStack Query Maintainers and Contributors

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

ESLint Plugin Query

TanStack Query comes with its own ESLint plugin. This plugin is used to enforce best practices and to help you avoid common mistakes.

Exhaustive dependencies for query keys

Query keys should be seen like a dependency array to your query function: Every variable that is used inside the queryFn should be added to the query ...

Ensure correct order of inference sensitive properties for infinite queries

For the following functions, the property order of the passed in object matters due to type inference:

Ensure correct order of inference-sensitive properties in useMutation()

For the following functions, the property order of the passed in object matters due to type inference:

Disallow object rest destructuring on query results

Use object rest destructuring on query results automatically subscribes to every field of the query result, which may cause unnecessary re-renders.

Disallow putting the result of query hooks directly in a React hook dependency array

The object returned from the following query hooks is not referentially stable:

Disallow returning void from query functions

Query functions must return a value that will be cached by TanStack Query. Functions that don't return a value (void functions) can lead to unexpected...

Stable Query Client

The QueryClient contains the QueryCache, so you'd only want to create one instance of the QueryClient for the lifecycle of your application - _not_ a ...

Supported TanStack Query Frameworks

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

Comparison | React Query vs SWR vs Apollo vs RTK Query vs React Router

> This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be imp...

Devtools

Wave your hands in the air and shout hooray because React Query comes with dedicated devtools! 🥳

React Example: Algolia

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Auto Refetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic Graphql Request

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Chat

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Default Query Function

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Devtools Panel

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Infinite Query With Max Pages

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Load More Infinite Scroll

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs App Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs Suspense Streaming

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Offline

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Cache

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Ui

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Pagination

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Playground

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Native

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Router

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Rick Morty

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Shadow Dom

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Simple

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Star Wars

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Suspense

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

GraphQL

Because React Query's fetching mechanisms are agnostically built on Promises, you can use React Query with literally any asynchronous data fetching cl...

Advanced Server Rendering

Welcome to the Advanced Server Rendering guide, where you will learn all about using React Query with streaming, Server Components and the Next.js app...

Background Fetching Indicators

A query's state is sufficient enough to show the initial hard-loading state for a query, but sometimes you may want to display an additional indicato...

Caching Examples

> Please thoroughly read the Important Defaults before reading this guide

Default Query Function

If you find yourself wishing for whatever reason that you could just share the same query function for your entire app and just use query keys to iden...

Dependent Queries

Dependent (or serial) queries depend on previous ones to finish before they can execute. To achieve this, it's as easy as using the option to tell a ...

Disabling/Pausing Queries

If you ever want to disable a query from automatically running, you can use the option. The enabled option also accepts a callback that returns a boo...

Does TanStack Query replace Redux, MobX or other global state managers?

Well, let's start with a few important items:

Filters

Some methods within TanStack Query accept a or object.

Important Defaults

Out of the box, TanStack Query is configured with aggressive but sane defaults. Sometimes these defaults can catch new users off guard or make learnin...

Infinite Queries

Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. TanStack Quer...

Initial Query Data

There are many ways to supply initial data for a query to the cache before you need it:

Invalidations from Mutations

Invalidating queries is only half the battle. Knowing when to invalidate them is the other half. Usually when a mutation in your app succeeds, it's VE...

Migrating to React Query 3

Previous versions of React Query were awesome and brought some amazing new features, more magic, and an overall better experience to the library. They...

Migrating to React Query 4

v4 is a major version, so there are some breaking changes to be aware of:

Migrating to TanStack Query v5

v5 is a major version, so there are some breaking changes to be aware of:

Mutations

Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, TanStack Query exports a ...

Network Mode

TanStack Query provides three different network modes to distinguish how Queries and Mutations should behave if you have no network connection. This m...

Optimistic Updates

React Query provides two ways to optimistically update your UI before a mutation has completed. You can either use the option to update your cache di...

Paginated / Lagged Queries

Rendering paginated data is a very common UI pattern and in TanStack Query, it "just works" by including the page information in the query key:

Parallel Queries

"Parallel" queries are queries that are executed in parallel, or at the same time so as to maximize fetching concurrency.

Placeholder Query Data

Placeholder data allows a query to behave as if it already has data, similar to the option, but the data is not persisted to the cache. This comes in...

Prefetching & Router Integration

When you know or suspect that a certain piece of data will be needed, you can use prefetching to populate the cache with that data ahead of time, lead...

Queries

A query is a declarative dependency on an asynchronous source of data that is tied to a unique key. A query can be used with any Promise based method ...

Query Cancellation

TanStack Query provides each query function with an instance. When a query becomes out-of-date or inactive, this will become aborted. This means tha...

Query Functions

A query function can be literally any function that returns a promise. The promise that is returned should either resolve the data or throw an error.

Query Invalidation

Waiting for queries to become stale before they are fetched again doesn't always work, especially when you know for a fact that a query's data is out ...

Query Keys

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level, and can be as simple a...

Query Options

One of the best ways to share and between multiple places, yet keep them co-located to one another, is to use the helper. At runtime, this helper j...

Query Retries

When a query fails (the query function throws an error), TanStack Query will automatically retry the query if that query's request has not reached th...

Render Optimizations

React Query applies a couple of optimizations automatically to ensure that your components only re-render when they actually need to. This is done by ...

Performance & Request Waterfalls

Application performance is a broad and complex area and while React Query can't make your APIs faster, there are still things to be mindful about in h...

Scroll Restoration

Traditionally, when you navigate to a previously visited page on a web browser, you would find that the page would be scrolled to the exact position w...

Server Rendering & Hydration

In this guide you'll learn how to use React Query with server rendering.

Suspense

React Query can also be used with React's Suspense for Data Fetching APIs. For this, we have dedicated hooks:

Testing

React Query works by means of hooks - either the ones we offer or custom ones that wrap around them.

Updates from Mutation Responses

When dealing with mutations that update objects on the server, it's common for the new object to be automatically returned in the response of the muta...

Window Focus Refetching

If a user leaves your application and returns and the query data is stale, TanStack Query automatically requests fresh data for you in the background....

Installation

You can install React Query via NPM,

Overview

TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical ter...

broadcastQueryClient (Experimental)

> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at...

createAsyncStoragePersister

This utility comes as a separate package and is available under the import.

experimental_createQueryPersister

This utility comes as a separate package and is available under the import.

createSyncStoragePersister

This plugin is deprecated and will be removed in the next major version.

persistQueryClient

This is set of utilities for interacting with "persisters" which save your queryClient for later use. Different persisters can be used to store your c...

Quick Start

This code snippet very briefly illustrates the 3 core concepts of React Query:

React Native

React Query is designed to work out of the box with React Native.

hydration

creates a frozen representation of a that can later be hydrated with or . This is useful for passing prefetched queries from server to client or per...

infiniteQueryOptions

infiniteQueryOptions({

mutationOptions

You can generally pass everything to that you can also pass to .

QueryClientProvider

Use the component to connect and provide a to your application:

QueryErrorResetBoundary

When using suspense or throwOnError in your queries, you need a way to let queries know that you want to try again when re-rendering after some error ...

queryOptions

You can generally pass everything to that you can also pass to . Some options will have no effect when then forwarded to a function like , but TypeSc...

useInfiniteQuery

isFetchingPreviousPage,

useIsFetching

is an optional hook that returns the of the queries that your application is loading or fetching in the background (useful for app-wide loading indic...

useIsMutating

is an optional hook that returns the of mutations that your application is fetching (useful for app-wide loading indicators).

useMutation

useMutationState

is a hook that gives you access to all mutations in the . You can pass to it to narrow down your mutations, and to transform the mutation state.

usePrefetchInfiniteQuery

usePrefetchInfiniteQuery(options)

usePrefetchQuery

usePrefetchQuery(options)

useQueries

The hook can be used to fetch a variable number of queries:

useQuery

initialDataUpdatedAt,

useQueryClient

The hook returns the current instance.

useQueryErrorResetBoundary

This hook will reset any query errors within the closest . If there is no boundary defined it will reset them globally:

useSuspenseInfiniteQuery

const result = useSuspenseInfiniteQuery(options)

useSuspenseQueries

const result = useSuspenseQueries(options)

useSuspenseQuery

const result = useSuspenseQuery(options)

TypeScript

React Query is now written in TypeScript to make sure the library and your projects are type-safe!

TanStack Query Docs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

FocusManager

The manages the focus state within TanStack Query.

InfiniteQueryObserver

The can be used to observe and switch between infinite queries.

MutationCache

The is the storage for mutations.

NotifyManager

The handles scheduling and batching callbacks in TanStack Query.

OnlineManager

The manages the online state within TanStack Query. It can be used to change the default event listeners or to manually change the online state.

QueriesObserver

The can be used to observe multiple queries.

QueryCache

The is the storage mechanism for TanStack Query. It stores all the data, meta information and state of queries it contains.

QueryClient

The can be used to interact with a cache:

QueryObserver

The can be used to observe and switch between queries.

streamedQuery

is a helper function to create a query function that streams data from an AsyncIterable. Data will be an Array of all the chunks received. The query w...

TimeoutManager

The handles and timers in TanStack Query.

Next.js | Sentry for Next.js

Run the Sentry wizard to automatically configure Sentry in your Next.js application:

Set Up AI Agent Monitoring | Sentry for Next.js

With Sentry AI Agent Monitoring, you can monitor and debug your AI systems with full-stack context. You'll be able to track key insights like token us...

Mastra | Sentry for Next.js

This is a server-side exporter for Mastra AI tracing that uses the Node.js Sentry SDK. It requires Node.js or compatible runtimes. Requires package.

Special Use Cases | Sentry for Next.js

Learn how to configure Sentry for your Next.js application deployed on Cloudflare Workers.

Deploying on Cloudflare Workers | Sentry for Next.js

For instructions on deploying your Next.js application with Sentry on Cloudflare Workers, see the Next.js on Cloudflare guide.

Micro Frontends | Sentry for Next.js

To ensure the Sentry JavaScript SDK works with your micro frontends, make sure all micro frontends that import from a package are using the same vers...

Multiple Sentry Instances | Sentry for Next.js

Creating multiple Sentry clients is not recommended in general, as it can lead to unexpected behavior. In case you are using Micro Frontends or simila...

Offline Caching | Sentry for Next.js

If your JavaScript application is designed to continue working offline, dropping events when no connection is available and missing offline events, co...

Sentry Testkit | Sentry for Next.js

When building tests for your application, you want to assert that the right flow-tracking or error is being sent to Sentry, but without really sending...

Shared Environments / Browser Extensions | Sentry for Next.js

We recommend using JavaScript SDK and above when using the SDK with shared environments. Check out our migration docs to upgrade from an older SDK ve...

Web Workers | Sentry for Next.js

Sentry's Browser SDK supports the Web Workers API. You can use the SDK in different ways, though we recommend initializing it in the main thread to ca...

Capturing Errors | Sentry for Next.js

Sentry's Next.js SDK automatically captures most unhandled errors. However, Next.js has built-in error handling patterns that intercept errors before ...

Extended Configuration | Sentry for Next.js

Learn more about APIs of the SDK.

APIs | Sentry for Next.js

This page shows all available top-level APIs of the SDK. You can use these APIs as the primary way to:

Build Options | Sentry for Next.js

The Sentry Next.js SDK supports automatic code injection and source map upload during your app's build process using the wrapper in your Next.js conf...

Event Loop Block Detection | Sentry for Next.js

Event Loop Block detection monitors when the Node.js main thread event loop is blocked for more than a specified threshold. The Node SDK reports these...

Filtering | Sentry for Next.js

When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it'...

Integrations | Sentry for Next.js

The Sentry SDK uses integrations to hook into the functionality of popular libraries to automatically instrument your application and give you the bes...

Amqplib | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Anr | Sentry for Next.js

This integration only works in the Node.js runtime.

Anthropic | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your Anthropic client instance with . See instructions in the Browser-Si...

Breadcrumbs | Sentry for Next.js

This integration captures console logs as breadcrumbs (great for error context!). But if you need to search and query your logs across your entire app...

BrowserApiErrors | Sentry for Next.js

This integration only works inside a browser environment.

BrowserProfiling | Sentry for Next.js

This integration only works inside a browser environment.

BrowserSession | Sentry for Next.js

This integration only works inside a browser environment.

BrowserTracing | Sentry for Next.js

This integration only works inside a browser environment.

CaptureConsole | Sentry for Next.js

This integration captures all Console API calls and redirects them to Sentry using the SDK's captureMessage or captureException call, depending on the...

Child Process Integration | Sentry for Next.js

This integration only works in Node.js and requires SDK version or higher.

Console | Sentry for Next.js

This integration captures console logs as breadcrumbs (great for error context!). But if you need to search and query your logs across your entire app...

ContextLines | Sentry for Next.js

This integration adds source code from inline JavaScript of the current page's HTML (e.g. JS in tags) to stack traces of captured errors. It *can't* ...

Custom Integrations | Sentry for Next.js

In addition to the integrations that come with the SDK, you can also write custom integrations.

Dataloader | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Dedupe | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Event Loop Block | Sentry for Next.js

This integration only works in the Node.js runtime.

ExtraErrorData | Sentry for Next.js

This integration extracts all non-native attributes from the error object and attaches them to the event as extra data. If the error object has a .toJ...

Generic Feature Flags Integration | Sentry for Next.js

The Feature Flags integration allows you to manually track feature flag evaluations through an API. These evaluations are held in memory and sent to S...

FileSystem | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

FunctionToString | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Generic Pool | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

GlobalHandlers | Sentry for Next.js

This integration only works in the Browser and Deno runtimes.

Google Gen AI | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your Google Gen AI client instance with . See instructions in the Browse...

GraphQL | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

GraphQLClient | Sentry for Next.js

This integration only works inside a browser environment.

Http | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

HttpClient | Sentry for Next.js

This integration only works inside a browser environment.

HttpContext | Sentry for Next.js

This integration only works inside a browser environment.

InboundFilters | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Kafka | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Knex | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

LangChain | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually create a LangChain callback handler with . See instructions in the Browser-Si...

LangGraph | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your compiled graph with . See instructions in the Browser-Side Usage se...

LaunchDarkly | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

LinkedErrors | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

LocalVariables | Sentry for Next.js

This integration only works in the Node.js runtime.

LRU Memoizer | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

ModuleMetadata | Sentry for Next.js

This integration only works inside a browser environment.

Modules | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

MongoDB | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Mongoose | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

MySQL | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

MySQL2 | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Context | Sentry for Next.js

This integration only works in the Node.js runtime.

NodeFetch | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

NodeProfiling | Sentry for Next.js

This integration only works in the Node.js runtime.

OnUncaughtException | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

OpenAI | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your OpenAI client instance with . See instructions in the Browser-Side ...

OpenFeature | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Pino | Sentry for Next.js

This integration only works in the Node.js runtime. Requires SDK version or higher.

Postgres | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Prisma | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Prisma | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Redis | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Replay | Sentry for Next.js

This integration only works inside a browser environment.

ReplayCanvas | Sentry for Next.js

This integration only works inside a browser environment.

ReportingObserver | Sentry for Next.js

This integration only works inside a browser environment.

RequestData | Sentry for Next.js

This integration adds data from incoming requests to transaction and error events that occur during request handling done by the backend.

RewriteFrames | Sentry for Next.js

This integration allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name...

Statsig | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Supabase | Sentry for Next.js

The adds instrumentation for the Supabase client to capture spans for both authentication and database operations.

Tedious | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

trpcMiddleware | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

OnUnhandledRejection | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

Unleash | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Vercel AI | Sentry for Next.js

Requires SDK version or higher for Node.js, Cloudflare Workers, Vercel Edge Functions and Bun. Requires SDK version or higher for Deno.

WebWorker | Sentry for Next.js

This integration, together with , establishes communication between the browser's main thread and one or more WebWorkers. It listens to worker message...

WinterCGFetch | Sentry for Next.js

This integration only works in the Edge runtime.

ZodErrors | Sentry for Next.js

The Zod Errors integration enhances error reporting for applications using Zod schema validation. When Zod validation fails, this integration captures...

Options | Sentry for Next.js

The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. Learn more about DSN utilization.

Releases & Health | Sentry for Next.js

A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you can:

Transports | Sentry for Next.js

The JavaScript SDK uses a to send events to Sentry. On modern browsers, most transports use the browsers' API to send events. Transports will drop a...

Tree Shaking | Sentry for Next.js

The Sentry Next.js SDK supports tree shaking for webpack builds with some additional configurations.

Set Up Crons | Sentry for Next.js

Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.

Troubleshooting | Sentry for Next.js

Why aren't recurring job errors showing up on my monitor details page?

Data Management | Sentry for Next.js

See what data is collected by the Sentry SDK.

Data Collected | Sentry for Next.js

Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identif...

Scrubbing Sensitive Data | Sentry for Next.js

As with any third-party service it's important to understand what data is being sent to Sentry, and where relevant ensure sensitive data either never ...

Enriching Events | Sentry for Next.js

In addition to the data that the Sentry SDK automatically captures, you can add additional data to events to help you debug them.

Attachments | Sentry for Next.js

Sentry can enrich your events for further investigation by storing additional files, such as config or log files, as attachments.

Breadcrumbs | Sentry for Next.js

Manual breadcrumbs had a good run, but Sentry's got logs. Structured, searchable, and way easier to alert or query on. Check them out!

Event Processors | Sentry for Next.js

You can enrich events with additional data by adding your own event processors, either on the scope level or globally. Though event processors are sim...

Event Fingerprinting | Sentry for Next.js

All events have a fingerprint. Events with the same fingerprint are grouped together into an issue.

Event Level | Sentry for Next.js

The level - similar to logging levels - is generally added by default by the SDK. You can either provide a dedicated level directly in , or configure ...

Request Isolation | Sentry for Next.js

In server-side environments, the isolation scope automatically forks around request boundaries. This is done automatically by the SDK. As a result, ea...

Scopes | Sentry for Next.js

When an event is captured and sent to Sentry, SDKs will merge that event data with extra information from the current scope. SDKs will typically autom...

Tags | Sentry for Next.js

We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the numb...

Set Up Feature Flags | Sentry for Next.js

If you use a third-party SDK to evaluate feature flags, you can enable a Sentry SDK integration to track those evaluations. Integrations are provider ...

Set Up Logs | Sentry for Next.js

Sentry Logs let you send structured log data from your Next.js application. Unlike traditional string-based logging, structured logs include queryable...

Manual Setup | Sentry for Next.js

For the fastest setup, we recommend using the wizard installer.

Pages Router Setup | Sentry for Next.js

For the fastest setup, we recommend using the wizard installer.

Webpack Setup | Sentry for Next.js

This guide covers the configuration differences for Next.js applications using Webpack (the default bundler before Next.js 15). Complete the main manu...

Set Up Metrics | Sentry for Next.js

With Sentry Metrics, you can send counters, gauges, and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed al...

Migration Guide | Sentry for Next.js

Here's a list of guides on migrating to a newer version of the Sentry JavaScript SDK.

Migrate from 4.x to 5.x/6.x | Sentry for Next.js

We recommend upgrading from to directly. Migrating from to has no breaking changes to the SDK's API.

Migrate from 6.x to 7.x | Sentry for Next.js

The v7 version of the JavaScript SDK requires a self-hosted version of Sentry or higher.

Migrate from 7.x to 8.x | Sentry for Next.js

The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This version is breaking because we remov...

Deprecations in 7.x | Sentry for Next.js

To fix most of the deprecations on , you can use the codemod to automatically update your SDK usage. requires Node 18+.

New Tracing APIs | Sentry for Next.js

The SDK release introduces new APIs for performance monitoring. These APIs are designed to provide more control over how performance data is collecte...

Migrate from 8.x to 9.x | Sentry for Next.js

Version 9 of the Sentry JavaScript SDK primarily introduces API cleanup and version support changes.

Migrate from 9.x to 10.x | Sentry for Next.js

Version 10 of the Sentry JavaScript SDK primarily focuses on upgrading underlying OpenTelemetry dependencies to v2 with minimal breaking changes.

OpenTelemetry Support | Sentry for Next.js

The Sentry SDK uses OpenTelemetry under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up b...

Using Your Existing OpenTelemetry Setup | Sentry for Next.js

Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry...

Using OpenTelemetry APIs | Sentry for Next.js

Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any span...

Next.js | Sentry for Next.js

Run the Sentry wizard to automatically configure Sentry in your Next.js application:

Set Up AI Agent Monitoring | Sentry for Next.js

With Sentry AI Agent Monitoring, you can monitor and debug your AI systems with full-stack context. You'll be able to track key insights like token us...

Mastra | Sentry for Next.js

This is a server-side exporter for Mastra AI tracing that uses the Node.js Sentry SDK. It requires Node.js or compatible runtimes. Requires package.

Special Use Cases | Sentry for Next.js

Learn how to configure Sentry for your Next.js application deployed on Cloudflare Workers.

Deploying on Cloudflare Workers | Sentry for Next.js

For instructions on deploying your Next.js application with Sentry on Cloudflare Workers, see the Next.js on Cloudflare guide.

Micro Frontends | Sentry for Next.js

To ensure the Sentry JavaScript SDK works with your micro frontends, make sure all micro frontends that import from a package are using the same vers...

Multiple Sentry Instances | Sentry for Next.js

Creating multiple Sentry clients is not recommended in general, as it can lead to unexpected behavior. In case you are using Micro Frontends or simila...

Offline Caching | Sentry for Next.js

If your JavaScript application is designed to continue working offline, dropping events when no connection is available and missing offline events, co...

Sentry Testkit | Sentry for Next.js

When building tests for your application, you want to assert that the right flow-tracking or error is being sent to Sentry, but without really sending...

Shared Environments / Browser Extensions | Sentry for Next.js

We recommend using JavaScript SDK and above when using the SDK with shared environments. Check out our migration docs to upgrade from an older SDK ve...

Web Workers | Sentry for Next.js

Sentry's Browser SDK supports the Web Workers API. You can use the SDK in different ways, though we recommend initializing it in the main thread to ca...

Capturing Errors | Sentry for Next.js

Sentry's Next.js SDK automatically captures most unhandled errors. However, Next.js has built-in error handling patterns that intercept errors before ...

Extended Configuration | Sentry for Next.js

Learn more about APIs of the SDK.

APIs | Sentry for Next.js

This page shows all available top-level APIs of the SDK. You can use these APIs as the primary way to:

Build Options | Sentry for Next.js

The Sentry Next.js SDK supports automatic code injection and source map upload during your app's build process using the wrapper in your Next.js conf...

Event Loop Block Detection | Sentry for Next.js

Event Loop Block detection monitors when the Node.js main thread event loop is blocked for more than a specified threshold. The Node SDK reports these...

Filtering | Sentry for Next.js

When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it'...

Integrations | Sentry for Next.js

The Sentry SDK uses integrations to hook into the functionality of popular libraries to automatically instrument your application and give you the bes...

Amqplib | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Anr | Sentry for Next.js

This integration only works in the Node.js runtime.

Anthropic | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your Anthropic client instance with . See instructions in the Browser-Si...

Breadcrumbs | Sentry for Next.js

This integration captures console logs as breadcrumbs (great for error context!). But if you need to search and query your logs across your entire app...

BrowserApiErrors | Sentry for Next.js

This integration only works inside a browser environment.

BrowserProfiling | Sentry for Next.js

This integration only works inside a browser environment.

BrowserSession | Sentry for Next.js

This integration only works inside a browser environment.

BrowserTracing | Sentry for Next.js

This integration only works inside a browser environment.

CaptureConsole | Sentry for Next.js

This integration captures all Console API calls and redirects them to Sentry using the SDK's captureMessage or captureException call, depending on the...

Child Process Integration | Sentry for Next.js

This integration only works in Node.js and requires SDK version or higher.

Console | Sentry for Next.js

This integration captures console logs as breadcrumbs (great for error context!). But if you need to search and query your logs across your entire app...

ContextLines | Sentry for Next.js

This integration adds source code from inline JavaScript of the current page's HTML (e.g. JS in tags) to stack traces of captured errors. It *can't* ...

Custom Integrations | Sentry for Next.js

In addition to the integrations that come with the SDK, you can also write custom integrations.

Dataloader | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Dedupe | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Event Loop Block | Sentry for Next.js

This integration only works in the Node.js runtime.

ExtraErrorData | Sentry for Next.js

This integration extracts all non-native attributes from the error object and attaches them to the event as extra data. If the error object has a .toJ...

Generic Feature Flags Integration | Sentry for Next.js

The Feature Flags integration allows you to manually track feature flag evaluations through an API. These evaluations are held in memory and sent to S...

FileSystem | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

FunctionToString | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Generic Pool | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

GlobalHandlers | Sentry for Next.js

This integration only works in the Browser and Deno runtimes.

Google Gen AI | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your Google Gen AI client instance with . See instructions in the Browse...

GraphQL | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

GraphQLClient | Sentry for Next.js

This integration only works inside a browser environment.

Http | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

HttpClient | Sentry for Next.js

This integration only works inside a browser environment.

HttpContext | Sentry for Next.js

This integration only works inside a browser environment.

InboundFilters | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

Kafka | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

Knex | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

LangChain | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually create a LangChain callback handler with . See instructions in the Browser-Si...

LangGraph | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your compiled graph with . See instructions in the Browser-Side Usage se...

LaunchDarkly | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

LinkedErrors | Sentry for Next.js

This integration is enabled by default. If you'd like to modify your default integrations, read this.

LocalVariables | Sentry for Next.js

This integration only works in the Node.js runtime.

LRU Memoizer | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

ModuleMetadata | Sentry for Next.js

This integration only works inside a browser environment.

Modules | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

MongoDB | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Mongoose | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

MySQL | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

MySQL2 | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Context | Sentry for Next.js

This integration only works in the Node.js runtime.

NodeFetch | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

NodeProfiling | Sentry for Next.js

This integration only works in the Node.js runtime.

OnUncaughtException | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

OpenAI | Sentry for Next.js

For meta-framework applications using all runtimes, you need to manually wrap your OpenAI client instance with . See instructions in the Browser-Side ...

OpenFeature | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Pino | Sentry for Next.js

This integration only works in the Node.js runtime. Requires SDK version or higher.

Postgres | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Prisma | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Prisma | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Redis | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes.

Replay | Sentry for Next.js

This integration only works inside a browser environment.

ReplayCanvas | Sentry for Next.js

This integration only works inside a browser environment.

ReportingObserver | Sentry for Next.js

This integration only works inside a browser environment.

RequestData | Sentry for Next.js

This integration adds data from incoming requests to transaction and error events that occur during request handling done by the backend.

RewriteFrames | Sentry for Next.js

This integration allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name...

Statsig | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Supabase | Sentry for Next.js

The adds instrumentation for the Supabase client to capture spans for both authentication and database operations.

Tedious | Sentry for Next.js

This integration only works in the Node.js and Bun runtimes. Requires SDK version or higher.

trpcMiddleware | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

OnUnhandledRejection | Sentry for Next.js

This integration only works inside server environments (Node.js, Bun, Deno).

Unleash | Sentry for Next.js

This integration only works inside a browser environment. It is only available from a package-based install (e.g. or ).

Vercel AI | Sentry for Next.js

Requires SDK version or higher for Node.js, Cloudflare Workers, Vercel Edge Functions and Bun. Requires SDK version or higher for Deno.

WebWorker | Sentry for Next.js

This integration, together with , establishes communication between the browser's main thread and one or more WebWorkers. It listens to worker message...

WinterCGFetch | Sentry for Next.js

This integration only works in the Edge runtime.

ZodErrors | Sentry for Next.js

The Zod Errors integration enhances error reporting for applications using Zod schema validation. When Zod validation fails, this integration captures...

Options | Sentry for Next.js

The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. Learn more about DSN utilization.

Releases & Health | Sentry for Next.js

A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you can:

Transports | Sentry for Next.js

The JavaScript SDK uses a to send events to Sentry. On modern browsers, most transports use the browsers' API to send events. Transports will drop a...

Tree Shaking | Sentry for Next.js

The Sentry Next.js SDK supports tree shaking for webpack builds with some additional configurations.

Set Up Crons | Sentry for Next.js

Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.

Troubleshooting | Sentry for Next.js

Why aren't recurring job errors showing up on my monitor details page?

Data Management | Sentry for Next.js

See what data is collected by the Sentry SDK.

Data Collected | Sentry for Next.js

Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identif...

Scrubbing Sensitive Data | Sentry for Next.js

As with any third-party service it's important to understand what data is being sent to Sentry, and where relevant ensure sensitive data either never ...

Enriching Events | Sentry for Next.js

In addition to the data that the Sentry SDK automatically captures, you can add additional data to events to help you debug them.

Attachments | Sentry for Next.js

Sentry can enrich your events for further investigation by storing additional files, such as config or log files, as attachments.

Breadcrumbs | Sentry for Next.js

Manual breadcrumbs had a good run, but Sentry's got logs. Structured, searchable, and way easier to alert or query on. Check them out!

Event Processors | Sentry for Next.js

You can enrich events with additional data by adding your own event processors, either on the scope level or globally. Though event processors are sim...

Event Fingerprinting | Sentry for Next.js

All events have a fingerprint. Events with the same fingerprint are grouped together into an issue.

Event Level | Sentry for Next.js

The level - similar to logging levels - is generally added by default by the SDK. You can either provide a dedicated level directly in , or configure ...

Request Isolation | Sentry for Next.js

In server-side environments, the isolation scope automatically forks around request boundaries. This is done automatically by the SDK. As a result, ea...

Scopes | Sentry for Next.js

When an event is captured and sent to Sentry, SDKs will merge that event data with extra information from the current scope. SDKs will typically autom...

Tags | Sentry for Next.js

We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the numb...

Set Up Feature Flags | Sentry for Next.js

If you use a third-party SDK to evaluate feature flags, you can enable a Sentry SDK integration to track those evaluations. Integrations are provider ...

Set Up Logs | Sentry for Next.js

Sentry Logs let you send structured log data from your Next.js application. Unlike traditional string-based logging, structured logs include queryable...

Manual Setup | Sentry for Next.js

For the fastest setup, we recommend using the wizard installer.

Pages Router Setup | Sentry for Next.js

For the fastest setup, we recommend using the wizard installer.

Webpack Setup | Sentry for Next.js

This guide covers the configuration differences for Next.js applications using Webpack (the default bundler before Next.js 15). Complete the main manu...

Set Up Metrics | Sentry for Next.js

With Sentry Metrics, you can send counters, gauges, and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed al...

Migration Guide | Sentry for Next.js

Here's a list of guides on migrating to a newer version of the Sentry JavaScript SDK.

Migrate from 4.x to 5.x/6.x | Sentry for Next.js

We recommend upgrading from to directly. Migrating from to has no breaking changes to the SDK's API.

Migrate from 6.x to 7.x | Sentry for Next.js

The v7 version of the JavaScript SDK requires a self-hosted version of Sentry or higher.

Migrate from 7.x to 8.x | Sentry for Next.js

The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This version is breaking because we remov...

Deprecations in 7.x | Sentry for Next.js

To fix most of the deprecations on , you can use the codemod to automatically update your SDK usage. requires Node 18+.

New Tracing APIs | Sentry for Next.js

The SDK release introduces new APIs for performance monitoring. These APIs are designed to provide more control over how performance data is collecte...

Migrate from 8.x to 9.x | Sentry for Next.js

Version 9 of the Sentry JavaScript SDK primarily introduces API cleanup and version support changes.

Migrate from 9.x to 10.x | Sentry for Next.js

Version 10 of the Sentry JavaScript SDK primarily focuses on upgrading underlying OpenTelemetry dependencies to v2 with minimal breaking changes.

OpenTelemetry Support | Sentry for Next.js

The Sentry SDK uses OpenTelemetry under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up b...

Using Your Existing OpenTelemetry Setup | Sentry for Next.js

Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry...

Using OpenTelemetry APIs | Sentry for Next.js

Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any span...

Set Up Profiling | Sentry for Next.js

Get started with Browser profiling to understand your application's performance.

Browser Profiling | Sentry for Next.js

Browser Profiling is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony.

Node Profiling | Sentry for Next.js

By default, Sentry error events will not get trace context unless you configure the scope with the transaction, as illustrated in the example below.

Sampling | Sentry for Next.js

Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of inf...

Set Up Security Policy Reporting | Sentry for Next.js

Sentry provides the ability to collect information on Content-Security-Policy (CSP) violations by setting the proper HTTP header which results in the ...

Set Up Session Replay | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Configuration | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Replay Issues | Sentry for Next.js

A *replay issue* is an issue detected using captured Session Replay data. If your application is configured with Session Replay, problems will be dete...

Privacy | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Troubleshooting | Sentry for Next.js

Replay doesn't match my application

Understanding Sessions | Sentry for Next.js

In most cases, setting the Replay sample rates will be all you need to do to begin capturing recording data you care about. For more complex cases, it...

Source Maps | Sentry for Next.js

Source maps translate minified production code back to your original source, giving you readable stack traces instead of cryptic line numbers.

Troubleshooting Source Maps | Sentry for Next.js

If you previously set up source maps, we suggest updating your tools (SDK, bundler plugins, Sentry CLI). It is generally easier to upgrade to the late...

What are Debug IDs | Sentry for Next.js

This documentation provides an in-depth look at Debug IDs, explaining how they work and why Sentry recommends using them. Visit Uploading Source Maps ...

Legacy Uploading Methods | Sentry for Next.js

Sentry moved to a new process for handling source maps. We call this process "source mapping with debug IDs".

esbuild | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Ionic Capacitor Build | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

Ionic | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

Rollup | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

SystemJS | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for SystemJS using our tool.

TypeScript (tsc) | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

UglifyJS | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for SystemJS using our tool.

Vite | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Webpack | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Set Up Tracing | Sentry for Next.js

Tracing captures the timing and flow of requests through your Next.js application. Learn more about tracing and how Sentry uses traces to track perfor...

Configure Sampling | Sentry for Next.js

Sentry's tracing functionality helps you monitor application performance by capturing distributed traces, attaching attributes, and span performance a...

Set Up Distributed Tracing | Sentry for Next.js

Distributed tracing connects and records the path of requests as they travel through the different tiers of your application architecture. If your arc...

Custom Trace Propagation | Sentry for Next.js

On this page you will learn how to manually propagate trace information into and out of your JavaScript application.

Dealing with CORS Issues | Sentry for Next.js

If your frontend and backend are hosted on different domains (for example, your frontend is on and your backend is on ), you need to configure your b...

Instrumentation | Sentry for Next.js

To capture transactions and spans customized to your organization's needs, you must first set up tracing.

Automatic Instrumentation | Sentry for Next.js

Capturing spans requires that you first set up tracing in your app if you haven't already.

Instrument Caches | Sentry for Next.js

A cache can be used to speed up data retrieval, thereby improving application performance. Because instead of getting data from a potentially slow dat...

Instrument MCP Servers | Sentry for Next.js

With Sentry's MCP monitoring, you can track and debug MCP servers with full-stack context. You'll be able to monitor tool executions, prompt retrieval...

Instrument Queues | Sentry for Next.js

To ensure that you have performance data about your messaging queues, you'll need to instrument custom spans and transactions around your queue produc...

Instrument HTTP Requests | Sentry for Next.js

As a prerequisite to setting up Requests, you'll need to first set up tracing. Once this is done, the JavaScript SDK will automatically instrument out...

Sending Span Metrics | Sentry for Next.js

To use span metrics, you must first configure tracing in your application.

Example Instrumentation | Sentry for Next.js

The sample code on this page is for demonstration purposes only. It isn’t production-ready and may not apply directly to your language or framework.

Troubleshooting | Sentry for Next.js

If you need help managing transactions, you can read more here. If you need additional help, you can ask on GitHub. Customers on a paid plan may also ...

Troubleshooting | Sentry for Next.js

The SDK is not sending any data

Supported Browsers | Sentry for Next.js

Sentry's latest JavaScript SDKs require ES2020 compatibility. The minimum supported browser versions are:

Set Up User Feedback | Sentry for Next.js

The User Feedback feature allows you to collect user feedback from anywhere inside your application at any time, without needing an error event to occ...

Configuration | Sentry for Next.js

In version 7 of our JavaScript SDK, User Feedback was released as a Beta integration. We recommend following the migration guide and updating your SDK...

Configuration | Sentry for Next.js

The User Feedback Widget offers many customization options, and if the available options are insufficient, you can use your own UI.

Set Up Profiling | Sentry for Next.js

Get started with Browser profiling to understand your application's performance.

Browser Profiling | Sentry for Next.js

Browser Profiling is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony.

Node Profiling | Sentry for Next.js

By default, Sentry error events will not get trace context unless you configure the scope with the transaction, as illustrated in the example below.

Sampling | Sentry for Next.js

Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of inf...

Set Up Security Policy Reporting | Sentry for Next.js

Sentry provides the ability to collect information on Content-Security-Policy (CSP) violations by setting the proper HTTP header which results in the ...

Set Up Session Replay | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Configuration | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Replay Issues | Sentry for Next.js

A *replay issue* is an issue detected using captured Session Replay data. If your application is configured with Session Replay, problems will be dete...

Privacy | Sentry for Next.js

If you have any questions, feedback or would like to report a bug, please open a GitHub issue with a link to a relevant replay or, if possible, a publ...

Troubleshooting | Sentry for Next.js

Replay doesn't match my application

Understanding Sessions | Sentry for Next.js

In most cases, setting the Replay sample rates will be all you need to do to begin capturing recording data you care about. For more complex cases, it...

Source Maps | Sentry for Next.js

Source maps translate minified production code back to your original source, giving you readable stack traces instead of cryptic line numbers.

Troubleshooting Source Maps | Sentry for Next.js

If you previously set up source maps, we suggest updating your tools (SDK, bundler plugins, Sentry CLI). It is generally easier to upgrade to the late...

What are Debug IDs | Sentry for Next.js

This documentation provides an in-depth look at Debug IDs, explaining how they work and why Sentry recommends using them. Visit Uploading Source Maps ...

Legacy Uploading Methods | Sentry for Next.js

Sentry moved to a new process for handling source maps. We call this process "source mapping with debug IDs".

esbuild | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Ionic Capacitor Build | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

Ionic | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

Rollup | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

SystemJS | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for SystemJS using our tool.

TypeScript (tsc) | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for TypeScript using our tool.

UglifyJS | Sentry for Next.js

In this guide, you'll learn how to successfully upload source maps for SystemJS using our tool.

Vite | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Webpack | Sentry for Next.js

This guide assumes you're using a Sentry SDK version or higher. If you're on an older version and you want to upload source maps, we recommend upgrad...

Set Up Tracing | Sentry for Next.js

Tracing captures the timing and flow of requests through your Next.js application. Learn more about tracing and how Sentry uses traces to track perfor...

Configure Sampling | Sentry for Next.js

Sentry's tracing functionality helps you monitor application performance by capturing distributed traces, attaching attributes, and span performance a...

Set Up Distributed Tracing | Sentry for Next.js

Distributed tracing connects and records the path of requests as they travel through the different tiers of your application architecture. If your arc...

Custom Trace Propagation | Sentry for Next.js

On this page you will learn how to manually propagate trace information into and out of your JavaScript application.

Dealing with CORS Issues | Sentry for Next.js

If your frontend and backend are hosted on different domains (for example, your frontend is on and your backend is on ), you need to configure your b...

Instrumentation | Sentry for Next.js

To capture transactions and spans customized to your organization's needs, you must first set up tracing.

Automatic Instrumentation | Sentry for Next.js

Capturing spans requires that you first set up tracing in your app if you haven't already.

Instrument Caches | Sentry for Next.js

A cache can be used to speed up data retrieval, thereby improving application performance. Because instead of getting data from a potentially slow dat...

Instrument MCP Servers | Sentry for Next.js

With Sentry's MCP monitoring, you can track and debug MCP servers with full-stack context. You'll be able to monitor tool executions, prompt retrieval...

Instrument Queues | Sentry for Next.js

To ensure that you have performance data about your messaging queues, you'll need to instrument custom spans and transactions around your queue produc...

Instrument HTTP Requests | Sentry for Next.js

As a prerequisite to setting up Requests, you'll need to first set up tracing. Once this is done, the JavaScript SDK will automatically instrument out...

Sending Span Metrics | Sentry for Next.js

To use span metrics, you must first configure tracing in your application.

Example Instrumentation | Sentry for Next.js

The sample code on this page is for demonstration purposes only. It isn’t production-ready and may not apply directly to your language or framework.

Troubleshooting | Sentry for Next.js

If you need help managing transactions, you can read more here. If you need additional help, you can ask on GitHub. Customers on a paid plan may also ...

Troubleshooting | Sentry for Next.js

The SDK is not sending any data

Supported Browsers | Sentry for Next.js

Sentry's latest JavaScript SDKs require ES2020 compatibility. The minimum supported browser versions are:

Set Up User Feedback | Sentry for Next.js

The User Feedback feature allows you to collect user feedback from anywhere inside your application at any time, without needing an error event to occ...

Configuration | Sentry for Next.js

In version 7 of our JavaScript SDK, User Feedback was released as a Beta integration. We recommend following the migration guide and updating your SDK...

Configuration | Sentry for Next.js

The User Feedback Widget offers many customization options, and if the available options are insufficient, you can use your own UI.

Featured sponsor: Jazz

TypeScript-first schema validation with static type inference

Defining schemas

To validate data, you must first define a _schema_. Schemas represent _types_ , from simple primitive values to complex nested objects and arrays.

Basic usage

This page will walk you through the basics of creating schemas, parsing data, and using inferred types. For complete documentation on Zod's schema API...

Codecs

✨ New — Introduced in

Ecosystem

There are a growing number of tools that are built atop or support Zod natively! If you've built a tool or library on top of Zod, let me know on Twitt...

Customizing errors

In Zod, validation errors are surfaced as instances of the class.

Formatting errors

Zod emphasizes _completeness_ and _correctness_ in its error reporting. In many cases, it's helpful to convert the to a more useful format. Zod provi...

JSON Schema

Zod provides to convert a JSON Schema into a Zod schema.

For library authors

Update — July 10th, 2025

Zod llms.txt

Zod documentation index in llms.txt format.

Metadata and registries

It's often useful to associate a schema with some additional _metadata_ for documentation, code generation, AI structured outputs, form validation, an...

Zod Core

This sub-package exports the core classes and utilities that are consumed by Zod and Zod Mini. It is not intended to be used directly; instead it's de...

Zod Mini

Zod Mini variant was introduced with the release of Zod 4. To try it:

Zod

Overview of the zod/v4 package and its role in the Zod ecosystem.

Release notes

After a year of active development: Zod 4 is now stable! It's faster, slimmer, more -efficient, and implements some long-requested features.

Migration guide

This migration guide aims to list the breaking changes in Zod 4 in order of highest to lowest impact. To learn more about the performance enhancements...

dev-docs

최신 개발 문서를 한국어와 영어로 정리한 개발자 문서 허브

NextAuth.js

Google, Facebook, Auth0, Apple 같은 인기 서비스에 대한 기본 지원을 제공합니다.

index

최신 문서는 authjs.dev 페이지를 방문하세요.

Callbacks

Callbacks는 작업이 수행될 때 어떤 일이 일어나는지 제어할 수 있는 비동기 함수입니다.

데이터베이스

NextAuth.js는 여러 데이터베이스 어댑터를 제공합니다. 개요를 확인하세요.

이벤트[](https://next-auth.js.org/configuration/events#events "Direct link to heading")

원본 URL: https://next-auth.js.org/configuration/events

간단한 초기화[](https://next-auth.js.org/configuration/initialization#simple-initialization "Direct link to heading")

NextAuth.js의 주요 진입점은 에서 import하는 메서드입니다. 이 메서드는 REST API 섹션에 정의된 대로 다양한 유형의 요청을 처리합니다.

Next.js

를 여기저기 전달하지 않아도 되도록 헬퍼 함수를 만들 수 있습니다:

환경 변수[](https://next-auth.js.org/configuration/options#environment-variables "Direct link to heading")

프로덕션에 배포할 때는 환경 변수를 사이트의 정식 URL로 설정하세요.

오류 코드[](https://next-auth.js.org/configuration/pages#error-codes "Direct link to heading")

NextAuth.js는 로그인, 로그아웃, 이메일 인증 처리 및 오류 메시지 표시를 위한 단순하고 브랜드가 적용되지 않은 인증 페이지를 자동으로 생성합니다.

Credentials

Credentials provider를 사용하면 사용자 이름과 비밀번호, 2단계 인증, 하드웨어 장치(예: YubiKey U2F / FIDO) 같은 임의의 자격 증명으로 로그인 처리를 할 수 있습니다.

Email

Email provider는 사용자가 클릭해 로그인할 수 있는 이메일 "매직 링크"를 전송합니다. Slack 같은 소프트웨어를 사용해 봤다면 이미 보셨을 가능성이 큽니다.

OAuth

NextAuth.js는 어떤 OAuth 서비스와도 동작하도록 설계되었습니다. OAuth 1.0, 1.0A, 2.0, OpenID Connect를 지원하며, 가장 널리 쓰이는 로그인 서비스 대부분을 기본 지원합니다.

코어 팀[](https://next-auth.js.org/contributors#core-team)

Auth.js를 오픈 소스 프로젝트로 유지하는 일은 매우 어려운 작업입니다. 코어 팀원 모두 각자의 본업이 있으며, 이 라이브러리는 우리의 여가 시간에 선의로 유지·개발되고 있습니다. 후원은 코어 팀이 궁극적으로 Auth.js에 전업으로 참여해 더 많은 기능과 더 나은...

Vercel[](https://next-auth.js.org/deployment#vercel "Direct link to heading")

NextAuth.js를 배포하는 데는 몇 가지 단계만 필요합니다. Next.js 애플리케이션이 실행될 수 있는 곳이라면 어디서든 실행할 수 있습니다. 따라서 데이터베이스 없이 JWT 세션 전략만 사용하는 기본 구성에서는, 애플리케이션 외에 다음 몇 가지만 있으면 됩니다...

Errors

다음은 NextAuth.js에서 출력되는 오류 목록입니다.

자주 묻는 질문

원본 URL: https://next-auth.js.org/faq

클라이언트 API

NextAuth.js 클라이언트 라이브러리를 사용하면 React 애플리케이션에서 세션과 쉽게 상호작용할 수 있습니다.

시작하기

아래 예제 코드는 Next.js 앱에 인증을 추가하는 방법을 설명합니다.

NextAuth.js 소개[](https://next-auth.js.org/getting-started/introduction#about-nextauthjs "Direct link to heading")

NextAuth.js는 Next.js 애플리케이션을 위한 완전한 오픈 소스 인증 솔루션입니다.

REST API

NextAuth.js는 NextAuth.js 클라이언트에서 사용하는 REST API를 제공합니다.

TypeScript

NextAuth.js는 TypeScript 프로젝트에서 안전하게 사용할 수 있도록 자체 타입 정의를 제공합니다. TypeScript를 사용하지 않더라도 VSCode 같은 IDE가 이를 인식해 더 나은 개발자 경험을 제공합니다. 타이핑하는 동안 특정 객체/함수의 형태에 ...

업그레이드 가이드 (v4)

원본 URL: https://next-auth.js.org/getting-started/upgrade-v4

index

내부 가이드는 난이도별로 세 가지 수준으로 제공됩니다.

[페이지 및 API 라우트 보안](https://next-auth.js.org/tutorials/securing-pages-and-api-routes)[](https://next-auth.js.org/guides/basics#securing-pages-and-api-routes "Direct link to heading")

원본 URL: https://next-auth.js.org/guides/basics

[Refresh Token Rotation](https://authjs.dev/guides/refresh-token-rotation)[](https://next-auth.js.org/guides/fullstack#refresh-token-rotation "Direct link to heading")

[Cypress로 테스트하기](https://next-auth.js.org/tutorials/testing-with-cypress)[](https://next-auth.js.org/guides/testing#testing-with-cypress "헤딩으로 바로 가는 링크")

index

사용자가 로그인할 수 있는 방법은 네 가지입니다.

42 School

원본 URL: https://next-auth.js.org/providers/42-school

Apple

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Atlassian

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Auth0

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Authentik

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Azure Active Directory B2C

Azure AD B2C는 에서 다음 필드를 반환합니다:

Azure Active Directory

원본 URL: https://next-auth.js.org/providers/azure-ad

Battle.net

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

문서[](https://next-auth.js.org/providers/box#documentation "헤딩으로 직접 연결되는 링크")

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

BoxyHQ SAML

BoxyHQ SAML은 SAML 로그인 흐름을 OAuth 2.0 흐름으로 처리하여 SAML 프로토콜의 모든 복잡성을 추상화해 주는 오픈 소스 서비스입니다.

Bungie

원하는 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Amazon Cognito

원본 URL: https://next-auth.js.org/providers/cognito

Coinbase

원본 URL: https://next-auth.js.org/providers/coinbase

Credentials

Credentials provider를 사용하면 사용자 이름과 비밀번호, 도메인, 또는 2단계 인증이나 하드웨어 디바이스(예: YubiKey U2F / FIDO) 같은 임의의 자격 증명으로 로그인 처리를 할 수 있습니다.

Discord

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Dropbox

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

DuendeIdentityServer6

원하는 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

개요[](https://next-auth.js.org/providers/email#overview "Direct link to heading")

Email provider는 로그인에 사용할 수 있는 "magic links"를 이메일로 전송하며, Slack 같은 서비스를 사용해 봤다면 아마 본 적이 있을 것입니다.

EVE Online

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Facebook

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

FACEIT

기본 정보(email, nickname, guid, avatar)를 얻기 위한 Scopes: , ,

Foursquare

Foursquare는 추가로 형식의 파라미터를 요구하며, 이는 본질적으로 "이 날짜까지의 API 변경 사항에 대비되어 있다"는 의미입니다.

Freshbooks

Freshbooks Provider에는 기본 옵션 세트가 포함되어 있습니다.

FusionAuth

원본 URL: https://next-auth.js.org/providers/fusionauth

GitHub

GitHub는 에 숫자형 필드인 를 반환합니다. 자세한 내용은 docs를 참고하세요. Adapter를 사용하는 경우를 대비해, 이 필드를 데이터베이스 스키마에 추가하는 것을 잊지 마세요.

GitLab

GitLab은 에 이라는 필드를 반환하며, 이 값은 숫자입니다. 자세한 내용은 해당 문서를 참고하세요. Adapter를 사용 중이라면, 데이터베이스 스키마에 이 필드를 optional로 추가하는 것을 잊지 마세요.

Google

자격 증명을 생성할 때 사용하는 "Authorized redirect URIs"에는 전체 도메인이 포함되어야 하며 콜백 경로로 끝나야 합니다. 예를 들어:

HubSpot

원본 URL: https://next-auth.js.org/providers/hubspot

IdentityServer4

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Instagram

원본 URL: https://next-auth.js.org/providers/instagram

Kakao

원본 URL: https://next-auth.js.org/providers/kakao

Keycloak

Keycloak에서 "Access Type"을 "confidential"로 설정해 openid-connect 클라이언트를 생성하세요.

LINE

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Auth 탭에서 client ID와 client secret을 확인하세요. 같은 탭에서 http://localhost:3000/api/auth/callback/linkedin 같은 redirect URL을 추가해 LinkedIn이 애플리케이션으로 올바르게 다시 리디렉션...

Mailchimp

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Mail.ru

사용 사례에 맞게 옵션을 원하는 대로 재정의할 수 있습니다.

Medium

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Naver

원본 URL: https://next-auth.js.org/providers/naver

Netlify

자체 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Okta

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

OneLogin

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Osso

Osso는 Identity Provider를 대상으로 SAML 인증을 처리하고, 프로필을 정규화하며, 해당 프로필을 OAuth 2.0 code grant flow에서 사용할 수 있게 해주는 오픈 소스 서비스입니다.

osu!

원본 URL: https://next-auth.js.org/providers/osu

Patreon

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Pipedrive

각 옵션은 사용 사례에 맞게 원하는 대로 재정의할 수 있습니다.

!next-auth-reddit-provider-config

Salesforce

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Slack

원본 URL: https://next-auth.js.org/providers/slack

Spotify

원본 URL: https://next-auth.js.org/providers/spotify

Strava

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다. 구성이 필요에 맞는지 확인하세요.

Todoist

사용 사례에 맞게 옵션을 자유롭게 재정의할 수 있습니다.

Trakt

프로덕션에서 api.trakt.tv를 호출해 API를 사용한다면, 아래 예시를 따르세요. api-staging.trakt.tv를 호출해 Trakt의 샌드박스 환경에서 개발하려면 URL만 변경하여 기본 옵션을 사용하세요.

Twitch

다음 리디렉션 URL을 콘솔에 추가하세요

Twitter

Twitter는 현재 OAuth 1.0 사양을 사용하는 유일한 내장 Provider입니다. 즉, 또는 을 받는 대신 각각 과 을 받게 됩니다. Adapter를 사용하는 경우를 대비해, 데이터베이스 스키마에 이 값들도 추가해 두세요.

United Effects

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

문서[](https://next-auth.js.org/providers/vk#documentation "Direct link to heading")

필요에 맞게 모든 옵션을 재정의할 수 있습니다.

Wikimedia

이 provider는 모든 Wikimedia 프로젝트도 지원합니다:

WordPress.com

원본 URL: https://next-auth.js.org/providers/wordpress

WorkOS

원하는 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Yandex

사용 사례에 맞게 옵션을 자유롭게 재정의할 수 있습니다.

Zitadel

원본 URL: https://next-auth.js.org/providers/zitadel

Zoho

Zoho는 에 문자열 타입의 이라는 필드를 반환합니다. 해당 내용은 docs를 참고하세요. Adapter를 사용 중이라면 데이터베이스 스키마에 이 필드를 추가하는 것을 잊지 마세요.

Zoom

자신의 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

문서 검색

🎉 NextAuth.js는 이제 Better Auth의 일부입니다!

취약점 제보[](https://next-auth.js.org/security#reporting-a-vulnerability "Direct link to heading")

NextAuth.js는 책임 있는 공개 원칙을 따릅니다.

NextAuth.js

튜토리얼과 해설

원본 URL: https://next-auth.js.org/tutorials

기업용 링크 검사기 환경에서 이메일 가입 허용

원본 URL: https://next-auth.js.org/tutorials/avoid-corporate-link-checking-email-provider

corporate-proxy

원본 URL: https://next-auth.js.org/tutorials/corporate-proxy

어댑터 만들기

커스텀 어댑터를 사용하면 어떤 데이터베이스 백엔드든, 심지어 여러 개의 서로 다른 데이터베이스에도 연결할 수 있습니다. 커뮤니티에서 만들고 유지 관리하는 공식 어댑터는 adapters 패키지에서 찾을 수 있습니다. 프로젝트의 커스텀 어댑터를 저장소에 자유롭게 추가하거나...

LDAP 인증

NextAuth.js는 사용자 정의 Credential provider를 설정할 수 있는 기능을 제공하며, 이를 활용해 기존 LDAP 서버에 대해 사용자 인증을 수행할 수 있습니다.

페이지 및 API 라우트 보안

NextAuth.js를 사용하면 클라이언트 사이드 렌더링 페이지, 서버 사이드 렌더링 페이지, 그리고 API 라우트를 쉽게 보호할 수 있습니다.

Cypress로 테스트하기

NextAuth.js 구현을 테스트하려면 Cypress 사용을 권장합니다.

클래스 컴포넌트에서 사용하기

클래스 컴포넌트에서 훅을 사용하려면, 고차 컴포넌트(higher order component) 또는 render prop의 도움을 받아 사용할 수 있습니다.

DynamoDB

이것은 next-auth용 AWS DynamoDB Adapter입니다. 이 패키지는 기본 next-auth 패키지와 함께 사용할 때만 동작합니다. 독립형 패키지가 아닙니다.

FaunaDB

원본 URL: https://next-auth.js.org/v3/adapters/fauna

Firebase

이 문서는 를 위한 Firebase Adapter입니다. 이 패키지는 기본 패키지와 함께 사용할 때만 동작합니다. 독립적으로 사용할 수 있는 패키지가 아닙니다.

User[](https://next-auth.js.org/v3/adapters/models#user "Direct link to heading")

NextAuth.js의 모델은 ANSI SQL을 기준으로 설계되었지만 다형성을 가지며, 사용 중인 데이터베이스에 맞게 변환됩니다. 특정 데이터 타입(예: datetime, text 필드 등)에는 약간의 차이가 있지만, 가능한 한 동작 일관성을 유지하면서 기능적으로는 동...

사용자 정의 Adapter[](https://next-auth.js.org/v3/adapters/overview#custom-adapter "Direct link to heading")

NextAuth.js의 Adapter는 사용자 계정, 세션 등의 데이터를 저장하기 위해 애플리케이션을 원하는 데이터베이스 또는 백엔드 시스템에 연결해 줍니다.

PouchDB

원본 URL: https://next-auth.js.org/v3/adapters/pouchdb

Prisma (레거시)

내장된 Prisma용 Adapter를 사용해 NextAuth.js를 함께 사용할 수도 있습니다. 현재 이 기능은 코어 패키지에 포함되어 있습니다. 다른 adapter는 별도의 추가 패키지에서 설치해야 합니다.

Prisma

원본 URL: https://next-auth.js.org/v3/adapters/prisma

MongoDB

MongoDB는 문서 데이터베이스이며, 대부분의 RDBMS 데이터베이스와 같은 방식으로 스키마를 사용하지 않습니다.

Microsoft SQL Server

Microsoft SQL Server(mssql) 데이터베이스용 스키마입니다.

MySQL

MySQL 데이터베이스용 스키마입니다.

Postgres

Postgres 데이터베이스용 스키마입니다.

TypeORM 어댑터[](https://next-auth.js.org/v3/adapters/typeorm/typeorm-overview#typeorm-adapter "Direct link to heading")

원본 URL: https://next-auth.js.org/v3/adapters/typeorm/typeorm-overview

로그인 콜백[](https://next-auth.js.org/v3/configuration/callbacks#sign-in-callback "Direct link to heading")

콜백은 작업이 수행될 때 어떤 일이 발생할지 제어하는 데 사용할 수 있는 비동기 함수입니다.

데이터베이스

NextAuth.js는 데이터베이스에 연결하는 여러 가지 방법을 제공합니다.

이벤트[](https://next-auth.js.org/v3/configuration/events#events "Direct link to heading")

이벤트는 응답을 반환하지 않는 비동기 함수이며, 감사 로그/리포팅에 유용합니다.

환경 변수[](https://next-auth.js.org/v3/configuration/options#environment-variables "Direct link to heading")

프로덕션에 배포할 때는 환경 변수를 사이트의 정식 URL로 설정하세요.

Pages

NextAuth.js는 Sign in, Sign out, Email Verification을 처리하고 오류 메시지를 표시하기 위한 단순한 비브랜딩 인증 페이지를 자동으로 생성합니다.

프로바이더

사용자가 로그인할 수 있는 방법은 네 가지입니다:

핵심 팀[](https://next-auth.js.org/v3/contributors#core-team "헤딩으로 직접 링크")

원본 URL: https://next-auth.js.org/v3/contributors

Client[](https://next-auth.js.org/v3/errors#client "제목으로 바로 가는 링크")

다음은 NextAuth.js에서 출력되는 오류 목록입니다.

자주 묻는 질문

NextAuth.js는 개인 기여자들이 만든 오픈 소스 프로젝트입니다.

클라이언트 API

NextAuth.js 클라이언트 라이브러리를 사용하면 React 애플리케이션에서 세션을 쉽게 다룰 수 있습니다.

예제 코드

아래 예제 코드는 Next.js 앱에 인증을 추가하는 방법을 설명합니다.

NextAuth.js 소개[](https://next-auth.js.org/v3/getting-started/introduction#about-nextauthjs "헤딩으로 직접 연결")

NextAuth.js는 Next.js 애플리케이션을 위한 완전한 오픈 소스 인증 솔루션입니다.

REST API

NextAuth.js는 NextAuth.js 클라이언트에서 사용하는 REST API를 제공합니다.

TypeScript

NextAuth.js는 자체 타입 정의를 제공하므로 TypeScript 프로젝트에서 안전하게 사용할 수 있습니다. TypeScript를 사용하지 않더라도 VSCode 같은 IDE가 이를 인식해 더 나은 개발자 경험을 제공합니다. 코드를 입력하는 동안 특정 객체/함수의 ...

42 School

자체 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Apple

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Atlassian

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Auth0

Auth0에서 애플리케이션을 'Single Page App'이 아닌 'Regular Web Application'으로 구성하세요.

Azure Active Directory B2C

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Basecamp

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Battle.net

자신의 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

문서[](https://next-auth.js.org/v3/providers/box#documentation "Direct link to heading")

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Bungie

원본 URL: https://next-auth.js.org/v3/providers/bungie

Amazon Cognito

Cognito 대시보드로 이동하려면 AWS 리전을 선택해야 합니다.

Coinbase

자신의 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

자격 증명

Credentials provider를 사용하면 사용자 이름과 비밀번호, 도메인, 2단계 인증, 하드웨어 디바이스(예: YubiKey U2F / FIDO)처럼 임의의 자격 증명으로 로그인 처리를 할 수 있습니다.

Discord

원본 URL: https://next-auth.js.org/v3/providers/discord

Dropbox

원본 URL: https://next-auth.js.org/v3/providers/dropbox

DuendeIdentityServer6

사용 사례에 맞게 원하는 옵션을 재정의할 수 있습니다.

개요[](https://next-auth.js.org/v3/providers/email#overview "Direct link to heading")

Email provider는 이메일을 사용해 로그인에 사용할 수 있는 "매직 링크"를 전송합니다. Slack 같은 서비스를 사용해 봤다면 이미 보셨을 가능성이 높습니다.

EVE Online

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Facebook

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

FACEIT

기본 정보(email, nickname, guid, avatar)를 얻기 위한 scopes: , ,

Foursquare

Foursquare는 추가 파라미터를 format으로 요구하며, 이는 본질적으로 "이 날짜까지의 API 변경 사항을 감당할 준비가 되어 있다"는 의미입니다.

FusionAuth

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

GitHub

원본 URL: https://next-auth.js.org/v3/providers/github

GitLab

원본 URL: https://next-auth.js.org/v3/providers/gitlab

Google

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

IdentityServer4

사용 사례에 맞게 원하는 옵션을 재정의할 수 있습니다.

Instagram

원본 URL: https://next-auth.js.org/v3/providers/instagram

Kakao

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

LINE

자신의 사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

원본 URL: https://next-auth.js.org/v3/providers/linkedin

Mailchimp

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Mail.ru

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Medium

자신의 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Naver

사용 사례에 맞게 옵션을 자유롭게 재정의할 수 있습니다.

Netlify

자체 사용 사례에 맞게 원하는 옵션을 재정의할 수 있습니다.

Okta

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Osso

Osso는 Identity Provider에 대한 SAML 인증을 처리하고, 프로필을 정규화하며, 해당 프로필을 OAuth 2.0 code grant 흐름에서 사용할 수 있게 해주는 오픈 소스 서비스입니다.

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Salesforce

원본 URL: https://next-auth.js.org/v3/providers/salesforce

Slack

사용 사례에 맞게 옵션을 자유롭게 재정의할 수 있습니다.

Spotify

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Strava

원본 URL: https://next-auth.js.org/v3/providers/strava

Twitch

원본 URL: https://next-auth.js.org/v3/providers/twitch

Twitter

자체 사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

문서[](https://next-auth.js.org/v3/providers/vk#documentation "제목으로 바로 가는 링크")

사용 사례에 맞게 어떤 옵션이든 재정의할 수 있습니다.

WordPress.com

원본 URL: https://next-auth.js.org/v3/providers/wordpress

WorkOS

필요에 맞게 어떤 옵션이든 재정의할 수 있습니다.

Yandex

원본 URL: https://next-auth.js.org/v3/providers/yandex

Zoho

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

Zoom

사용 사례에 맞게 모든 옵션을 재정의할 수 있습니다.

튜토리얼 및 설명

_이 튜토리얼들은 커뮤니티에서 기여했으며 이 사이트에 호스팅됩니다._

데이터베이스 어댑터 만들기

커스텀 어댑터를 사용하면 어떤 데이터베이스 백엔드든, 심지어 서로 다른 여러 데이터베이스에도 연결할 수 있습니다. 커뮤니티에서 만들고 유지 관리하는 커스텀 어댑터는 adapters repository에서 확인할 수 있습니다. 여러분의 프로젝트에서 만든 커스텀 어댑터를 ...

LDAP 인증

NextAuth.js는 custom Credential provider를 설정할 수 있는 기능을 제공하며, 이를 활용해 기존 LDAP 서버를 대상으로 사용자를 인증할 수 있습니다.

Refresh Token Rotation

NextAuth.js는 아직 OAuth provider의 access token rotation을 자동으로 처리하지 않지만, 이 기능은 callbacks를 사용해 구현할 수 있습니다.

페이지 및 API 라우트 보호

NextAuth.js를 사용하면 클라이언트 사이드 렌더링 페이지, 서버 사이드 렌더링 페이지, 그리고 API 라우트를 쉽게 보호할 수 있습니다.

Cypress로 테스트하기

NextAuth.js 구현을 테스트할 때는 Cypress 사용을 권장합니다.

TypeORM 커스텀 모델

원본 URL: https://next-auth.js.org/v3/tutorials/typeorm-custom-models

클래스 컴포넌트에서 사용하기

원본 URL: https://next-auth.js.org/v3/tutorials/usage-with-class-components

클라이언트[](https://next-auth.js.org/v3/warnings#client "Direct link to heading")

다음은 NextAuth.js의 경고 출력 목록입니다.

클라이언트[](https://next-auth.js.org/warnings#client "Direct link to heading")

원본 URL: https://next-auth.js.org/warnings

Next.js 국제화(i18n)

`next-intl`은 Next.js용 국제화 툴킷으로, 다음을 도와줍니다:

디자인 원칙

이 페이지는 이 기반으로 삼고 있는 디자인 원칙을 깊이 있게 설명합니다.

index

원본 URL: https://next-intl.dev/docs/environments

서버 액션, 메타데이터 및 라우트 핸들러

Next.js 앱에서는 React 컴포넌트 밖에서도 국제화를 적용할 수 있는 위치가 몇 가지 있습니다:

코어 라이브러리

은 주로 Next.js 앱에서 사용하도록 설계되었지만, 코어는 프레임워크 비종속적이며 독립적으로 사용할 수 있습니다. 즉, React 앱이나 다른 모든 JavaScript 환경에서도 사용할 수 있습니다.

Next.js 오류 파일에서의 국제화

Next.js App Router의 파일 컨벤션은 오류 처리를 위해 사용할 수 있는 두 가지 파일을 제공합니다.

런타임 요구사항

원본 URL: https://next-intl.dev/docs/environments/runtime-requirements

서버 및 클라이언트 컴포넌트의 국제화

이는 국제화 처리에도 동일하게 적용됩니다.

Vitest[](https://next-intl.dev/docs/environments/testing#vitest)

원본 URL: https://next-intl.dev/docs/environments/testing

Next.js 국제화(i18n)

은 Next.js를 위한 국제화 툴킷으로, 다음을 도와줍니다:

Next.js App Router 국제화(i18n)

아직 하지 않았다면, App Router를 사용하는 Next.js 앱을 생성하고 다음을 실행하세요:

Next.js Pages Router 국제화(i18n)

import {NextIntlClientProvider} from 'next-intl';

index

은 Next.js의 라우팅 시스템 두 곳에 통합됩니다:

라우팅 구성

import {defineRouting} from 'next-intl/routing';

프록시 / 미들웨어

미들웨어는 를 통해 생성할 수 있습니다.

Navigation API

은 , 같은 Next.js의 내비게이션 API를 감싸는 가벼운 wrapper를 제공하며, 내부적으로 사용자 locale과 pathname을 자동으로 처리합니다.

로케일 기반 라우팅 설정

원본 URL: https://next-intl.dev/docs/routing/setup

사용 가이드

원본 URL: https://next-intl.dev/docs/usage

요청 구성

원본 URL: https://next-intl.dev/docs/usage/configuration

날짜 및 시간 형식 지정

날짜와 시간의 형식은 로케일마다 크게 다릅니다(예: 에서는 “Apr 24, 2023”, 에서는 “24 квіт. 2023 р.”). 의 형식 지정 기능을 사용하면 Next.js 앱에서 i18n 차이를 자동으로 처리할 수 있습니다.

useExtracted (실험적)

네임스페이스와 키를 수동으로 관리하는 대신, 은 와 유사하게 동작하지만 소스 파일에서 메시지를 자동으로 추출하는 추가 API를 제공합니다.

목록 포맷팅

항목 목록을 다룰 때, 목록을 접속형(conjunction) 또는 선택형(disjunction)으로 포맷할 수 있습니다.

숫자 서식 지정

숫자의 서식은 사용자의 로캘에 따라 달라질 수 있으며, 다음과 같은 서로 다른 규칙이 포함될 수 있습니다.

Next.js 플러그인 (createNextIntlPlugin)

import {NextConfig} from 'next';

번역 렌더링

원본 URL: https://next-intl.dev/docs/usage/translations

워크플로 및 통합

원본 URL: https://next-intl.dev/docs/workflows

Crowdin을 사용한 현지화 관리

완전한 AI 기반 워크플로를 사용하는 것이 더 좋으신가요?

메시지 검증

원본 URL: https://next-intl.dev/docs/workflows/messages

next-intl을 위한 Storybook 통합

용 Storybook을 설정하려면, 스토리를 적절히 감싸도록 를 렌더링하는 전역 데코레이터를 구성할 수 있습니다:

TypeScript 보강

은 별도의 추가 설정 없이 기본적으로 TypeScript와 매끄럽게 통합됩니다.

VSCode 통합

코드 에디터에서 바로 메시지를 관리하는 워크플로를 개선하려면, 을 지원하는 VSCode 확장을 사용할 수 있습니다.

Next.js 문서

Next.js 문서에 오신 것을 환영합니다!

Next.js Docs: App Router

설치부터 레이아웃, 내비게이션, 서버 및 클라이언트 컴포넌트까지 앱 라우터 프로젝트를 구축하는 기본기를 학습하세요.

App Router: API 레퍼런스

API 레퍼런스: CLI

Next.js에는 두 가지 명령줄 인터페이스(CLI) 도구가 포함되어 있습니다.

CLI: create-next-app

CLI를 사용하면 기본 템플릿이나 공개 GitHub 리포지토리의 예제를 통해 새로운 Next.js 애플리케이션을 만들 수 있습니다. Next.js를 시작하는 가장 쉬운 방법입니다.

CLI: next CLI

원본 URL: https://nextjs.org/docs/app/api-reference/cli/next

API Reference: Components

구성 요소: Font

모든 폰트 파일에 대해 내장 자동 셀프 호스팅을 포함합니다. 이는 layout shift 없이 웹 폰트를 최적으로 로드할 수 있음을 의미합니다.

컴포넌트: Form 컴포넌트

컴포넌트는 HTML 요소를 확장해 로딩 UI의 사전 가져오기, 제출 시 클라이언트 측 내비게이션, 점진적 향상을 제공합니다.

컴포넌트: Image 컴포넌트

Next.js Image 컴포넌트는 자동 이미지 최적화를 위해 HTML 요소를 확장합니다.

컴포넌트: Link Component

는 prefetching과 경로 간 클라이언트 측 내비게이션을 제공하도록 HTML 요소를 확장한 React 컴포넌트입니다. Next.js에서 경로 간 이동을 수행하는 기본 방법입니다.

컴포넌트: Script 컴포넌트

이 API 레퍼런스는 Script 컴포넌트에 사용할 수 있는 props의 동작을 이해하는 데 도움을 줍니다. 기능과 사용 예시는 Optimizing Scripts 페이지를 참고하세요.

API Reference: Configuration

구성: ESLint

Next.js는 애플리케이션에서 흔히 발생하는 문제를 쉽게 찾을 수 있도록 라는 ESLint 구성 패키지를 제공합니다. 이 패키지는 플러그인과 함께 , 의 권장 규칙 세트를 포함합니다.

구성: next.config.js

최종 업데이트: 2026년 2월 20일

next.config.js: experimental.adapterPath

Next.js는 빌드 프로세스에 연결할 수 있는 커스텀 어댑터를 만들 수 있도록 실험적 API를 제공합니다. 이는 Next.js 구성을 수정하거나 빌드 결과물을 처리해야 하는 배포 플랫폼이나 커스텀 빌드 통합에서 유용합니다.

next.config.js: allowedDevOrigins

Next.js는 개발 중 교차 출처 요청을 자동으로 차단하지 않지만, 향후 메이저 버전에서는 개발 모드에서 노출되는 내부 자산/엔드포인트에 대한 무단 요청을 방지하기 위해 기본적으로 차단할 예정입니다.

next.config.js: appDir

이것은 레거시 API이며 더 이상 권장되지 않습니다. 하위 호환성을 위해 계속 지원됩니다.

next.config.js: assetPrefix

> 주의: Vercel에 배포하면 Next.js 프로젝트에 대한 글로벌 CDN이 자동으로 구성됩니다. Asset Prefix를 수동으로 설정할 필요가 없습니다.

next.config.js: authInterrupts

이 기능은 현재 카나리 채널에서만 사용할 수 있으며 변경될 수 있습니다. Next.js를 업그레이드해 체험해 보고, GitHub에서 의견을 공유해 주세요.

next.config.js: basePath

Next.js 애플리케이션을 도메인의 하위 경로에 배포하려면 구성 옵션을 사용할 수 있습니다.

next.config.js: browserDebugInfoInTerminal

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 직접 사용해 보고 GitHub에 의견을 공유해 주세요.

next.config.js: cacheComponents

플래그는 Next.js App Router에서 데이터 가져오기 작업이 명시적으로 캐시되지 않는 한 사전 렌더링에서 제외되도록 만드는 기능입니다. 이는 서버 컴포넌트에서 동적 데이터 가져오기 성능을 최적화하는 데 유용합니다.

next.config.js: cacheHandlers

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers

next.config.js: cacheLife

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheLife

next.config.js: compress

기본적으로 Next.js는 또는 커스텀 서버를 사용할 때 렌더링된 콘텐츠와 정적 파일을 압축하기 위해 을 사용합니다. 이는 압축이 구성되어 있지 않은 애플리케이션을 위한 최적화입니다. 커스텀 서버를 통해 애플리케이션에서 이미 압축을 구성한 경우 Next.js는 압축을...

next.config.js: crossOrigin

옵션을 사용하면 컴포넌트가 생성하는 모든 태그에 속성을 추가하고, 교차 출처 요청을 처리하는 방식을 정의할 수 있습니다.

next.config.js: cssChunking

이 기능은 현재 실험 중이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. GitHub에서 피드백을 공유해 주세요.

next.config.js: deploymentId

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId

next.config.js: devIndicators

는 개발 중에 현재 보고 있는 경로에 대한 컨텍스트를 제공하는 화면 표시기를 구성할 수 있게 해줍니다.

next.config.js: distDir

대신 사용할 사용자 지정 빌드 디렉터리 이름을 지정할 수 있습니다.

next.config.js: env

이 API는 레거시이며 더 이상 권장되지 않습니다. 하위 호환성을 위해 계속 지원됩니다.

next.config.js: expireTime

최종 업데이트: 2026년 2월 20일

next.config.js: exportPathMap

이 API는 레거시이므로 더 이상 권장되지 않습니다. 하위 호환성을 위해서만 계속 지원됩니다.

next.config.js: generateBuildId

Next.js는 애플리케이션에서 제공 중인 버전을 식별하기 위해 중에 ID를 생성합니다. 동일한 빌드를 재사용하여 여러 컨테이너를 부팅해야 합니다.

next.config.js: generateEtags

Next.js는 기본적으로 모든 페이지에 대해 etags를 생성합니다. 캐시 전략에 따라 HTML 페이지에서 etag 생성을 비활성화하고 싶을 수 있습니다.

next.config.js: 헤더

헤더를 사용하면 특정 경로로 들어오는 요청에 대한 응답에 커스텀 HTTP 헤더를 설정할 수 있습니다.

next.config.js: htmlLimitedBots

구성은 스트리밍 메타데이터 대신 차단 메타데이터를 받아야 하는 사용자 에이전트 목록을 지정할 수 있도록 합니다.

next.config.js: httpAgentOptions

Node.js 18 이전 버전에서는 Next.js가 자동으로 undici를 사용해 를 폴리필하고 기본적으로 HTTP Keep-Alive를 활성화합니다.

next.config.js: 이미지

Next.js 내장 Image Optimization API 대신 클라우드 공급자를 사용해 이미지를 최적화하려면 를 다음과 같이 구성할 수 있습니다.

next.config.js: cacheHandler

캐시된 페이지와 데이터를 영구 스토리지에 보존하거나 Next.js 애플리케이션의 여러 컨테이너·인스턴스 간에 캐시를 공유하려면 Next.js 캐시 위치를 구성할 수 있습니다.

next.config.js: inlineCss

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 사용해 보고 GitHub에 피드백을 공유해 주세요.

next.config.js: isolatedDevBuild

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션에서는 권장되지 않습니다. GitHub에서 사용해 보고 피드백을 공유해주세요.

next.config.js: logging

개발 모드에서 Next.js를 실행할 때, 로그 수준과 전체 URL을 콘솔에 기록할지 여부를 구성할 수 있습니다.

next.config.js: mdxRs

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 사용해 본 뒤 GitHub에서 피드백을 공유해 주세요.

next.config.js: onDemandEntries

Next.js는 개발 환경에서 빌드된 페이지를 서버가 메모리에 유지하거나 폐기하는 방식을 일부 제어할 수 있는 옵션을 제공합니다.

next.config.js: optimizePackageImports

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports

next.config.js: output

빌드 중 Next.js는 각 페이지와 그 의존성을 자동으로 추적해 프로덕션 버전을 배포하는 데 필요한 모든 파일을 결정합니다.

next.config.js: pageExtensions

기본적으로 Next.js는 , , , 확장자를 가진 파일을 허용합니다. 이는 마크다운(, )과 같은 다른 확장자를 포함하도록 수정할 수 있습니다.

next.config.js: poweredByHeader

기본적으로 Next.js는 헤더를 추가합니다. 이를 사용하지 않으려면 를 열어 설정을 비활성화하세요.

next.config.js: productionBrowserSourceMaps

개발 중에는 소스 맵이 기본적으로 활성화됩니다. 프로덕션 빌드에서는 별도로 이 구성 플래그를 통해 옵트인하지 않는 한, 클라이언트 측에 소스가 노출되는 일을 막기 위해 비활성화됩니다.

next.config.js: proxyClientMaxBodySize

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 환경에서는 사용을 권장하지 않습니다. 직접 사용해 보고 GitHub에서 피드백을 공유하세요.

next.config.js: reactCompiler

Next.js는 컴포넌트 렌더링을 자동으로 최적화해 성능을 높이도록 설계된 React Compiler를 지원합니다. 이를 통해 와 으로 수동 메모이제이션을 해야 하는 필요성이 줄어듭니다.

next.config.js: reactMaxHeadersLength

정적 렌더링 중에 React는 응답에 추가할 수 있는 헤더를 생성할 수 있습니다. 이를 통해 브라우저가 폰트, 스크립트, 스타일시트 같은 리소스를 미리 로드하도록 허용해 성능을 향상시킬 수 있습니다. 기본값은 이지만, 의 옵션을 구성하여 이 값을 재정의할 수 있습니다...

next.config.js: reactStrictMode

> 알아두면 좋아요 : Next.js 13.5.1부터 라우터에서는 Strict Mode가 기본값으로 이므로, 위 설정은 에서만 필요합니다. 로 설정해 Strict Mode를 비활성화할 수도 있습니다.

next.config.js: 리다이렉트

리다이렉트는 들어오는 요청 경로를 다른 대상 경로로 전환할 수 있게 해 줍니다.

next.config.js: 리라이트

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites

next.config.js: sassOptions

를 사용하면 Sass 컴파일러를 구성할 수 있습니다.

next.config.js: serverActions

Next.js 애플리케이션에서 Server Actions 동작을 구성하기 위한 옵션입니다.

next.config.js: serverComponentsHmrCache

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 로컬 개발에서 사용해 보고 GitHub에서 피드백을 공유해 주세요.

next.config.js: serverExternalPackages

특정 의존성이 Node.js 전용 기능을 사용한다면, 해당 의존성을 Server Components 번들링에서 선택적으로 제외하고 네이티브 Node.js 를 사용할 수 있습니다.

next.config.js: staleTimes

이 기능은 현재 실험적 단계이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 시도해 보고 GitHub에서 피드백을 공유해 주세요.

next.config.js: staticGeneration*

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 직접 사용해 보고 GitHub에서 피드백을 공유해 주세요.

next.config.js: taint

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 사용해 보고 GitHub에서 의견을 공유해 주세요.

next.config.js: trailingSlash

기본적으로 Next.js는 슬래시가 붙은 URL을 슬래시가 없는 대응 경로로 리디렉션합니다. 예를 들어 은 으로 이동합니다. 이 동작을 반대로 설정해, 슬래시가 없는 URL을 슬래시가 붙은 경로로 리디렉션하도록 구성할 수 있습니다.

next.config.js: transpilePackages

Next.js는 로컬 패키지(모노레포 등)나 외부 의존성()에서 종속성을 자동으로 트랜스파일하고 번들할 수 있습니다. 이는 패키지를 대체합니다.

next.config.js: turbopack

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack

next.config.js: turbopackFileSystemCache

Turbopack 파일시스템 캐시는 또는 명령 전반에서 Turbopack의 작업량을 줄일 수 있도록 합니다. 이 기능을 활성화하면 Turbopack은 빌드 사이에 폴더에 데이터를 저장하고 복원하여 이후 빌드와 개발 세션을 크게 가속할 수 있습니다.

next.config.js: typedRoutes

> 참고: 이 옵션은 안정(stable) 버전으로 지정되었으므로 대신 를 사용해야 합니다.

next.config.js: typescript

에서 옵션으로 TypeScript 동작을 구성하세요:

next.config.js: urlImports

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에서 사용하는 것은 권장되지 않습니다. 사용해 보고 GitHub에 피드백을 공유해 주세요.

next.config.js: useLightningcss

이 기능은 현재 실험적이며 향후 변경될 수 있으므로 프로덕션에서는 권장되지 않습니다. GitHub에서 사용해 보고 피드백을 공유하세요.

next.config.js: viewTransition

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 사용해 보고 GitHub에서 피드백을 공유해 주세요.

next.config.js: webpack

원본 URL: https://nextjs.org/docs/app/api-reference/config/next-config-js/webpack

next.config.js: webVitalsAttribution

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에는 권장되지 않습니다. 대신 사용해 보고 GitHub에서 피드백을 공유해주세요.

구성: TypeScript

Next.js는 내장 TypeScript를 제공하므로 으로 새 프로젝트를 만들 때 필요한 패키지를 자동으로 설치하고 적절한 설정을 구성합니다.

API 레퍼런스: Directives

사용 가능한 디렉티브는 다음과 같습니다:

지시문: use cache: private

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션에서 권장되지 않습니다. 시도해 본 뒤 GitHub에서 의견을 공유해주세요.

지시문: use cache: remote

지시문은 대부분의 애플리케이션 요구 사항을 충족하지만, 캐시된 연산이 예상보다 자주 다시 실행되거나 업스트림 서비스(CMS, 데이터베이스, 외부 API 등)에 대한 요청이 늘어나는 경우가 있을 수 있습니다. 이는 가 엔트리를 메모리에 저장하기 때문에 발생하며, 다음과 ...

지시문: use cache

지시문은 라우트, React 컴포넌트, 함수가 캐시될 수 있도록 표시합니다. 파일 상단에 선언하면 해당 파일의 모든 export가 캐시되고, 함수나 컴포넌트 상단에 인라인으로 선언하면 반환값을 캐시합니다.

지시문: use client

지시문은 클라이언트 측에서 렌더링될 컴포넌트의 진입점을 선언하며, 상태 관리, 이벤트 처리, 브라우저 API 접근처럼 클라이언트 측 JavaScript 기능이 필요한 대화형 사용자 인터페이스(UI)를 만들 때 사용해야 합니다. 이는 React 기능입니다.

지시문: use server

지시문은 함수나 파일이 서버 측에서 실행되어야 함을 지정합니다. 파일 맨 위에 두면 해당 파일의 모든 함수가 서버 측 함수임을 나타내고, 함수의 상단에 인라인으로 추가하면 해당 함수를 Server Function으로 표시합니다. 이는 React 기능입니다.

API 레퍼런스: Edge Runtime

Next.js 애플리케이션에서는 두 가지 서버 런타임을 사용할 수 있습니다:

API 레퍼런스: 파일 시스템 규칙

2026년 2월 20일에 마지막으로 업데이트됨

파일 시스템 규칙: default.js

파일은 Next.js가 전체 페이지 로드 후 슬롯의 활성 상태를 복구하지 못할 때 병렬 라우트 내에서 폴백을 렌더링하는 데 사용됩니다.

파일 시스템 규칙: 동적 세그먼트

요청 시점에 채워지거나 빌드 시 사전 렌더링되는 동적 데이터를 이용해 라우트를 만들고 싶은데 정확한 라우트 세그먼트 이름을 미리 알 수 없다면, 동적 세그먼트를 사용할 수 있습니다.

파일 시스템 규칙: error.js

app/dashboard/error.tsx

파일 시스템 규칙: forbidden.js

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 사용해 보고 GitHub에 피드백을 공유해 주세요.

파일 시스템 규칙: instrumentation-client.js

파일을 사용하면 애플리케이션이 인터랙티브 상태가 되기 전에 실행되는 모니터링, 분석 코드, 기타 부수 효과를 추가할 수 있습니다. 이는 성능 추적, 오류 모니터링, 폴리필 또는 그 밖의 클라이언트 측 관측 도구를 설정하는 데 유용합니다.

파일 시스템 규칙: instrumentation.js

파일은 애플리케이션에 관측 도구를 통합하여 성능과 동작을 추적하고 프로덕션 문제를 디버깅할 수 있도록 합니다.

파일 시스템 규칙: 인터셉트(Intercepting) 라우트

인터셉트 라우트를 사용하면 현재 레이아웃 안에서 앱의 다른 위치에 있는 라우트를 로드할 수 있습니다. 이 라우팅 패러다임은 사용자가 다른 컨텍스트로 전환하지 않고도 특정 라우트의 콘텐츠를 표시하고 싶을 때 유용합니다.

파일 시스템 규칙: layout.js

파일은 Next.js 애플리케이션에서 레이아웃을 정의하는 데 사용됩니다.

파일 시스템 규칙: loading.js

특수 파일 는 React Suspense를 사용해 의미 있는 로딩 UI를 만들도록 도와줍니다. 이 규칙을 사용하면 경로 세그먼트의 콘텐츠가 스트리밍되는 동안 서버에서 즉시 로딩 상태를 표시할 수 있습니다. 새 콘텐츠가 완료되면 자동으로 교체됩니다.

파일 시스템 규칙: mdx-components.js

원본 URL: https://nextjs.org/docs/app/api-reference/file-conventions/mdx-components

파일 시스템 규칙: Metadata Files

이 문서 섹션에서는 메타데이터 파일 규칙을 다룹니다. 파일 기반 메타데이터는 라우트 세그먼트에 특수한 메타데이터 파일을 추가하여 정의할 수 있습니다.

메타데이터 파일: favicon, icon, and apple-icon

, , 또는 파일 규칙을 사용하면 애플리케이션 아이콘을 설정할 수 있습니다.

메타데이터 파일: manifest.json

브라우저에 웹 애플리케이션 정보를 제공하려면 디렉터리의 루트에 Web Manifest Specification을 준수하는 파일을 추가하거나 생성하세요.

메타데이터 파일: opengraph-image 및 twitter-image

및 파일 규칙은 라우트 세그먼트에 대해 Open Graph 및 Twitter 이미지를 설정할 수 있게 해줍니다.

메타데이터 파일: robots.txt

검색 엔진 크롤러에게 사이트에서 접근 가능한 URL을 알리려면 디렉터리의 루트에 Robots 배제 표준을 따르는 파일을 추가하거나 생성하세요.

메타데이터 파일: sitemap.xml

는 Sitemaps XML 포맷과 일치하는 특별한 파일로, 검색 엔진 크롤러가 사이트를 더 효율적으로 색인화하도록 돕습니다.

파일 시스템 규칙: not-found.js

최종 업데이트: 2026년 2월 20일

파일 시스템 규칙: page.js

파일을 사용하면 경로에 고유한 UI를 정의할 수 있습니다. 파일에서 컴포넌트를 기본 내보내기(default export)하면 페이지를 만들 수 있습니다:

파일 시스템 규칙: 병렬 라우트

Parallel Routes는 동일한 레이아웃 안에서 하나 이상의 페이지를 동시에 또는 조건부로 렌더링할 수 있게 해줍니다. 대시보드나 소셜 사이트의 피드처럼 매우 동적인 앱 섹션에 유용합니다.

파일 시스템 규칙: proxy.js

> 참고: 파일 규칙은 더 이상 사용되지 않으며 로 이름이 변경되었습니다. 자세한 내용은 Migration to Proxy를 참고하세요.

파일 시스템 규칙: public

Next.js는 루트 디렉터리의 폴더 아래에서 이미지 같은 정적 파일을 제공할 수 있습니다. 내부의 파일은 기본 URL()부터 시작하여 코드에서 참조할 수 있습니다.

파일 시스템 규칙: Route Groups

라우트 그룹은 폴더 이름을 기준으로 경로를 팀이나 카테고리별로 구성할 수 있게 해주는 폴더 규칙입니다.

파일 시스템 규칙: Route Segment Config

> * 플래그가 켜져 있으면 이 페이지에 설명된 옵션은 비활성화되며, 향후 더 이상 지원되지 않습니다.

파일 시스템 규칙: route.js

Route Handler를 사용하면 Web Request 및 Response API를 이용해 특정 라우트에 대한 사용자 정의 요청 핸들러를 만들 수 있습니다.

파일 시스템 규칙: src

프로젝트 루트에 특수한 Next.js 또는 디렉터리를 두는 대신, Next.js는 애플리케이션 코드를 폴더 아래에 두는 일반적인 패턴도 지원합니다.

파일 시스템 규칙: template.js

파일에서 기본 React 컴포넌트를 export하여 템플릿을 정의할 수 있다. 이 컴포넌트는 prop을 받아야 한다.

파일 시스템 규칙: unauthorized.js

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. GitHub에서 체험 후 피드백을 공유해 주세요.

API 참조: Functions

Functions: after

는 응답(또는 사전 렌더링)이 완료된 뒤에 실행할 작업을 예약할 수 있게 해 줍니다. 이는 로깅, 분석처럼 응답을 차단하면 안 되는 작업 및 부수 효과에 유용합니다.

Functions: cacheLife

함수는 함수나 컴포넌트의 캐시 수명을 설정하는 데 사용됩니다. 지시문과 함께, 해당 함수나 컴포넌트 범위 내에서 사용해야 합니다.

함수: cacheTag

원본 URL: https://nextjs.org/docs/app/api-reference/functions/cacheTag

함수: connection

원본 URL: https://nextjs.org/docs/app/api-reference/functions/connection

함수: cookies

는 Server Components에서 들어오는 HTTP 요청의 쿠키를 읽고, Server Functions 또는 Route Handlers에서 나가는 요청 쿠키를 읽거나 쓸 수 있도록 해주는 비동기 함수입니다.

함수: draftMode

는 Server Component에서 Draft Mode가 활성화되어 있는지 확인하고, Draft Mode를 활성화·비활성화할 수 있는 async 함수입니다.

함수: fetch

Next.js는 Web API를 확장해 서버에서 수행되는 각 요청이 고유한 영구 캐싱 및 재검증 규칙을 설정할 수 있게 합니다.

함수: forbidden

이 기능은 현재 실험 단계이며 변경될 수 있으므로, 프로덕션 환경에서는 권장되지 않습니다. 테스트해 보고 GitHub에서 피드백을 공유해주세요.

함수: generateImageMetadata

를 사용하면 하나의 이미지에 대한 다양한 버전을 생성하거나 하나의 라우트 세그먼트에 여러 이미지를 반환할 수 있습니다. 이는 아이콘처럼 메타데이터 값을 하드코딩하지 않고자 할 때 유용합니다.

함수: generateMetadata

객체나 함수를 사용하여 메타데이터를 정의할 수 있습니다.

함수: generateSitemaps

애플리케이션에 대해 여러 사이트맵을 생성하려면 함수를 사용할 수 있습니다.

함수: generateStaticParams

함수는 동적 라우트 세그먼트와 함께 사용해 요청 시점이 아닌 빌드 시점에 정적 생성으로 라우트를 만들 수 있습니다.

함수: generateViewport

정적 객체나 동적 함수를 사용해 페이지의 초기 뷰포트를 사용자 지정할 수 있습니다.

함수: headers

는 Server Component에서 들어오는 HTTP 요청 헤더를 읽을 수 있게 해 주는 비동기 함수입니다.

함수: ImageResponse

생성자는 JSX와 CSS를 사용해 동적 이미지를 생성할 수 있게 합니다. 이는 Open Graph 이미지, Twitter 카드 등 소셜 미디어 이미지를 만들 때 유용합니다.

함수: NextRequest

NextRequest는 추가 편의 메서드를 제공하기 위해 Web Request API를 확장합니다.

함수: NextResponse

NextResponse는 Web Response API를 확장해 추가적인 편의 메서드를 제공합니다.

Functions: notFound

함수는 라우트 세그먼트 내에서 파일을 렌더링하고 태그를 삽입할 수 있도록 해줍니다.

함수: permanentRedirect

함수는 사용자를 다른 URL로 리디렉션하도록 해 줍니다. 는 서버 컴포넌트, 클라이언트 컴포넌트, 라우트 핸들러, 서버 함수에서 사용할 수 있습니다.

함수: redirect

함수는 사용자를 다른 URL로 리디렉션할 수 있게 해 줍니다. 는 서버 및 클라이언트 컴포넌트, 라우트 핸들러, 서버 함수에서 렌더링 중에 사용할 수 있습니다.

Functions: refresh

는 서버 액션 내부에서 클라이언트 라우터를 새로 고칠 수 있게 해줍니다.

함수: revalidatePath

는 특정 경로에 대해 필요할 때 캐시된 데이터를 무효화할 수 있게 해줍니다.

Functions: revalidateTag

는 특정 캐시 태그에 대해 캐시된 데이터를 온디맨드로 무효화할 수 있게 해줍니다.

함수: unauthorized

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 대신 테스트해 보고 GitHub에서 피드백을 공유해주세요.

Functions: unstable_cache

> 참고: 이 API는 Next.js 16에서 로 대체되었습니다. Cache Components를 사용하도록 전환하고 를 지시어로 교체하는 것을 권장합니다.

Functions: unstable_noStore

이 API는 레거시로 더 이상 권장되지 않습니다. 하위 호환성을 위해 계속 지원됩니다.

함수: unstable_rethrow

이 기능은 현재 불안정하며 변경될 수 있으므로 프로덕션에서는 권장되지 않습니다. GitHub에 피드백을 공유해 주세요.

Functions: updateTag

는 Server Actions 내에서 특정 캐시 태그의 캐시된 데이터를 필요할 때 업데이트할 수 있게 해 줍니다.

함수: useLinkStatus

훅을 사용하면 의 pending 상태를 추적할 수 있습니다. 클릭한 링크 위에 쉬머 효과처럼 미묘하고 인라인 피드백을 제공해 내비게이션이 완료될 때까지 사용자에게 상태를 알려 주세요. 즉각적인 전환에는 를 이용한 라우트 수준 폴백과 프리패칭을 우선 고려하세요.

Functions: useParams

2026년 2월 20일에 마지막으로 업데이트됨

Functions: usePathname

은 현재 URL의 pathname을 읽을 수 있게 해주는 클라이언트 컴포넌트 훅입니다.

함수: useReportWebVitals

훅은 Core Web Vitals을 보고할 수 있게 해 주며, 애널리틱스 서비스와 함께 사용할 수 있습니다.

함수: useRouter

훅을 사용하면 클라이언트 컴포넌트 내부에서 라우트를 프로그래밍 방식으로 변경할 수 있습니다.

함수: useSearchParams

는 현재 URL의 query string을 읽을 수 있게 해 주는 Client Component 훅입니다.

함수: useSelectedLayoutSegment

최종 업데이트: 2026년 2월 20일

함수: useSelectedLayoutSegments

는 호출된 Layout 아래의 활성 라우트 세그먼트를 읽을 수 있게 해주는 Client Component 훅입니다.

함수: userAgent

최종 업데이트: 2026년 2월 20일

API 레퍼런스: Turbopack

Turbopack은 Rust로 작성되어 Next.js에 내장된 증분 번들러로, JavaScript와 TypeScript에 최적화되어 있습니다. Pages와 App Router 모두에서 Turbopack을 사용해 훨씬 더 빠른 로컬 개발 경험을 얻을 수 있습니다.

앱 라우터: 시작하기

Next.js 문서에 오신 것을 환영합니다!

시작하기: Cache Components

> 알아두면 좋아요: Cache Components는 선택 사항입니다. Next 구성 파일에서 플래그를 로 설정해 활성화하세요. 자세한 내용은 Cache Components 활성화를 참조하세요.

시작하기: 캐싱과 재검증

캐싱은 데이터 페칭과 기타 연산의 결과를 저장해 동일한 데이터에 대한 향후 요청을 더 빠르게 처리하도록, 동일한 작업을 반복하지 않고도 응답할 수 있게 하는 기법입니다. 재검증은 애플리케이션 전체를 다시 빌드하지 않고도 캐시 항목을 최신 상태로 업데이트할 수 있게 해 ...

시작하기: CSS

Next.js는 다음과 같이 애플리케이션을 CSS로 스타일링할 수 있는 여러 방법을 제공합니다:

시작하기: 배포

Next.js는 Node.js 서버, Docker 컨테이너, 정적 내보내기, 또는 다양한 플랫폼에 맞춘 어댑터 형태로 배포할 수 있습니다.

시작하기: 오류 처리

오류는 예상된 오류와 처리되지 않은 예외 두 가지 범주로 나눌 수 있습니다. 이 페이지에서는 Next.js 애플리케이션에서 이러한 오류를 처리하는 방법을 설명합니다.

시작하기: 데이터 가져오기

이 페이지에서는 서버 및 클라이언트 컴포넌트에서 데이터를 가져오는 방법과 데이터에 의존하는 컴포넌트를 스트리밍하는 방법을 안내합니다.

시작하기: 폰트 최적화

이 모듈은 모든 폰트 파일에 대한 내장형 자체 호스팅을 포함합니다. 즉, 레이아웃 시프트 없이 웹 폰트를 최적으로 로드할 수 있습니다.

시작하기: 이미지 최적화

Next.js 컴포넌트는 HTML 요소를 확장해 다음과 같은 기능을 제공합니다:

시작하기: 설치

최종 업데이트: 2026년 2월 20일

시작하기: 레이아웃과 페이지

원본 URL: https://nextjs.org/docs/app/getting-started/layouts-and-pages

시작하기: 링크 및 탐색

Next.js에서는 기본적으로 서버에서 라우트를 렌더링합니다. 이는 새 라우트를 보여 주기 전에 클라이언트가 서버 응답을 기다려야 함을 의미합니다. Next.js는 탐색이 빠르고 반응성을 유지하도록 사전 가져오기, 스트리밍, 클라이언트 측 전환을 기본으로 제공합니다.

시작하기: 메타데이터와 OG 이미지

메타데이터 API는 애플리케이션 메타데이터를 정의해 SEO와 웹 공유성을 향상할 수 있으며 다음을 포함합니다.

시작하기: 프로젝트 구조

이 페이지는 Next.js의 모든 폴더와 파일 규칙, 그리고 프로젝트 구성에 대한 권장 사항을 개괄합니다.

시작하기: 프록시

> 알아두면 좋아요 : Next.js 16부터 Middleware가 목적을 더 잘 드러내도록 Proxy로 이름이 변경되었습니다. 기능은 동일하게 유지됩니다.

시작하기: Route Handlers

Route Handlers는 Web Request 및 Response API를 사용해 특정 경로에 대한 사용자 정의 요청 핸들러를 만들 수 있게 해줍니다.

시작하기: 서버 및 클라이언트 컴포넌트

기본적으로 레이아웃과 페이지는 서버 컴포넌트이며, 이를 통해 서버에서 데이터를 가져오고 UI 일부를 렌더링한 뒤 결과를 캐시하거나 클라이언트로 스트리밍할 수 있습니다. 상호작용이나 브라우저 API가 필요할 때는 클라이언트 컴포넌트를 사용해 기능을 추가할 수 있습니다.

시작하기: 데이터 업데이트

Next.js에서는 React의 Server Functions을 사용해 데이터를 업데이트할 수 있습니다. 이 페이지에서는 Server Function을 생성하고 호출하는 방법을 다룹니다.

시작하기: 업그레이드

최신 버전의 Next.js로 업데이트하려면 명령을 사용할 수 있습니다.

App Router: 용어집

React Server Components 위에 구축되어 Next.js 13에서 도입된 라우터입니다. 파일 시스템 기반 라우팅을 사용하며 레이아웃, 중첩 라우팅, 로딩 상태, 오류 처리 등을 지원합니다. 자세한 내용은 App Router 문서를 참고하세요.

앱 라우터: 가이드

가이드: AI 코딩 에이전트

원본 URL: https://nextjs.org/docs/app/guides/ai-agents

가이드: Analytics

최종 업데이트: 2026년 2월 20일

안내서: 인증

최종 업데이트: 2026년 2월 20일

가이드: Backend for Frontend

Next.js는 "Backend for Frontend" 패턴을 지원합니다. 이를 통해 공개 엔드포인트를 만들어 HTTP 요청을 처리하고 HTML뿐 아니라 모든 콘텐츠 유형을 반환할 수 있습니다. 또한 데이터 소스에 접근하고 원격 데이터를 업데이트하는 등의 사이드 이펙...

가이드: 캐싱

Next.js는 렌더링 작업과 데이터 요청을 캐싱해 애플리케이션 성능을 향상시키고 비용을 절감합니다. 이 페이지에서는 Next.js 캐싱 메커니즘, 이를 구성할 수 있는 API, 그리고 서로 간의 상호 작용을 심층적으로 살펴봅니다.

가이드: CI 빌드 캐싱

빌드 성능을 높이기 위해 Next.js는 빌드 간에 공유되는 캐시를 에 저장합니다.

가이드: Content Security Policy

CSP를 사용하면 개발자는 콘텐츠 소스, 스크립트, 스타일시트, 이미지, 폰트, 객체, 미디어(오디오, 비디오), iframe 등에서 허용되는 출처를 지정할 수 있습니다.

가이드: CSS-in-JS

> 경고: Server Components와 Streaming 같은 최신 React 기능과 함께 CSS-in-JS를 사용하려면 라이브러리 작성자가 동시 렌더링을 포함한 최신 React 버전을 지원해야 합니다.

가이드: Custom Server

Next.js는 기본적으로 와 함께 자체 서버를 포함합니다. 기존 백엔드를 보유하고 있어도 Next.js와 함께 사용할 수 있으며, 이는 커스텀 서버가 아닙니다. 커스텀 Next.js 서버를 사용하면 맞춤 패턴을 위해 서버를 프로그래밍 방식으로 시작할 수 있습니다. 대...

가이드: 데이터 보안

원본 URL: https://nextjs.org/docs/app/guides/data-security

가이드: 디버깅

이 문서는 VS Code 디버거, Chrome DevTools, Firefox DevTools를 사용해 전체 소스맵을 지원하는 Next.js 프런트엔드 및 백엔드 코드를 디버깅하는 방법을 설명합니다.

가이드: Draft Mode

이 문서는 Draft Mode를 활성화하고 사용하는 방법을 안내합니다.

가이드: 환경 변수

최종 업데이트: 2026년 2월 20일

가이드: 폼

React Server Actions는 서버에서 실행되는 Server Functions입니다. 서버 및 클라이언트 컴포넌트에서 호출해 폼 제출을 처리할 수 있습니다. 이 가이드는 Server Actions를 사용해 Next.js에서 폼을 만드는 과정을 단계별로 안내합니...

가이드: ISR

Incremental Static Regeneration(ISR)은 다음을 가능하게 합니다:

가이드: Instrumentation

Instrumentation은 애플리케이션에 모니터링과 로깅 도구를 통합하도록 코드를 사용하는 과정입니다. 이를 통해 애플리케이션의 성능과 동작을 추적하고, 프로덕션 환경에서 문제를 디버그할 수 있습니다.

가이드: 국제화

원본 URL: https://nextjs.org/docs/app/guides/internationalization

가이드: JSON-LD

원본 URL: https://nextjs.org/docs/app/guides/json-ld

가이드: Lazy Loading

Next.js의 Lazy loading은 라우트를 렌더링하는 데 필요한 JavaScript 양을 줄여 애플리케이션의 초기 로딩 성능을 향상시킵니다.

가이드: 개발 환경

Next.js는 뛰어난 개발자 경험을 제공하도록 설계되었습니다. 애플리케이션이 커질수록 로컬 개발 중 컴파일 속도가 느려질 수 있습니다. 이 가이드는 일반적인 컴파일 시간 성능 문제를 식별하고 해결하도록 도와줍니다.

가이드: Next.js MCP Server

Next.js 16 이상에는 MCP 지원이 포함되어 있어 코딩 에이전트가 애플리케이션 내부를 실시간으로 조회할 수 있습니다. 이 기능을 사용하려면 패키지를 설치하세요.

가이드: MDX

Next.js는 애플리케이션 내부의 로컬 MDX 콘텐츠는 물론, 서버에서 동적으로 가져온 원격 MDX 파일도 지원합니다. Next.js 플러그인은 마크다운과 React 컴포넌트를 HTML로 변환하며, App Router에서 기본인 서버 컴포넌트에서도 사용할 수 있도록 ...

가이드: 메모리 사용량

애플리케이션이 성장하고 기능이 풍부해질수록 로컬 개발이나 프로덕션 빌드 시 더 많은 리소스를 요구할 수 있습니다.

가이드: 마이그레이션

마이그레이션: App Router

이 가이드를 통해 다음을 수행할 수 있습니다:

마이그레이션: Create React App

이 가이드는 기존 Create React App(CRA) 사이트를 Next.js로 마이그레이션하는 데 도움이 됩니다.

마이그레이션: Vite

이 가이드는 기존 Vite 애플리케이션을 Next.js로 이전하는 과정을 안내합니다.

가이드: 멀티 테넌트

여러 테넌트를 제공하는 단일 Next.js 애플리케이션을 구축하려는 경우, 권장 아키텍처를 보여 주는 예제를 준비해 두었습니다.

가이드: 멀티 존

멀티 존은 하나의 도메인에 있는 대형 애플리케이션을 경로 집합별로 서비스하는 더 작은 Next.js 애플리케이션으로 분리하는 마이크로 프론트엔드 접근 방식입니다. 애플리케이션의 다른 페이지들과 연관성이 낮은 페이지 묶음이 있을 때 유용합니다. 해당 페이지를 별도의 존(...

가이드: OpenTelemetry

관측 가능성은 Next.js 앱의 동작과 성능을 이해하고 최적화하는 데 매우 중요합니다.

가이드: 패키지 번들링

번들링은 애플리케이션 코드와 그 의존성을 클라이언트와 서버를 위한 최적화된 출력 파일로 결합하는 과정입니다. 번들이 작아지면 로드 속도가 빨라지고 자바스크립트 실행 시간이 줄어들며 Core Web Vitals가 개선되고 서버 콜드 스타트 시간도 감소합니다.

가이드: Prefetching

원본 URL: https://nextjs.org/docs/app/guides/prefetching

가이드: 프로덕션

원본 URL: https://nextjs.org/docs/app/guides/production-checklist

가이드: PWAs

Progressive Web Application(PWA)는 웹 애플리케이션의 도달성과 접근성을 네이티브 모바일 앱의 기능 및 사용자 경험과 결합합니다. Next.js를 사용하면 여러 코드베이스나 앱 스토어 승인 없이 모든 플랫폼에서 매끄럽고 앱 같은 경험을 제공하는 ...

가이드: 공개 페이지

공개 페이지는 모든 사용자에게 동일한 콘텐츠를 보여줍니다. 대표적인 예로 랜딩 페이지, 마케팅 페이지, 제품 페이지가 있습니다.

가이드: Redirecting

원본 URL: https://nextjs.org/docs/app/guides/redirecting

가이드: Sass

Next.js는 패키지를 설치한 뒤 와 확장자를 모두 활용하여 Sass와 통합할 수 있도록 기본 지원합니다. CSS Modules와 또는 확장자를 사용하면 컴포넌트 수준의 Sass를 사용할 수 있습니다.

가이드: 스크립트

여러 경로에서 서드파티 스크립트를 로드하려면 를 import한 뒤 레이아웃 컴포넌트에 직접 포함하세요:

가이드: Self-Hosting

Next.js 앱을 배포할 때는 인프라에 따라 다양한 기능을 어떻게 처리할지 구성하고 싶을 수 있습니다.

가이드: SPAs

Next.js는 단일 페이지 애플리케이션(SPA) 구축을 완전히 지원합니다.

가이드: 정적 내보내기

Next.js는 정적 사이트 또는 Single-Page Application(SPA)으로 시작한 뒤, 나중에 서버가 필요한 기능으로 선택적으로 업그레이드할 수 있게 해 줍니다.

가이드: Tailwind CSS v3

이 가이드는 Next.js 애플리케이션에 Tailwind CSS v3를 설치하는 방법을 단계별로 설명합니다.

가이드: 테스트

React와 Next.js에는 작성 목적과 활용 사례가 서로 다른 다양한 테스트 유형이 있습니다. 이 페이지에서는 애플리케이션을 테스트할 때 사용할 수 있는 테스트 유형과 일반적인 도구를 개괄합니다.

테스트: Cypress

> * Cypress 13.6.3 미만 버전은 가 있는 TypeScript 5를 지원하지 않습니다. 하지만 이 문제는 Cypress 13.6.3 이상 버전에서 해결되었습니다. cypress v13.6.3

테스트: Jest

Jest와 React Testing Library는 단위 테스트와 스냅샷 테스트에서 자주 함께 사용됩니다. 이 가이드는 Next.js에서 Jest를 설정하고 첫 번째 테스트를 작성하는 방법을 안내합니다.

테스트: Playwright

Playwright는 하나의 API로 Chromium, Firefox, WebKit을 자동화할 수 있는 테스트 프레임워크입니다. 이를 사용해 엔드 투 엔드(E2E) 테스트를 작성할 수 있습니다. 이 가이드는 Playwright를 Next.js와 함께 설정하고 첫 번째 ...

테스트: Vitest

Vitest와 React Testing Library는 단위 테스트에 자주 함께 사용됩니다. 이 가이드에서는 Next.js에서 Vitest를 설정하고 첫 번째 테스트를 작성하는 방법을 설명합니다.

가이드: 서드파티 라이브러리

원본 URL: https://nextjs.org/docs/app/guides/third-party-libraries

가이드: 업그레이드

버전별 가이드를 따라 최신 Next.js 버전으로 업그레이드하는 방법을 알아보세요:

업그레이드: Codemods

Codemod은 코드베이스에 대해 프로그램 방식으로 실행되는 변환입니다. 이를 통해 모든 파일을 수동으로 훑어보지 않고도 대규모 변경을 자동으로 적용할 수 있습니다.

업그레이드: 버전 14

선호하는 패키지 관리자를 사용해 아래 명령어를 실행하면 Next.js 14 버전으로 업데이트할 수 있습니다.

업그레이드: 버전 15

Next.js 버전 15로 업데이트하려면 코데모드를 사용할 수 있습니다:

업그레이드: 버전 16

각 코딩 에이전트에 대해 MCP 클라이언트에 다음 구성을 추가하세요. 구성 세부 정보는 이 섹션을 참고하세요.

가이드: 비디오

이 페이지에서는 Next.js 애플리케이션에서 비디오를 사용하는 방법을 설명하며, 성능에 영향을 주지 않고 비디오 파일을 저장하고 표시하는 방법을 보여 줍니다.

Next.js 문서: 아키텍처

Next.js 아키텍처와 내부 동작 방식을 알아보세요.

아키텍처: 접근성

Next.js 팀은 모든 개발자(및 최종 사용자)가 Next.js를 활용할 수 있도록 접근성을 보장하기 위해 노력하고 있습니다. 기본적으로 Next.js에 접근성 기능을 추가해 두어 모두에게 더 포괄적인 웹을 제공하는 것이 목표입니다.

아키텍처: Fast Refresh

Fast Refresh는 Next.js에 통합된 React 기능으로, 파일을 저장할 때 임시 클라이언트 상태를 유지한 채 브라우저 페이지를 라이브 리로드할 수 있게 해줍니다. 9.4 이상의 모든 Next.js 애플리케이션에서 기본 활성화되어 있으며, Fast Refre...

아키텍처: Next.js Compiler

Rust로 작성되고 SWC를 사용하는 Next.js Compiler는 Next.js가 프로덕션용 JavaScript 코드를 변환하고 최소화할 수 있게 해 줍니다. 이는 개별 파일 처리에 사용되던 Babel과 출력 번들을 최소화하던 Terser를 대체합니다.

아키텍처: 지원되는 브라우저

Next.js는 모던 브라우저를 추가 설정 없이 지원합니다.

Next.js 문서: 커뮤니티

원본 URL: https://nextjs.org/docs/community

커뮤니티: 기여 가이드

Next.js 문서 기여 가이드에 오신 것을 환영합니다! 함께하게 되어 기쁩니다.

커뮤니티: Rspack

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 직접 사용해 보고 GitHub에서 피드백을 공유해 주세요.

Next.js에서 "App Container Deprecated" 오류 해결

이 문서는 사용자 정의 App 컴포넌트를 업데이트하여 Next.js의 "App Container Deprecated" 오류를 해결하는 방법을 안내합니다.

외부에서 캐시되지 않은 데이터에 접근했습니다

기능을 활성화하면 Next.js는 모든 사용자 요청마다 접근해야 하는 데이터를 기다리는 컴포넌트를 부모 경계 안에 둘 것으로 예상합니다. 이 요구 사항의 목적은 Next.js가 해당 데이터를 접근하고 렌더링하는 동안 유용한 폴백 UI를 제공하려는 것입니다.

퍼블릭 파일과 페이지 파일 충돌

퍼블릭 파일 중 하나가 페이지 파일과 동일한 경로를 갖고 있어 지원되지 않습니다. 하나의 리소스만 해당 URL에 존재할 수 있으므로 퍼블릭 파일과 페이지 파일은 각각 고유해야 합니다.

Cache Components에서 비어 있는 generateStaticParams

Next.js 애플리케이션에서 Cache Components를 사용 중이며, 함수 중 하나가 빈 배열을 반환하여 빌드 오류가 발생했습니다.

Google Font Display

> Google Fonts에서 font-display 동작을 강제합니다.

Google Font Preconnect

> 참고: Next.js는 버전 이후 자동으로 를 추가합니다.

인라인 스크립트 ID

> 인라인 콘텐츠가 있는 컴포넌트에는 속성을 강제합니다.

미들웨어 업그레이드 가이드

Middleware를 GA(General Availability)로 개선하는 과정에서, 여러분의 피드백을 바탕으로 Middleware API(및 애플리케이션에서 Middleware를 정의하는 방식)에 몇 가지 변경을 적용했습니다.

useSearchParams에서 Suspense 경계 누락

원본 URL: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

next/dynamic는 동시에 여러 모듈을 로드하는 기능을 더 이상 지원하지 않습니다

에서 여러 모듈을 한 번에 로드하는 기능이 React 구현( 및 )에 더 가깝게 맞추기 위해 더 이상 지원되지 않습니다.

"use cache"에서 cookies() 또는 headers()에 접근할 수 없음

함수 하나가 주석이 달린 함수의 범위 안에서 현재 들어오는 요청을 읽으려고 했습니다. 이렇게 하면 요청마다 캐시가 무효화되어 의도한 동작이 아니기 때문에 지원되지 않습니다.

@next/third-parties/google를 통한 Next.js에서의 Google Analytics 사용

> Google Analytics와 Tag Manager를 위해 인라인 스크립트를 사용할 때는 를 우선적으로 사용하세요.

모듈 변수 할당 금지

변수에 어떤 값을 할당하고 있습니다. 변수는 이미 사용 중이므로 여기에 값을 다시 할당하면 오류가 발생할 가능성이 매우 높습니다.

비동기 Client Component 금지

원본 URL: https://nextjs.org/docs/messages/no-async-client-component

문서 밖에서 Before Interactive Script 사용 금지

> 또는 외부에서 의 전략 사용을 방지합니다.

캐시가 감지되지 않음

연속 통합(CI) 환경에서 Next.js 빌드가 트리거됐지만, 캐시가 감지되지 않았습니다.

CSS 태그 없음

> 수동 스타일시트 태그 추가를 방지하세요.

페이지에서 Document 가져오기 금지

를 (TypeScript를 사용하는 경우 ) 외부의 페이지에서 가져왔습니다. 이는 애플리케이션에서 예기치 않은 문제를 유발할 수 있습니다.

중복된 Head 없음

사용자 정의 문서에서 컴포넌트를 두 번 이상 사용했습니다. 이는 애플리케이션에서 예상치 못한 동작을 일으킬 수 있습니다.

head 요소 없음

페이지 수준 메타데이터를 포함하기 위해 요소를 사용했지만, 이는 Next.js 애플리케이션에서 예상치 못한 동작을 일으킬 수 있습니다. 대신 Next.js에 내장된 컴포넌트를 사용하세요.

Document에서 Head 임포트 금지

원본 URL: https://nextjs.org/docs/messages/no-head-import-in-document

페이지용 HTML 링크 없음

원본 URL: https://nextjs.org/docs/messages/no-html-link-for-pages

img 요소 없음

> 느린 LCP와 더 높은 대역폭 사용 때문에 요소 사용을 방지합니다.

페이지 전용 커스텀 폰트 없음

> 페이지에만 적용되는 커스텀 폰트를 방지하세요.

헤드에서 Script 컴포넌트 사용 금지

> 컴포넌트 안에서는 를 사용하지 마세요.

_document에서 styled-jsx 사용 금지

> 에서 를 사용하는 것을 방지하세요.

동기 스크립트 없음

동기 스크립트를 사용하면 웹페이지 성능에 영향을 줄 수 있습니다.

문서 헤드에 제목 없음

> 의 컴포넌트에서 사용을 방지하십시오.

원치 않는 Polyfill.io 없음

> Polyfill.io에서 중복된 폴리필을 방지하세요.

동적 API는 비동기입니다

특정 API에 동기적으로 접근하면 이제 경고가 발생하는 이유를 살펴보세요.

url은 더 이상 사용되지 않습니다

이 기능이 사라지는 이유는 모든 것을 매우 예측 가능하고 명시적으로 만들고자 하기 때문입니다. 어디선가 갑자기 나타나는 마법 같은 url 속성은 이러한 목표에 도움이 되지 않습니다.

Webpack 5 도입

Next.js는 기본 컴파일러로 webpack 5를 채택했습니다. webpack 4에서 5로 전환이 최대한 원활하도록 많은 노력을 기울였습니다.

Next.js 문서: Pages Router

원본 URL: https://nextjs.org/docs/pages

Pages Router: API Reference

API 참고: CLI

원본 URL: https://nextjs.org/docs/pages/api-reference/cli

CLI: create-next-app CLI

2026년 2월 20일에 마지막으로 업데이트됨

CLI: next CLI

Next.js CLI를 사용하면 애플리케이션을 개발하고, 빌드하고, 시작하는 등 다양한 작업을 수행할 수 있습니다.

API 레퍼런스: Components

컴포넌트: Font

모든 폰트 파일에 대해 자동 자체 호스팅이 내장되어 있습니다. 즉, 레이아웃 시프트 없이 웹 폰트를 최적으로 로드할 수 있습니다.

컴포넌트: Form

컴포넌트는 HTML 요소를 확장해 제출 시 클라이언트 측 내비게이션과 점진적 향상을 제공합니다.

구성 요소: Head

다음과 같이 페이지의 에 요소를 추가하는 내장 컴포넌트를 제공합니다:

컴포넌트: Image (Legacy)

이는 더 이상 권장되지 않는 레거시 API입니다. 하위 호환성을 위해 계속 지원됩니다.

Components: Image

Next.js Image 컴포넌트는 자동 이미지 최적화를 위해 HTML 요소를 확장합니다.

컴포넌트: Link

은 HTML 요소를 확장하여 prefetching과 라우트 간 클라이언트 내비게이션을 제공하는 React 컴포넌트입니다. Next.js에서 라우트 간 이동을 수행하는 기본 수단입니다.

구성 요소: Script

이 API 레퍼런스는 Script 컴포넌트에서 사용할 수 있는 props를 이해하는 데 도움을 줍니다. 기능과 사용법은 Optimizing Scripts 페이지를 참고하세요.

API Reference: 구성

구성: ESLint

Next.js는 애플리케이션에서 일반적인 문제를 쉽게 찾아낼 수 있도록 라는 ESLint 구성 패키지를 제공합니다. 이 패키지는 플러그인과 , 의 권장 규칙 세트를 함께 포함합니다.

구성: next.config.js 옵션

Next.js는 프로젝트 디렉터리 루트(예: 옆)에 있는 파일의 기본 내보내기를 통해 구성할 수 있습니다.

next.config.js 옵션: experimental.adapterPath

Next.js는 빌드 프로세스에 연결할 사용자 정의 어댑터를 생성할 수 있는 실험적 API를 제공합니다. 이는 Next.js 구성을 수정하거나 빌드 출력을 처리해야 하는 배포 플랫폼 또는 맞춤형 빌드 통합에 유용합니다.

next.config.js 옵션: allowedDevOrigins

Next.js는 개발 중 교차 출처 요청을 자동으로 차단하지 않지만, 향후 메이저 버전에서는 개발 모드에서 접근 가능한 내부 자산/엔드포인트에 대한 무단 요청을 방지하기 위해 기본적으로 차단할 예정입니다.

next.config.js 옵션: assetPrefix

> 주의 : Vercel에 배포하면 Next.js 프로젝트를 위한 전역 CDN이 자동으로 설정됩니다. Asset Prefix를 수동으로 설정할 필요가 없습니다.

next.config.js 옵션: basePath

Next.js 애플리케이션을 도메인의 하위 경로로 배포하려면 구성 옵션을 사용할 수 있습니다.

next.config.js 옵션: bundlePagesRouterDependencies

Pages Router 애플리케이션에서 서버 측 종속성을 자동으로 번들링합니다. App Router에서의 자동 종속성 번들링과 동일하게 동작합니다.

next.config.js 옵션: compress

기본적으로 Next.js는 또는 커스텀 서버를 사용할 때 렌더링된 콘텐츠와 정적 파일을 으로 압축합니다. 이는 압축을 별도로 구성하지 않은 애플리케이션을 위한 최적화입니다. 커스텀 서버를 통해 애플리케이션에 이미 압축이 구성되어 있다면 Next.js는 추가 압축을 적...

next.config.js Options: crossOrigin

옵션을 사용하면 와 컴포넌트가 생성하는 모든 태그에 속성을 추가하고, 크로스 오리진 요청을 어떻게 처리할지 정의할 수 있습니다.

next.config.js 옵션: deploymentId

옵션을 사용하면 배포에 대한 식별자를 설정할 수 있습니다. 이 식별자는 버전 스큐 보호와 롤링 배포 중 캐시 무효화에 사용됩니다.

next.config.js Options: devIndicators

는 개발 중에 보고 있는 현재 라우트에 대한 컨텍스트를 제공하는 화면 상의 인디케이터를 구성할 수 있게 합니다.

next.config.js 옵션: distDir

대신 사용할 사용자 지정 빌드 디렉터리 이름을 지정할 수 있습니다.

next.config.js 옵션: env

> Next.js 9.4 릴리스 이후로 환경 변수를 추가하는 경험이 더욱 직관적이고 편리해졌습니다. 직접 사용해 보세요!

next.config.js 옵션: exportPathMap

> 이 기능은 전용이며 현재 의 나 의 를 대신하도록 deprecated 상태입니다.

next.config.js 옵션: generateBuildId

Next.js는 애플리케이션에서 제공 중인 버전을 식별하기 위해 동안 ID를 생성합니다. 동일한 빌드를 사용해 여러 컨테이너를 부팅해야 합니다.

next.config.js Options: generateEtags

Next.js는 기본적으로 모든 페이지에 대해 etag를 생성합니다. 캐시 전략에 따라 HTML 페이지의 etag 생성을 비활성화하고 싶을 수 있습니다.

next.config.js 옵션: 헤더

헤더를 사용하면 특정 경로로 들어오는 요청에 대한 응답에 사용자 지정 HTTP 헤더를 설정할 수 있습니다.

next.config.js 옵션: httpAgentOptions

원본 URL: https://nextjs.org/docs/pages/api-reference/config/next-config-js/httpAgentOptions

next.config.js 옵션: images

최종 업데이트: 2026년 2월 20일

next.config.js Options: isolatedDevBuild

실험적 옵션인 는 개발 및 프로덕션 빌드 출력을 서로 다른 디렉터리로 분리합니다. 이 기능을 활성화하면 개발 서버()는 대신 에 출력을 기록하므로 와 를 동시에 실행할 때 충돌을 방지합니다.

next.config.js 옵션: onDemandEntries

Next.js는 개발 환경에서 서버가 빌드된 페이지를 메모리에 유지하거나 제거하는 방식을 제어할 수 있는 몇 가지 옵션을 제공합니다.

next.config.js 옵션: optimizePackageImports

이 기능은 현재 실험적이며 추후 변경될 수 있으므로 프로덕션에서는 권장되지 않습니다. 자유롭게 시도해 보고 GitHub에서 피드백을 공유해주세요.

next.config.js 옵션: output

빌드 중 Next.js는 각 페이지와 그 의존성을 자동으로 추적하여 애플리케이션을 프로덕션 버전으로 배포하는 데 필요한 모든 파일을 파악합니다.

next.config.js 옵션: pageExtensions

Next.js가 사용하는 기본 페이지 확장자(, , , )를 확장할 수 있습니다. 안에 구성을 추가하세요:

next.config.js 옵션: poweredByHeader

기본적으로 Next.js는 헤더를 추가합니다. 이를 비활성화하려면 를 열고 설정을 꺼 주세요:

next.config.js 옵션: productionBrowserSourceMaps

개발 중에는 소스 맵이 기본적으로 활성화됩니다. 프로덕션 빌드에서는 클라이언트에 소스가 유출되는 것을 막기 위해 비활성화되며, 구성 플래그로 명시적으로 옵트인하지 않는 한 그대로 유지됩니다.

next.config.js Options: experimental.proxyClientMaxBodySize

프록시를 사용할 때 Next.js는 요청 본문을 자동으로 복제해 메모리에 버퍼링하여, 프록시와 기본 라우트 처리기 모두에서 여러 번 읽을 수 있도록 합니다. 과도한 메모리 사용을 방지하기 위해 이 구성 옵션은 버퍼링되는 본문의 크기 제한을 설정합니다.

next.config.js 옵션: reactStrictMode

> 알아두면 좋아요 : Next.js 13.5.1부터 라우터에서는 Strict Mode가 기본으로 이므로 위 설정은 에만 필요합니다. 로 설정하면 Strict Mode를 비활성화할 수도 있습니다.

next.config.js 옵션: redirects

리디렉션을 사용하면 들어오는 요청 경로를 다른 목적지 경로로 전달할 수 있습니다.

next.config.js Options: rewrites

Rewrites를 사용하면 들어오는 요청 경로를 다른 목적지 경로로 매핑할 수 있습니다.

next.config.js 옵션: serverExternalPackages

이러한 페이지는 이후 네이티브 Node.js 를 사용해 의존성을 해석합니다.

next.config.js Options: trailingSlash

기본적으로 Next.js는 슬래시로 끝나는 URL을 슬래시가 없는 대응 URL로 리다이렉트합니다. 예를 들어 는 으로 리다이렉트됩니다. 이 동작을 반대로 설정해, 슬래시 없이 끝나는 URL을 슬래시가 붙은 대응 URL로 리다이렉트하도록 구성할 수 있습니다.

next.config.js 옵션: transpilePackages

Next.js는 로컬 패키지(예: 모노레포)나 외부 의존성()에서 오는 의존성을 자동으로 트랜스파일하고 번들링할 수 있습니다. 이는 패키지를 대체합니다.

next.config.js 옵션: turbopack

이 기능은 현재 실험 단계이며 언제든지 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 직접 사용해 보고 GitHub에서 피드백을 공유하세요.

next.config.js 옵션: typescript

의 옵션으로 TypeScript 동작을 구성하세요:

next.config.js Options: urlImports

이 기능은 현재 실험 단계이며 변경될 수 있으므로 프로덕션 사용은 권장되지 않습니다. 직접 사용해 보고 GitHub에 피드백을 남겨 주세요.

next.config.js 옵션: useLightningcss

이 기능은 현재 실험적이며 변경될 수 있으므로 프로덕션 환경에서는 권장되지 않습니다. 사용해 보고 GitHub에서 피드백을 공유해 주세요.

next.config.js 옵션: webpack

> 알아두면 좋아요: webpack 구성 변경은 semver 보장에 포함되지 않으므로 위험을 감수하고 진행하세요

next.config.js 옵션: webVitalsAttribution

원본 URL: https://nextjs.org/docs/pages/api-reference/config/next-config-js/webVitalsAttribution

구성: TypeScript

Next.js에는 기본적으로 TypeScript가 포함되어 있어 으로 새 프로젝트를 만들 때 필요한 패키지를 자동으로 설치하고 적절한 설정을 구성합니다.

API 레퍼런스: Edge Runtime

Next.js 애플리케이션에서는 두 가지 서버 런타임을 사용할 수 있습니다.

API Reference: 파일 시스템 규칙

원본 URL: https://nextjs.org/docs/pages/api-reference/file-conventions

파일 시스템 규칙: instrumentation.js

원본 URL: https://nextjs.org/docs/pages/api-reference/file-conventions/instrumentation

파일 시스템 규칙: Proxy

> 참고: 파일 규칙은 더 이상 사용되지 않으며 로 이름이 변경되었습니다. 자세한 내용은 Proxy로의 마이그레이션을 참고하세요.

파일 시스템 규칙: public

Next.js는 루트 디렉터리의 폴더 아래에서 이미지와 같은 정적 파일을 제공할 수 있습니다. 안의 파일은 기본 URL()을 기준으로 코드에서 참조할 수 있습니다.

파일 시스템 규칙: src 디렉터리

프로젝트 루트에 있는 Next.js의 특수 또는 디렉터리를 사용하는 대신, Next.js는 애플리케이션 코드를 폴더 아래에 배치하는 일반적인 패턴도 지원합니다.

API 레퍼런스: 함수

함수: getInitialProps

> 알아두면 좋아요 : 는 레거시 API입니다. 대신 또는 를 사용하는 것을 권장합니다.

함수: getServerSideProps

페이지에서 (서버 사이드 렌더링)라는 함수를 내보내면, Next.js는 각 요청마다 가 반환한 데이터를 사용해 이 페이지를 사전 렌더링합니다. 자주 변경되는 데이터를 가져와 페이지가 최신 데이터를 보여 주도록 하고 싶을 때 유용합니다.

함수: getStaticPaths

pages/repo/[name].tsx

Functions: getStaticProps

라는 함수를 export하면 함수가 반환한 props를 사용해 빌드 시점에 페이지를 사전 렌더링합니다:

함수: NextRequest

NextRequest는 Web Request API를 확장하여 추가 편의 메서드를 제공합니다.

함수: NextResponse

NextResponse는 추가 편의 메서드로 Web Response API를 확장합니다.

함수: useParams

는 현재 URL이 채운 라우트의 동적 매개변수를 읽을 수 있는 훅입니다.

함수: useReportWebVitals

훅을 사용하면 Core Web Vitals를 보고할 수 있으며 분석 서비스와 함께 활용할 수 있습니다.

함수: useRouter

원본 URL: https://nextjs.org/docs/pages/api-reference/functions/use-router

함수: useSearchParams

는 현재 URL의 쿼리 문자열을 읽을 수 있게 해 주는 훅입니다.

함수: userAgent

도우미는 요청에서 사용자 에이전트 객체와 상호 작용할 수 있도록 Web Request API를 확장하여 추가 속성과 메서드를 제공합니다.

API Reference: Turbopack

Turbopack은 Rust로 작성된 증분 번들러로, JavaScript와 TypeScript에 최적화되어 있으며 Next.js에 내장되어 있습니다. Pages Router와 App Router 모두에서 Turbopack을 사용하면 훨씬 빠른 로컬 개발 환경을 경험할 ...

페이지 라우터: 애플리케이션 구축

애플리케이션 빌드: Configuring

Next.js는 프로젝트를 특정 요구 사항에 맞게 사용자 지정할 수 있도록 합니다. 여기에는 TypeScript, ESLint 등과의 통합뿐 아니라 절대 경로 임포트와 환경 변수와 같은 내부 구성 옵션이 포함됩니다.

애플리케이션 빌드: 데이터 가져오기

Next.js의 데이터 가져오기는 애플리케이션의 사용 사례에 따라 다양한 방식으로 콘텐츠를 렌더링할 수 있게 해 줍니다. 여기에는 서버 사이드 렌더링 또는 정적 생성을 통한 사전 렌더링과, 런타임에 증분 정적 재생성으로 콘텐츠를 업데이트하거나 생성하는 방법이 포함됩니다...

데이터 페칭: 클라이언트 측 페칭

클라이언트 측 데이터 페칭은 페이지가 SEO 인덱싱을 필요로 하지 않거나, 데이터를 사전 렌더링할 필요가 없거나, 페이지 콘텐츠를 자주 업데이트해야 할 때 유용합니다. 서버 측 렌더링 API와 달리 클라이언트 측 데이터 페칭은 컴포넌트 수준에서 사용할 수 있습니다.

데이터 페칭: getServerSideProps

는 Next.js 함수로, 요청 시점에 데이터를 가져와 페이지 내용을 렌더링할 때 사용할 수 있습니다.

데이터 패칭: getStaticPaths

페이지가 동적 라우트를 사용하고 를 정의한다면, 정적으로 생성할 경로 목록을 지정해야 합니다.

데이터 페칭: getStaticProps

페이지에서 (정적 사이트 생성)라는 함수를 export하면, Next.js는 빌드 시점에 가 반환한 props를 사용해 해당 페이지를 사전 렌더링합니다.

렌더링: 자동 정적 최적화

Next.js는 페이지에 차단형 데이터 요구 사항이 없으면 해당 페이지가 정적(사전 렌더링 가능)이라고 자동으로 판단합니다. 이 판단은 페이지에 와 가 없는지 여부로 이루어집니다.

렌더링: 클라이언트 사이드 렌더링 (CSR)

최종 업데이트: 2026년 2월 20일

렌더링: 서버 사이드 렌더링 (SSR)

> "SSR" 또는 "동적 렌더링"이라고도 합니다.

렌더링: Static Site Generation (SSG)

페이지가 Static Generation 을 사용하면 페이지 HTML은 빌드 시점 에 생성됩니다. 즉, 프로덕션 환경에서는 를 실행할 때 페이지 HTML이 생성됩니다. 이 HTML은 각 요청마다 재사용되며 CDN에 캐싱할 수 있습니다.

애플리케이션 빌드: 라우팅

원본 URL: https://nextjs.org/docs/pages/building-your-application/routing

라우팅: API Routes

> 알아두면 좋아요 : App Router를 사용하는 경우 API Routes 대신 Server Components 또는 Route Handlers를 사용할 수 있습니다.

라우팅: Custom App

Next.js는 컴포넌트를 사용해 페이지를 초기화합니다. 이를 오버라이드해 페이지 초기화를 제어하면 다음을 수행할 수 있습니다.

라우팅: Custom Document

커스텀 는 Page를 렌더링할 때 사용되는 및 태그를 업데이트할 수 있습니다.

라우팅: 사용자 정의 오류

404 페이지는 자주 접근될 수 있습니다. 방문마다 오류 페이지를 서버 렌더링하면 Next.js 서버의 부하가 증가하여 비용 증가와 느린 경험으로 이어질 수 있습니다.

Routing: Dynamic Routes

미리 정확한 세그먼트 이름을 알지 못하고 동적 데이터에서 라우트를 생성하려면, 요청 시점에 채워지거나 빌드 시점에 프리렌더링되는 Dynamic Segment를 사용할 수 있습니다.

라우팅: 연결 및 내비게이션

Next.js 라우터를 사용하면 단일 페이지 애플리케이션과 유사하게 페이지 간 클라이언트 사이드 라우트 전환을 수행할 수 있습니다.

라우팅: 페이지와 레이아웃

Pages Router는 페이지 개념을 기반으로 한 파일 시스템 기반 라우터를 제공합니다.

페이지 라우터: 시작하기

시작하기: CSS

Next.js는 다음과 같이 CSS를 사용해 애플리케이션을 스타일링하는 여러 방법을 제공합니다.

시작하기: 배포

Next.js는 Node.js 서버, Docker 컨테이너, 정적 내보내기, 또는 다양한 플랫폼에 맞춘 어댑터 형태로 배포할 수 있습니다.

시작하기: 폰트

이 모듈에는 모든 폰트 파일에 대한 내장 셀프 호스팅 기능이 포함되어 있어, 레이아웃 시프트 없이 웹 폰트를 최적으로 로드할 수 있습니다.

시작하기: Images

Next.js 컴포넌트는 HTML 요소를 확장해 다음을 제공합니다:

시작하기: 설치

시작하기 전에 개발 환경이 다음 요구 사항을 충족하는지 확인하세요.

시작하기: 프로젝트 구조

이 페이지는 Next.js의 모든 폴더 및 파일 규칙과 프로젝트 구성에 대한 권장 사항을 개괄합니다.

Pages Router: 가이드

가이드: Analytics

최종 업데이트: 2026년 2월 20일

가이드: 인증

인증을 이해하는 것은 애플리케이션 데이터를 보호하는 데 필수적입니다. 이 페이지에서는 인증을 구현할 때 사용할 React 및 Next.js 기능을 안내합니다.

가이드: Babel

Next.js는 React 애플리케이션과 서버 측 코드를 컴파일하는 데 필요한 모든 항목을 포함한 프리셋을 앱에 기본 제공합니다. 그러나 기본 Babel 구성을 확장하고 싶다면 그렇게 할 수도 있습니다.

가이드: CI Build Caching

빌드 성능을 개선하기 위해 Next.js는 빌드 간에 공유되는 캐시를 에 저장합니다.

가이드: Content Security Policy

최종 업데이트: 2026년 2월 20일

Guides: CSS-in-JS

기존 CSS-in-JS 솔루션은 모두 사용할 수 있습니다. 가장 간단한 방법은 인라인 스타일입니다:

가이드: Custom Server

Next.js는 기본적으로 와 함께 자체 서버를 포함합니다. 기존 백엔드가 있더라도 Next.js와 함께 사용할 수 있으며(이 경우 커스텀 서버가 아님) 커스텀 Next.js 서버를 통해 특정 패턴에 맞춰 프로그래밍 방식으로 서버를 시작할 수 있습니다. 대부분의 경우 ...

가이드: 디버깅

이 문서는 VS Code 디버거, Chrome DevTools, Firefox DevTools를 이용해 소스 맵을 온전히 활용하면서 Next.js 프런트엔드와 백엔드 코드를 디버깅하는 방법을 설명합니다.

가이드: 드래프트 모드

정적 생성은 페이지가 헤드리스 CMS에서 데이터를 가져올 때 유용합니다. 그러나 헤드리스 CMS에서 초안을 작성하면서 즉시 페이지에서 보고 싶다면 적합하지 않습니다. 이런 경우에는 Next.js가 빌드 시점이 아니라 요청 시점에 페이지를 렌더링하고, 게시본 대신 초안 ...

가이드: 환경 변수

Next.js는 환경 변수를 위한 기본 제공 지원을 제공하며, 다음 작업을 수행할 수 있습니다.

가이드: Forms

최종 업데이트: 2026년 2월 20일

가이드: ISR

증분 정적 재생성(ISR)을 사용하면 다음을 수행할 수 있습니다.

가이드: 계측

계측은 코드를 사용해 모니터링 및 로깅 도구를 애플리케이션에 통합하는 과정입니다. 이를 통해 애플리케이션의 성능과 동작을 추적하고, 프로덕션 환경에서 발생하는 문제를 디버깅할 수 있습니다.

가이드: 국제화

Next.js는 부터 국제화(i18n) 라우팅을 기본 지원합니다. 로케일 목록, 기본 로케일, 도메인별 로케일을 지정하면 Next.js가 라우팅을 자동으로 처리합니다.

가이드: 지연 로딩

Next.js의 지연 로딩은 경로를 렌더링하는 데 필요한 JavaScript 양을 줄여 애플리케이션의 초기 로딩 성능을 향상합니다.

가이드: MDX

Next.js는 애플리케이션 내부의 로컬 MDX 콘텐츠뿐 아니라 서버에서 동적으로 가져오는 원격 MDX 파일도 지원합니다. Next.js 플러그인은 마크다운과 React 컴포넌트를 HTML로 변환하며, App Router에서 기본인 서버 컴포넌트 사용도 지원합니다.

가이드: 마이그레이션

마이그레이션: App Router

원본 URL: https://nextjs.org/docs/pages/guides/migrating/app-router-migration

마이그레이션: Create React App

이 가이드는 기존 Create React App(CRA) 사이트를 Next.js로 마이그레이션하는 방법을 설명합니다.

마이그레이션: Vite

이 가이드는 기존 Vite 애플리케이션을 Next.js로 마이그레이션하는 과정을 안내합니다.

가이드: Multi-Zones

Multi-Zones는 하나의 도메인에서 큰 애플리케이션을 여러 개의 Next.js 애플리케이션으로 분리하여 각 애플리케이션이 특정 경로 집합을 서비스하도록 하는 마이크로 프런트엔드 접근 방식입니다. 이는 애플리케이션 내의 다른 페이지와 관련 없는 페이지 모음을 다룰 ...

안내서: OpenTelemetry

관측 가능성은 Next.js 앱의 동작과 성능을 이해하고 최적화하는 데 필수적입니다.

가이드: 패키지 번들링

번들링은 애플리케이션 코드와 그 의존성을 클라이언트와 서버용으로 최적화된 출력 파일로 결합하는 과정입니다. 번들이 작을수록 로딩 속도가 빨라지고 JavaScript 실행 시간이 줄어들며 Core Web Vitals가 개선되고 서버 콜드 스타트 시간이 단축됩니다.

가이드: PostCSS

Next.js는 내장 CSS 지원을 위해 CSS를 PostCSS로 컴파일합니다.

가이드: Preview Mode

이는 레거시 API이며 더 이상 권장되지 않습니다. 하위 호환성을 위해 계속 지원됩니다.

가이드: 프로덕션

Next.js 애플리케이션을 프로덕션에 배포하기 전, 최상의 사용자 경험·성능·보안을 위해 적용을 고려해야 하는 최적화와 패턴이 있습니다.

가이드: 리디렉션

Next.js에서 리디렉션을 처리하는 방법은 몇 가지가 있습니다. 이 페이지에서는 사용 가능한 옵션, 활용 사례, 그리고 대량의 리디렉션을 관리하는 방법을 살펴봅니다.

가이드: Sass

Next.js는 와 확장자를 사용하는 패키지를 설치하면 Sass 통합을 기본 지원합니다. CSS Modules와 또는 확장을 통해 컴포넌트 단위의 Sass를 사용할 수 있습니다.

가이드: 스크립트

모든 라우트에서 서드파티 스크립트를 로드하려면 를 임포트한 뒤 사용자 정의 에 스크립트를 직접 포함하세요:

가이드: 셀프 호스팅

Next.js 앱을 배포할 때는 인프라에 따라 다양한 기능이 어떻게 처리될지 구성하고 싶을 수 있습니다.

안내서: Static Exports

Next.js는 정적 사이트 또는 단일 페이지 애플리케이션(SPA)으로 시작한 뒤, 서버가 필요한 기능을 나중에 선택적으로 도입할 수 있게 해줍니다.

가이드: Tailwind CSS

이 가이드는 Next.js 애플리케이션에 Tailwind CSS v3를 설치하는 방법을 안내합니다.

가이드: 테스트

React와 Next.js에서는 목적과 사용 사례가 다른 여러 종류의 테스트를 작성할 수 있습니다. 이 페이지는 애플리케이션을 테스트할 때 활용할 수 있는 테스트 유형과 널리 쓰이는 도구를 개괄합니다.

테스트: Cypress

> * Cypress 13.6.3 미만 버전은 설정에서 TypeScript 5를 지원하지 않습니다. 이 문제는 Cypress 13.6.3 이후 버전에서 해결되었습니다. cypress v13.6.3

테스트: Jest

Jest와 React Testing Library는 단위 테스트 및 스냅샷 테스트에 자주 함께 사용됩니다. 이 가이드는 Next.js와 Jest를 설정하고 첫 번째 테스트를 작성하는 방법을 보여줍니다.

테스트: Playwright

Playwright는 단일 API로 Chromium, Firefox, WebKit을 자동화할 수 있는 테스트 프레임워크입니다. End-to-End (E2E) 테스트를 작성할 때 사용할 수 있습니다. 이 가이드는 Next.js와 Playwright를 설정하고 첫 번째 테...

테스트: Vitest

Vitest와 React Testing Library는 단위 테스트에 자주 함께 사용됩니다. 이 가이드는 Next.js에서 Vitest를 설정하고 첫 번째 테스트를 작성하는 방법을 보여줍니다.

가이드: 서드파티 라이브러리

가 제공하는 모든 서드파티 통합은 성능과 사용 편의성을 위해 최적화되어 있습니다.

가이드: 업그레이드

버전별 가이드를 따라 최신 Next.js 버전으로 업그레이드하는 방법을 알아보세요.

업그레이드: Codemods

Codemod은 코드베이스에서 프로그램적으로 실행되는 변환으로, 모든 파일을 수동으로 확인하지 않아도 대규모 변경을 자동으로 적용할 수 있습니다.

업그레이드: 버전 10

버전 9와 10 사이에는 호환을 깨뜨리는 변경 사항이 없습니다.

업그레이드: 버전 11

버전 11로 업그레이드하려면 다음 명령을 실행하세요:

업그레이드: 버전 12

원본 URL: https://nextjs.org/docs/pages/guides/upgrading/version-12

업그레이드: 버전 13

선호하는 패키지 매니저에서 다음 명령을 실행해 Next.js 13 버전으로 업데이트하세요:

업그레이드: 버전 14

선호하는 패키지 관리자를 사용해 Next.js 버전 14로 업데이트하려면 다음 명령을 실행하세요.

업그레이드: 버전 9

버전 9로 업그레이드하려면 다음 명령을 실행하세요:

설치

Playwright Test는 최신 웹 앱을 위한 엔드 투 엔드 테스트 프레임워크입니다. 테스트 러너, 단언(assertion), 격리, 병렬화, 그리고 풍부한 도구를 함께 제공합니다. ...

접근성 테스트

Playwright를 사용하면 애플리케이션에서 다양한 유형의 접근성 문제를 테스트할 수 있습니다.

자동 대기

Playwright는 액션을 수행하기 전에 요소에 대해 다양한 실행 가능성 검사를 수행하여 액션이 예상대로 동작하도록 보장합니다. 관련된 모든 검사가 통과될 때까지 자동으로 대기한 뒤에만 요청된 액션을 수행합니다. 주어진 내에 필요한 검사가 통과하지 않으면 액션은 와...

API testing

Playwright can be used to get access to the REST API of your application.

Android

Playwright는 Android 자동화를 실험적으로 지원합니다. 여기에는 Android용 Chrome과 Android WebView가 포함됩니다.

AndroidDevice

추가: v1.9 androidDevice.close

AndroidInput

추가된 버전: v1.9 androidInput.drag

AndroidSocket

추가된 버전: v1.9 androidSocket.close

AndroidWebView

추가된 버전: v1.9 androidWebView.page

APIRequest

Web API 테스트에 사용할 수 있는 API를 제공합니다. 이 클래스는 APIRequestContext 인스턴스를 생성하는 데 사용되며, 생성된 인스턴스는 웹 요청 전송에 사용할 수 있습니다. 이 클래스의 인스턴스는 playwright.request를 통해 얻을 수 ...

APIRequestContext

이 API는 Web API 테스트에 사용됩니다. 이를 사용해 API 엔드포인트를 트리거하고, 마이크로서비스를 구성하며, e2e 테스트를 위한 환경 또는 서비스를 준비할 수 있습니다.

APIResponse

추가된 버전: v1.16 apiResponse.body

APIResponseAssertions

import { test, expect } from '@playwright/test';

Browser

Browser는 browserType.launch()를 통해 생성됩니다. Browser를 사용해 Page를 만드는 예시는 다음과 같습니다:

BrowserContext

BrowserContext는 여러 개의 독립적인 브라우저 세션을 운영할 수 있는 방법을 제공합니다.

BrowserServer

v1.9 이전에 추가됨: browserServer.close

BrowserType

BrowserType는 특정 브라우저 인스턴스를 실행하거나 기존 인스턴스에 연결하는 메서드를 제공합니다. 다음은 Playwright를 사용해 자동화를 구동하는 일반적인 예시입니다:

CDPSession

인스턴스는 원시 Chrome Devtools Protocol과 통신하는 데 사용됩니다:

Clock

시간 의존 동작을 정확히 시뮬레이션하는 것은 애플리케이션의 정확성을 검증하는 데 필수적입니다. 자세한 내용은 clock emulation을 참고하세요.

ConsoleMessage

// Listen for all console logs

Coverage

Coverage는 페이지에서 사용된 JavaScript 및 CSS 부분에 대한 정보를 수집합니다.

Dialog

const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.

Download

브라우저 컨텍스트에 속한 모든 다운로드 파일은 브라우저 컨텍스트가 닫힐 때 삭제됩니다.

Electron

Playwright는 Electron 자동화를 실험적으로 지원합니다. 네임스페이스는 다음을 통해 접근할 수 있습니다:

ElectronApplication

Electron 애플리케이션 표현입니다. electron.launch()을 사용해 애플리케이션 인스턴스를 얻을 수 있습니다. 이 인스턴스를 통해 Electron의 메인 프로세스를 제어하고 Electron 창도 다룰 수 있습니다:

ElementHandle

ElementHandle는 페이지 내 DOM 요소를 나타냅니다. ElementHandle은 page.$() 메서드로 생성할 수 있습니다.

FileChooser

// Start waiting for file chooser before clicking. Note no await.

Fixtures

Playwright Test는 test fixtures 개념을 기반으로 합니다. 테스트 픽스처는 각 테스트를 위한 환경을 설정하는 데 사용되며, 테스트에 필요한 것만 정확히 제공합니다.

Frame

항상 모든 시점에서 page는 page.mainFrame() 및 frame.childFrames() 메서드를 통해 현재 frame 트리를 노출합니다.

FrameLocator

FrameLocator는 페이지의 에 대한 뷰를 나타냅니다. 을 가져오고 해당 iframe 내에서 요소를 찾는 데 충분한 로직을 캡처합니다. FrameLocator는 locator.contentFrame(), page.frameLocator(), 또는 locator.f...

FullConfig

추가된 버전: v1.20 fullConfig.configFile

FullProject

테스트 프로젝트 구성의 런타임 표현입니다. 테스트에서는 testInfo.project 및 workerInfo.project를 통해 접근할 수 있으며, 테스트 리포터에도 전달됩니다. Playwright 구성 파일에서의 프로젝트 형식을 보려면 TestProject를 대신 ...

GenericAssertions

import { test, expect } from '@playwright/test';

JSHandle

JSHandle은 페이지 내 JavaScript 객체를 나타냅니다. JSHandle은 page.evaluateHandle() 메서드로 생성할 수 있습니다.

Keyboard

Keyboard는 가상 키보드를 관리하기 위한 API를 제공합니다. 상위 수준 API는 keyboard.type()이며, 원시 문자를 받아 페이지에서 적절한 , /, 이벤트를 생성합니다.

Location

추가된 버전: v1.10 location.column

Locator

Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page ...

LocatorAssertions

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

Logger

This class is deprecated. The logs pumped through this class are incomplete. Please use tracing instead.

Mouse

The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.

Page

Page provides methods to interact with a single tab in a Browser, or an extension background page in Chromium. One Browser instance might have multipl...

PageAssertions

The PageAssertions class provides assertion methods that can be used to make assertions about the Page state in the tests.

Playwright Library

Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright to drive automation:

PlaywrightAssertions

Playwright gives you Web-First Assertions with convenience methods for creating assertions that will wait and retry until the expected condition is me...

Reporter

Test runner notifies the reporter about various events during test execution. All methods of the reporter are optional.

Request

Whenever the page sends a request for a network resource the following sequence of events are emitted by Page:

Response

Added in: v1.15 response.allHeaders

Route

Whenever a network route is set up with page.route() or browserContext.route(), the object allows to handle the route.

Selectors

Selectors can be used to install custom selector engines. See extensibility for more information.

SnapshotAssertions

Playwright provides methods for comparing page and element screenshots with expected values stored in files.

Suite

is a group of tests. All tests in Playwright Test form the following hierarchy:

Playwright Test

Playwright Test provides a function to declare tests and function to write assertions.

TestCase

corresponds to every test() call in a test file. When a single test() is running in multiple projects or repeated multiple times, it will have multipl...

TestConfig

Playwright Test provides many options to configure how your tests are collected and executed, for example or . These options are described in the Tes...

TestError

Information about an error thrown during test execution.

TestInfo

contains information about currently running test. It is available to test functions, test.beforeEach(), test.afterEach(), test.beforeAll() and test.a...

TestInfoError

Information about an error thrown during test execution.

TestOptions

Playwright Test provides many options to configure test environment, Browser, BrowserContext and more.

TestProject

Playwright Test supports running multiple test projects at the same time. This is useful for running tests in multiple configurations. For example, co...

TestResult

A result of a single TestCase run.

TestStep

Represents a step in the [TestRun].

TestStepInfo

contains information about currently running test step. It is passed as an argument to the step function. provides utilities to control test step exe...

TimeoutError

TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. locator.waitFor() or browserType.launch().

Touchscreen

The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the touchscreen can only be used i...

Tracing

API for collecting and saving Playwright traces. Playwright traces can be opened in Trace Viewer after Playwright script runs.

Video

When browser context is created with the option, each page has a video object associated with it.

WebError

// Log all uncaught errors to the terminal

WebSocket

The WebSocket class represents WebSocket connections within a page. It provides the ability to inspect and manipulate the data being transmitted and r...

WebSocketRoute

Whenever a route is set up with page.routeWebSocket() or browserContext.routeWebSocket(), the object allows to handle the WebSocket, like an actual ...

Worker

The Worker class represents a WebWorker. event is emitted on the page object to signal a worker creation. event is emitted on the worker object when...

WorkerInfo

contains information about the worker that is running tests and is available to worker-scoped fixtures. is a subset of TestInfo that is available in ...

Snapshot testing

With Playwright's Snapshot testing you can assert the accessibility tree of a page against a predefined snapshot template.

Authentication

Playwright executes tests in isolated environments called browser contexts. This isolation model improves reproducibility and prevents cascading test ...

Best Practices

This guide should help you to make sure you are following our best practices and writing tests that are more resilient.

Isolation

Tests written with Playwright execute in isolated clean-slate environments called browser contexts. This isolation model improves reproducibility and ...

Browsers

Each version of Playwright needs specific versions of browser binaries to operate. You will need to use the Playwright CLI to install these browsers.

Canary releases

Playwright for Node.js has a canary releases system.

Chrome extensions

Extensions only work in Chromium when launched with a persistent context. Use custom browser args at your own risk, as some of them may break Playwrig...

Setting up CI

Playwright tests can be run on any CI provider. This guide covers one way of running tests on GitHub using GitHub Actions. If you would like to learn ...

Continuous Integration

Playwright tests can be executed in CI environments. We have created sample configurations for common CI providers.

Clock

Accurately simulating time-dependent behavior is essential for verifying the correctness of applications. Utilizing Clock functionality allows develop...

Generating tests

Playwright can generate tests automatically, providing a quick way to get started with testing. Codegen opens a browser window for interaction and the...

Test generator

Playwright comes with the ability to generate tests for you as you perform actions in the browser and is a great way to quickly get started with testi...

Debugging Tests

We recommend using the VS Code Extension for debugging for a better developer experience. With the VS Code extension you can debug your tests right in...

Dialogs

Playwright can interact with the web page dialogs such as , , as well as confirmation. For print dialogs, see Print.

Docker

This Docker image is published to Microsoft Artifact Registry.

Downloads

For every attachment downloaded by the page, page.on('download') event is emitted. All these attachments are downloaded into a temporary folder. You c...

Emulation

With Playwright you can test your app on any browser as well as emulate a real device such as a mobile phone or tablet. Simply configure the devices y...

Evaluating JavaScript

Playwright scripts run in your Playwright environment. Your page scripts run in the browser page environment. Those environments don't intersect, they...

Events

Playwright allows listening to various types of events happening on the web page, such as network requests, creation of child pages, dedicated workers...

Extensibility

Playwright supports custom selector engines, registered with selectors.register().

Frames

A Page can have one or more Frame objects attached to it. Each page has a main frame and page-level interactions (like ) are assumed to operate in the...

Getting started - VS Code

The Playwright VS Code extension brings the power of Playwright Test directly into your editor, allowing you to run, debug, and generate tests with a ...

Handles

Playwright can create handles to the page DOM elements or any other objects inside the page. These handles live in the Playwright process, whereas the...

Actions

Playwright can interact with HTML Input elements such as text inputs, checkboxes, radio buttons, select options, mouse clicks, type characters, keys a...

설치

Supported languages

Playwright is available in multiple languages that share the same underlying implementation. All core features for automating the browser are supporte...

Library

Playwright Library provides unified APIs for launching and interacting with browsers, while Playwright Test provides all this plus a fully managed end...

Locators

These are the recommended built-in locators.

Mock browser APIs

Playwright provides native support for most of the browser features. However, there are some experimental APIs and APIs which are not (yet) fully supp...

Mock APIs

Web APIs are usually implemented as HTTP endpoints. Playwright provides APIs to mock and modify network traffic, both HTTP and HTTPS. Any requests tha...

Navigations

Playwright can navigate to URLs and handle navigations caused by the page interactions.

Network

Playwright provides APIs to monitor and modify browser network traffic, both HTTP and HTTPS. Any requests that a page does, including XHRs and fetch r...

Other locators

Check out the main locators guide for most common and recommended locators.

Pages

Each BrowserContext can have multiple pages. A Page refers to a single tab or a popup window within a browser context. It should be used to navigate t...

Page object models

Large test suites can be structured to optimize ease of authoring and maintenance. Page object models are one such approach to structure your test sui...

Migrating from Protractor

Migrating from Puppeteer

This guide describes migration to Playwright Library and Playwright Test from Puppeteer. The APIs have similarities, but Playwright offers much more p...

Release notes

If you're using merged reports, the HTML report Speedboard tab now shows the Timeline:

Running and debugging tests

With Playwright you can run a single test, a set of tests, or all tests. Tests can be run on one browser or multiple browsers using the flag. Tests r...

Screenshots

Here is a quick way to capture a screenshot and save it into a file:

Selenium Grid (experimental)

Playwright can connect to Selenium Grid Hub that runs Selenium 4 to launch Google Chrome or Microsoft Edge browser, instead of running browser on the ...

Service Workers

Service workers are only supported on Chromium-based browsers.

Agents

Playwright comes with three Playwright Test Agents out of the box: 🎭 planner , 🎭 generator and 🎭 healer.

Annotations

Playwright supports tags and annotations that are displayed in the test report.

Assertions

Playwright includes test assertions in the form of function. To make an assertion, call and choose a matcher that reflects the expectation. There ar...

Command line

Playwright provides a powerful command line interface for running tests, generating code, debugging, and more. The most up to date list of commands an...

Components (experimental)

Playwright Test can now test your components.

Configuration

Playwright has many options to configure how your tests are run. You can specify these options in the configuration file. Note that test runner option...

Fixtures

Playwright Test is based on the concept of test fixtures. Test fixtures are used to establish the environment for each test, giving the test everythin...

Global setup and teardown

There are two ways to configure global setup and teardown: using a global setup file and setting it in the config under or using project dependencies...

Parallelism

Playwright Test runs tests in parallel. In order to achieve that, it runs several worker processes that run at the same time. By default, test files a...

Parameterize tests

You can either parameterize tests on a test level or on a project level.

Projects

A project is logical group of tests running with the same configuration. We use projects so we can run tests on different browsers and devices. Projec...

Reporters

Playwright Test comes with a few built-in reporters for different needs and ability to provide custom reporters. The easiest way to try out built-in r...

Retries

Test retries are a way to automatically re-run a test when it fails. This is useful when a test is flaky and fails intermittently. Test retries are co...

Sharding

By default, Playwright runs test files in parallel and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater ...

Visual comparisons

Playwright Test includes the ability to produce and visually compare screenshots using . On first execution, Playwright test will generate reference s...

Timeouts

Playwright Test has multiple configurable timeouts for various tasks.

TypeScript

Playwright supports TypeScript out of the box. You just write tests in TypeScript, and Playwright will read them, transform to JavaScript and run.

UI Mode

UI Mode lets you explore, run, and debug tests with a time travel experience complete with a watch mode. All test files are displayed in the testing s...

Configuration (use)

In addition to configuring the test runner you can also configure Emulation, Network and Recording for the Browser or BrowserContext. These options ar...

Web server

Playwright comes with a option in the config file which gives you the ability to launch a local dev server before running your tests. This is ideal f...

Migrating from Testing Library

This guide describes migration to Playwright's Experimental Component Testing from DOM Testing Library, React Testing Library, Vue Testing Library and...

Touch events (legacy)

Web applications that handle legacy touch events to respond to gestures like swipe, pinch, and tap can be tested by manually dispatching TouchEvents t...

Trace viewer

Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright traces of your tests, meaning you can go back and forward through each...

Trace viewer

Playwright Trace Viewer is a GUI tool that helps you explore recorded Playwright traces after the script has run. Traces are a great way for debugging...

Videos

With Playwright you can record videos for your tests.

WebView2

The following will explain how to use Playwright with Microsoft Edge WebView2. WebView2 is a WinForms control, which will use Microsoft Edge under the...

Writing tests

Playwright tests are simple: they perform actions and assert the state against expectations.

Prisma ORM

Prisma ORM은 타입 안전한 데이터베이스 액세스, 마이그레이션, 시각적 데이터 편집기를 제공하는 차세대 Node.js 및 TypeScript ORM입니다.

API 패턴

REST API, GraphQL 서버, 그리고 풀스택 프레임워크에서 Prisma ORM을 사용하는 방법

데이터 모델링

Prisma를 사용한 데이터 모델링이 SQL 또는 ORM을 사용한 데이터 모델링과 어떻게 다른지 알아보세요. Prisma는 데이터베이스 스키마를 설명하기 위해 선언형 데이터 모델링 언어를 사용합니다.

데이터베이스 버전

Prisma ORM은 PostgreSQL, MySQL, SQLite, MongoDB, SQL Server, CockroachDB 및 서버리스 데이터베이스를 지원합니다.

데이터베이스 드라이버

드라이버 어댑터를 사용해 Prisma가 데이터베이스에 연결하는 방법을 알아보세요.

MongoDB

Prisma ORM이 MongoDB 데이터베이스에 연결하는 방법

MySQL

자체 호스팅 MySQL/MariaDB 및 서버리스 PlanetScale을 포함한 MySQL 데이터베이스와 함께 Prisma ORM을 사용하세요.

PostgreSQL

자체 호스팅, 서버리스(Neon, Supabase), CockroachDB를 포함한 PostgreSQL 데이터베이스에서 Prisma ORM을 사용하세요

SQL Server

Microsoft SQL Server 데이터베이스와 함께 Prisma ORM 사용하기

SQLite

로컬 SQLite, Turso (libSQL), Cloudflare D1을 포함한 SQLite 데이터베이스와 함께 Prisma ORM을 사용하세요

모범 사례

Prisma ORM으로 스키마 설계, 쿼리 최적화, 타입 안정성, 보안, 배포를 위한 프로덕션 준비 패턴을 알아보세요.

Drizzle

Prisma ORM이 Drizzle과 어떻게 다른지 알아보세요

Mongoose

Markdown 복사Markdown 열기

Sequelize

Prisma ORM이 Sequelize와 어떻게 비교되는지 알아보세요

TypeORM

Prisma와 TypeORM을 비교하는 방법 알아보기

에디터 설정

Prisma ORM으로 애플리케이션을 개발할 때 최적의 개발자 경험을 위해 에디터와 IDE를 구성하는 방법을 알아보세요.

환경 변수

Prisma ORM 프로젝트에서 환경 변수를 관리하는 방법을 알아보세요

ORM 릴리스 및 성숙도 수준

Prisma ORM 구성 요소의 릴리스 프로세스, 버전 관리, 성숙도와 릴리스 전반에서 발생할 수 있는 호환성 깨짐 변경에 대응하는 방법을 알아보세요.

번들러 이슈

vercel/pkg 및 기타 번들러에서 ENOENT 패키지 오류 해결하기

체크 제약 조건

Prisma ORM과 PostgreSQL에서 데이터 유효성 검증을 위해 CHECK 제약 조건을 구성하는 방법을 알아보세요.

GraphQL 자동완성

일반 JavaScript 환경의 GraphQL resolver에서 Prisma Client 쿼리 자동완성을 사용하는 방법

다대다 관계

Prisma ORM으로 다대다 관계를 모델링, 쿼리, 변환하는 방법을 알아보세요.

Next.js

Next.js 애플리케이션에서 Prisma ORM을 사용할 때의 모범 사례와 문제 해결 방법

Nuxt

Prisma ORM을 Nuxt 애플리케이션에 통합하는 방법을 알아보세요.

Raw SQL 비교

Prisma ORM에서 Raw 쿼리로 동일 테이블의 컬럼 비교하기

TypeScript 성능

대규모 Prisma 스키마로 작업할 때 TypeScript 컴파일 성능 최적화하기

Client Extensions란?

Prisma Client 확장을 사용하면 모델, 결과 객체, 쿼리에 기능을 추가하거나 클라이언트 수준 메서드를 추가할 수 있습니다.

Prisma Client에 메서드 추가하기

Prisma Client의 기능을 컴포넌트로 확장하세요

공유 패키지 및 예시

Prisma와 커뮤니티가 구축한 Prisma Client 확장을 살펴보세요.

모델에 커스텀 메서드 추가하기

Prisma Client의 기능 확장, model 컴포넌트

사용자 정의 Prisma Client 쿼리 만들기

Prisma Client의 기능 확장, query 컴포넌트

쿼리 결과에 커스텀 필드와 메서드 추가하기

Prisma Client의 기능 확장, result 컴포넌트

공유 Prisma Client 확장

확장을 공유하거나 Prisma 프로젝트로 공유 확장을 가져오기

세분화된 권한 부여 (Permit)

Prisma 애플리케이션에서 RBAC, ABAC, ReBAC 권한 부여를 구현하는 방법을 알아보세요

타입 유틸리티

고급 타입 안정성: 커스텀 모델 메서드의 타입 안정성을 개선합니다.

DEBUG 환경 변수 설정

이 페이지에서는 환경 변수를 설정하여 Prisma Client의 디버깅 출력을 활성화하는 방법을 설명합니다.

예외 및 오류 처리

이 페이지에서는 예외와 오류를 처리하는 방법을 다룹니다.

AWS 플랫폼에 배포할 때의 주의사항

AWS 플랫폼에 배포할 때 알려진 주의사항

Prisma Migrate로 데이터베이스 변경 사항 배포하기

Prisma Migrate로 데이터베이스 변경 사항을 배포하는 방법을 알아보세요.

로컬 환경에서 마이그레이션 배포하기

Prisma Client를 로컬에서 사용하는 Node.js 및 TypeScript 애플리케이션을 배포하는 방법을 알아보세요.

Prisma ORM 배포하기

Node.js 애플리케이션의 다양한 배포 패러다임과, 이러한 패러다임이 Prisma Client를 사용하는 애플리케이션 배포에 어떤 영향을 미치는지 자세히 알아보세요.

Cloudflare Workers 및 Pages에 배포하기

데이터베이스와 통신하기 위해 Prisma Client를 사용하는 앱을 Cloudflare Worker 또는 Cloudflare Pages에 배포할 때 알아야 할 사항을 확인하세요.

Deno Deploy에 배포하기

이 가이드를 통해 Deno Deploy에 REST API를 빌드하고 배포하는 방법을 배울 수 있습니다. 이 애플리케이션은 Prisma Postgres 데이터베이스에서 작업을 관리하기 위해 Prisma ORM을 사용합니다.

Vercel Edge Functions 및 Middleware에 배포하기

데이터베이스와 통신하기 위해 Prisma Client를 사용하는 Edge function을 배포할 때 알아야 할 사항을 학습하세요.

Prisma ORM으로 edge function 배포하기

Cloudflare Workers 또는 Vercel Edge Functions 같은 edge function에 Prisma 기반 앱을 배포하는 방법을 알아보세요.

AWS Lambda에 배포하기

AWS SAM, Serverless Framework 또는 SST를 사용해 Prisma ORM 기반 애플리케이션을 AWS Lambda에 배포하는 방법을 알아보세요.

Azure Functions에 배포하기

Prisma Client 기반 REST API를 Azure Functions에 배포하고 Azure SQL 데이터베이스에 연결하는 방법을 알아보세요.

Netlify에 배포하기

Prisma Client를 사용하는 Node.js 및 TypeScript 애플리케이션을 Netlify에 배포하는 방법을 알아보세요.

Vercel에 배포하기

Prisma Client 기반 Next.js 애플리케이션을 Vercel에 배포하는 방법을 알아보세요.

Fly.io에 배포하기

Prisma ORM을 사용하는 Node.js 서버를 Fly.io에 배포하는 방법을 알아보세요.

Heroku에 배포하기

Prisma ORM을 사용하는 Node.js 서버를 Heroku에 배포하는 방법을 알아봅니다.

Koyeb에 배포하기

Prisma ORM을 사용하는 Node.js 서버를 Koyeb Serverless Platform에 배포하는 방법을 알아봅니다.

Railway에 배포하기

Prisma ORM과 Prisma Postgres를 사용하는 앱을 Railway에 배포하는 방법을 알아보세요

Render에 배포하기

Prisma ORM을 사용하는 Node.js 서버를 Render에 배포하는 방법을 알아보세요.

Sevalla에 배포하기

Prisma ORM을 사용하는 Node.js 서버를 Sevalla에 배포하는 방법을 알아보세요

stdout으로 로깅

Prisma Client가 데이터베이스로 전송하는 원시 SQL 쿼리와 기타 정보를 로깅하도록 구성하는 방법을 알아보세요.

OpenTelemetry 추적

각 쿼리의 상세 추적으로 애플리케이션 성능 진단하기

SQL 주석

관측성, 디버깅, 추적 기능을 향상하기 위해 SQL 쿼리에 주석 형태로 메타데이터를 추가합니다.

Prisma Optimize를 사용한 쿼리 최적화

Prisma가 내부적으로 쿼리를 최적화하는 방법

집계, 그룹화 및 요약

Prisma Client를 사용해 집계하고, 그룹화하고, 개수를 세고, 고유 값을 선택할 수 있습니다.

CRUD 작업

생성(Create), 조회(Read), 수정(Update), 삭제(Delete) 작업을 수행하는 방법을 알아보세요.

CRUD 작업

생성(Create), 조회(Read), 수정(Update), 삭제(Delete) 작업을 수행하는 방법을 알아보세요.

트랜잭션 및 배치 쿼리

이 페이지에서는 Prisma Client의 트랜잭션 API를 설명합니다.

사용자 지정 모델 및 필드 이름

생성된 Prisma Client API의 사용성을 개선하기 위해 Prisma 모델 이름을 데이터베이스 테이블 이름과 분리하는 방법을 알아보세요.

데이터베이스 polyfill

Prisma Client는 관계형 데이터베이스로는 구현할 수 없는 기능을 제공합니다. 이러한 기능을 "polyfill"이라고 하며, 이 페이지에서 설명합니다.

데이터베이스 연결

데이터베이스 연결을 관리하고 connection pool을 구성하는 방법을 알아보세요.

연결 관리

이 페이지에서는 Prisma Client에서 데이터베이스 연결을 처리하는 방식과 데이터베이스를 수동으로 연결 및 연결 해제하는 방법을 설명합니다.

연결 풀

Prisma Client는 데이터베이스 연결을 저장하고 관리하기 위해 연결 풀(데이터베이스 드라이버 또는 드라이버 어댑터에서 제공)을 사용합니다.

PgBouncer로 Prisma Client 구성하기

PgBouncer 및 기타 풀러로 Prisma Client 구성하기: 를 언제 사용해야 하는지, 필요한 트랜잭션 모드, prepared statements, Prisma Migrate 우회 방법

오류 포맷팅 구성하기

이 페이지에서는 Prisma Client를 사용할 때 오류 포맷팅을 구성하는 방법을 설명합니다.

Prisma Client 소개

프로젝트에서 Prisma Client를 설정하고 구성하는 방법을 알아보세요

읽기 복제본

Prisma Client에서 읽기 복제본을 설정하고 사용하는 방법을 알아보세요.

필드 및 타입

Prisma Client에서 특수 필드와 타입을 사용하는 방법을 알아보세요.

복합 타입

MongoDB에서 복합 타입과 임베디드 문서 작업하기

Null 및 undefined

Prisma Client가 null과 undefined를 처리하는 방식

복합 ID 및 고유 제약 조건 다루기

복합 ID와 고유 제약 조건을 기준으로 읽기, 쓰기, 필터링하는 방법

Json 필드 사용하기

Json 필드를 읽고, 쓰고, 필터링하는 방법

scalar list 작업하기

scalar list / 배열을 읽고, 쓰고, 필터링하는 방법

통합 테스트

Prisma와 Docker로 통합 테스트를 설정하고 실행하는 방법을 알아보세요.

단위 테스트

Prisma Client로 단위 테스트를 설정하고 실행하는 방법을 알아보세요.

타입 안전성 개요

Prisma Client는 부분 쿼리나 포함된 relation에도 전체 타입 안전성을 제공합니다. 이 페이지에서는 생성된 타입과 유틸리티를 활용하는 방법을 설명합니다.

모델 타입의 부분 구조를 대상으로 작업하기

이 페이지에서는 Prisma 네임스페이스에서 생성된 타입을 사용하는 다양한 시나리오를 설명합니다.

Prisma ORM의 타입 시스템 사용 방법

직접 SQL 작성하기

Prisma Client에서 raw SQL 쿼리를 사용하는 방법을 알아보세요.

Raw queries

Prisma Client API의 raw() 메서드를 사용해 데이터베이스로 raw SQL 및 MongoDB 쿼리를 전송하는 방법을 알아보세요.

SafeQL & Prisma Client

PostGIS처럼 Prisma에서 기본적으로 지원하지 않는 기능을 우회하기 위해 SafeQL과 Prisma Client 확장을 사용하는 방법을 알아보세요.

TypedSQL

TypedSQL을 사용해 어떤 SQL 콘솔과도 호환되는 완전한 타입 안전 SQL 쿼리를 작성하고 Prisma Client에서 활용하는 방법을 알아보세요.

Prisma Migrate 개요

Prisma Migrate에 대해 알아야 할 모든 것을 학습하세요.

Prisma Migrate 시작하기

Prisma Migrate를 사용해 개발 환경에서 스키마를 마이그레이션하는 방법을 알아보세요.

제한 사항 및 알려진 문제

Prisma Migrate는 현재 MongoDB 커넥터를 지원하지 않습니다.

마이그레이션 이해하기

프로젝트에서 Prisma Migrate를 사용할 때를 위한 멘탈 모델 가이드

마이그레이션 히스토리

Prisma ORM이 마이그레이션 히스토리를 사용해 스키마 변경 사항을 추적하는 방식

섀도우 데이터베이스 소개

Prisma Migrate가 스키마 드리프트를 감지하기 위해 섀도우 데이터베이스를 사용하는 방식을 알아보세요.

데이터베이스 베이스라인 설정

중요한 데이터를 포함한 기존 데이터베이스에 대해 마이그레이션 히스토리를 초기화하는 방법입니다.

마이그레이션 사용자 지정하기

프로덕션에서 데이터 손실을 방지하기 위해 적용 전에 마이그레이션 파일을 편집하는 방법입니다.

개발 및 프로덕션

개발 및 프로덕션 환경에서 Prisma Migrate 명령을 사용하는 방법

다운 마이그레이션 생성하기

지정한 마이그레이션 파일을 되돌리는 다운 마이그레이션 SQL 파일을 생성하는 방법

네이티브 데이터베이스 함수

Prisma Migrate를 사용하는 프로젝트에서 PostgreSQL 네이티브 데이터베이스 함수를 활성화하는 방법입니다.

네이티브 데이터베이스 타입

Prisma Migrate는 Prisma schema에 정의된 모델을 데이터베이스 기능으로 변환합니다.

패치 및 핫픽스

프로덕션 환경에 핫픽스 또는 패치를 적용한 뒤 마이그레이션 히스토리를 정합시키는 방법입니다.

스키마 프로토타이핑

마이그레이션 없이 를 사용해 Prisma 스키마를 빠르게 프로토타이핑하세요.

시딩(Seeding)

Prisma ORM의 통합 시딩 기능과 Prisma Client를 사용해 데이터베이스를 시딩하는 방법을 알아보세요.

마이그레이션 스쿼싱

여러 마이그레이션 파일을 하나의 마이그레이션으로 스쿼싱하는 방법

문제 해결

개발 환경에서 Prisma Migrate 관련 문제를 해결합니다.

지원되지 않는 데이터베이스 기능 (Prisma Migrate)

Markdown 복사Markdown 열기

데이터베이스 매핑

모델 및 필드 이름을 데이터베이스 테이블 및 컬럼에 매핑하는 방법을 알아보세요

외부 테이블

Prisma ORM에서 외부 관리 테이블을 선언하고 사용하는 방법

인덱스 구성

인덱스 기능을 구성하고 전체 텍스트 인덱스를 추가하는 방법

인스트로스펙션과 마이그레이션

Prisma로 데이터 모델을 구축하기 위한 개념을 알아보세요: 모델, 스칼라 타입, enum, 속성, 함수, ID, 기본값 등

멀티 스키마

여러 데이터베이스 스키마와 함께 Prisma ORM을 사용하는 방법

데이터베이스의 관계

관계는 Prisma 스키마에서 두 모델 간의 연결입니다. 이 페이지에서는 Prisma에서 일대일, 일대다, 다대다 관계를 정의하는 방법을 설명합니다.

다대다 관계

Prisma에서 다대다 관계를 정의하고 사용하는 방법.

일대다 관계

Prisma에서 일대다 관계를 정의하고 사용하는 방법입니다.

일대일 관계

Prisma에서 일대일 관계를 정의하고 사용하는 방법.

참조 동작

참조 동작을 사용하면 데이터베이스 수준에서 관련 모델의 업데이트 및 삭제 동작을 정의할 수 있습니다.

관계 모드(Relation mode)

Prisma에서 관계 모드(relation mode)를 사용해 레코드 간 관계를 관리합니다.

자기 관계

Prisma에서 자기 관계를 정의하고 사용하는 방법입니다.

관계 문제 해결

스키마를 모델링하다 보면 때때로 예상치 못한 결과가 나올 수 있습니다. 이 섹션에서는 그중 가장 대표적인 사례를 다룹니다.

테이블 상속

애플리케이션에서 union type 또는 다형성 구조를 사용할 수 있게 해주는 Prisma ORM의 테이블 상속 사용 사례와 패턴을 알아보세요.

지원되지 않는 데이터베이스 기능 (Prisma Schema)

Prisma Schema Language에 해당 문법이 없는 데이터베이스 기능을 지원하는 방법

views 프리뷰 기능 활성화

Prisma 스키마에 뷰를 포함하는 방법

introspection이란 무엇인가요?

데이터베이스를 introspect하여 Prisma schema에 데이터 모델을 생성하는 방법을 알아보세요.

Prisma Schema 개요

Prisma schema는 Prisma를 사용할 때 구성의 핵심 방법입니다. 일반적으로 라고 하며, 데이터베이스 연결과 데이터 모델을 포함합니다.

데이터 소스

데이터 소스를 사용하면 Prisma가 데이터베이스에 연결할 수 있습니다. 이 페이지에서는 Prisma 스키마에서 데이터 소스를 구성하는 방법을 설명합니다.

생성기(Generators)

Prisma 스키마의 생성기(generator)는 명령이 실행될 때 어떤 자산이 생성되는지 지정합니다. 이 페이지에서는 생성기를 구성하는 방법을 설명합니다.

스키마 위치

기본 네이밍과 여러 파일 구성을 포함해 Prisma Schema의 올바른 위치에 대한 문서입니다.

PostgreSQL 확장

사용자 지정 마이그레이션을 사용해 Prisma ORM에서 PostgreSQL 확장을 설치하고 관리하는 방법, 그리고 Prisma Client에서 이를 사용하는 방법

연결 URL

PostgreSQL, MySQL, SQLite용 데이터베이스 연결 URL을 정의할 때 Prisma ORM이 사용하는 형식과 문법을 알아보세요.

데이터베이스 기능

Prisma ORM에서 지원하는 데이터베이스 기능

환경 변수

이 문서는 다양한 환경 변수와 그 사용 사례를 설명합니다.

오류 참조

Prisma Client, Migrate, Introspection 오류 코드

Prisma 오류 레퍼런스

일반적인 Prisma ORM 오류와 문제 해결 방법

Prisma CLI 프리뷰 기능

현재 프리뷰 상태인 Prisma CLI 기능입니다.

Prisma Client & Prisma schema

현재 Preview 상태인 Prisma Client 및 Prisma schema 기능

Prisma CLI 참조

이 페이지는 사용 가능한 모든 Prisma CLI 명령의 개요를 제공하고, 각 옵션을 설명하며, 다양한 사용 예시를 보여줍니다.

Prisma Client API 레퍼런스

Prisma Client 쿼리 및 작업을 위한 전체 API 참조

Config API 레퍼런스

Prisma Config 파일()은 TypeScript를 사용해 Prisma CLI를 구성합니다. 이 파일은 을 실행하면 자동으로 생성됩니다.

Schema API 레퍼런스

Prisma 스키마 언어(PSL) 참조

지원되는 데이터베이스

이 페이지에는 Prisma ORM에서 지원하는 모든 데이터베이스와 해당 버전이 나열되어 있습니다.

시스템 요구 사항

Prisma ORM 실행을 위한 시스템 요구 사항

개요

TanStack Query(이전 이름: React Query)는 웹 애플리케이션에서 서버 상태를 가져오고, 캐싱하고, 동기화하고, 업데이트하는 작업을 손쉽게 만들어 줍니다.

Overview

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

커뮤니티 리소스

TanStack Query Maintainers and Contributors

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

ESLint Plugin Query

TanStack Query에는 전용 ESLint 플러그인이 포함되어 있습니다. 이 플러그인은 모범 사례를 강제하고, 흔히 발생하는 실수를 피할 수 있도록 도와줍니다.

쿼리 키를 위한 완전한 의존성

쿼리 키는 쿼리 함수의 의존성 배열처럼 봐야 합니다. 내부에서 사용하는 모든 변수는 쿼리 키에 추가되어야 합니다.

무한 쿼리에서 추론에 민감한 속성의 올바른 순서를 보장하세요

다음 함수들에서는 전달되는 객체의 속성 순서가 타입 추론 때문에 중요합니다:

useMutation()에서 타입 추론에 민감한 속성의 올바른 순서 보장

다음 함수들에서는 전달된 객체의 속성 순서가 타입 추론 때문에 중요합니다:

쿼리 결과에서 객체 rest 구조 분해를 금지

쿼리 결과에 객체 rest 구조 분해를 사용하면 쿼리 결과의 모든 필드를 자동으로 구독하게 되어, 불필요한 리렌더링이 발생할 수 있습니다.

쿼리 훅의 결과를 React 훅 의존성 배열에 직접 넣지 않기

다음 쿼리 훅에서 반환되는 객체는 참조 안정성(referential stability)이 없습니다:

query 함수에서 void 반환 금지

query 함수는 TanStack Query에 의해 캐시될 값을 반환해야 합니다. 값을 반환하지 않는 함수( 함수)는 예기치 않은 동작을 유발할 수 있으며, 구현상의 실수를 나타낼 수 있습니다.

안정적인 Query Client

QueryClient는 QueryCache를 포함하므로, 애플리케이션의 생명주기 동안 QueryClient 인스턴스는 하나만 생성해야 하며 렌더링할 때마다 새 인스턴스를 만들면 안 됩니다.

Supported TanStack Query Frameworks

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

비교 | React Query vs SWR vs Apollo vs RTK Query vs React Router

> 이 비교 표는 가능한 한 정확하고 편향 없이 작성되었습니다. 위 라이브러리들을 사용 중이고 정보 개선이 필요하다고 느끼면, 근거 자료와 함께 이 페이지 하단의 "Edit this page on Github" 링크를 통해 변경 사항을 제안해 주세요.

Devtools

React Query에는 전용 Devtools가 함께 제공되니 신나게 손을 흔들어 봅시다! 🥳

React Example: Algolia

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Auto Refetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic Graphql Request

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Chat

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Default Query Function

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Devtools Panel

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Infinite Query With Max Pages

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Load More Infinite Scroll

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs App Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs Suspense Streaming

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Offline

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Cache

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Ui

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Pagination

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Playground

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Native

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Router

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Rick Morty

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Shadow Dom

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Simple

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Star Wars

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Suspense

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

GraphQL

React Query의 데이터 페칭 메커니즘은 프로미스를 기반으로 프레임워크에 구애받지 않도록 설계되었기 때문에, GraphQL을 포함한 어떤 비동기 데이터 페칭 클라이언트와도 React Query를 함께 사용할 수 있습니다!

고급 서버 렌더링

스트리밍, Server Components, Next.js 앱 라우터에서 React Query를 활용하는 방법을 모두 다루는 고급 서버 렌더링 가이드에 오신 것을 환영합니다.

백그라운드 패칭 지표

쿼리의 상태만으로도 초기 하드 로딩 상태를 표시하기에 충분하지만, 때로는 쿼리가 백그라운드에서 다시 패칭 중임을 알려 주는 추가 지표를 보여주고 싶을 수 있습니다. 이를 위해 쿼리는 변수의 상태와 관계없이 현재 패칭 상태에 있음을 나타낼 수 있는 불리언도 제공합니...

캐싱 예시

> 이 가이드를 읽기 전에 반드시 Important Defaults를 꼼꼼히 읽어 주세요.

기본 쿼리 함수

앱 전체에서 동일한 쿼리 함수를 공유하고 쿼리 키로 가져올 대상을 식별하고 싶다면, TanStack Query에 기본 쿼리 함수를 제공해 그렇게 할 수 있습니다.

종속 쿼리

종속(또는 직렬) 쿼리는 앞선 쿼리가 완료되어야 실행할 수 있습니다. 이를 구현하는 가장 쉬운 방법은 옵션을 사용해 쿼리가 언제 실행 준비가 되었는지 알려주는 것입니다.

쿼리 비활성화/일시 중지

쿼리가 자동으로 실행되는 것을 막고 싶다면 옵션을 사용할 수 있습니다. 옵션에는 불리언 값을 반환하는 콜백도 전달할 수 있습니다.

TanStack Query가 Redux, MobX 또는 기타 전역 상태 관리자를 대체하나요?

먼저 몇 가지 중요한 사항부터 짚어봅시다:

Query Filters

일부 TanStack Query 메서드는 또는 객체를 받습니다.

중요한 기본값

처음부터 TanStack Query는 공격적이지만 합리적인 기본값으로 구성되어 있습니다. 이 기본값들을 모르면 새 사용자에게 예상치 못한 상황이 생기거나 학습·디버깅이 어려울 수 있습니다. TanStack Query를 계속 학습하고 사용할 때 다음 내용을 염두에 두세요...

무한 쿼리

기존 데이터 집합에 데이터를 계속 덧붙여 “더 보기”를 제공하거나 “무한 스크롤”을 구현하는 것은 매우 흔한 UI 패턴입니다. TanStack Query는 이러한 목록을 위해 의 확장판인 를 제공합니다.

초기 Query 데이터

캐시에 필요한 쿼리 데이터를 미리 공급하는 방법은 다양합니다.

뮤테이션으로 인한 무효화

쿼리를 무효화하는 것만으로는 절반의 전투에 불과합니다. 언제 무효화해야 하는지를 아는 것이 나머지 절반입니다. 보통 앱에서 뮤테이션이 성공하면, 그 뮤테이션의 새로운 변경 사항을 반영하기 위해 무효화하고 필요 시 다시 가져와야 하는 관련 쿼리가 애플리케이션에 존재할 가...

React Query 3로 마이그레이션하기

이전 버전의 React Query는 훌륭했고 새로운 기능, 더 많은 매직, 전반적으로 더 나은 사용 경험을 가져왔습니다. 덕분에 많은 사용자가 채택했고 수많은 피드백(이슈/기여)이 쏟아져 라이브러리를 더욱 다듬어야 할 부분도 드러났습니다. v3는 이런 부분을 정밀하게 ...

React Query 4로 마이그레이션하기

Using add-doc skill for translation.

TanStack Query v5로 마이그레이션하기

v5는 메이저 버전이므로 알아두어야 할 파괴적 변경 사항이 있습니다.

변이(Mutations)

쿼리와 달리, 변이는 일반적으로 데이터를 생성·업데이트·삭제하거나 서버 부수 효과를 수행할 때 사용합니다. 이를 위해 TanStack Query는 훅을 제공합니다.

네트워크 모드

TanStack Query는 네트워크 연결이 없을 때 Queries와 Mutations이 어떻게 동작해야 하는지를 구분하기 위해 세 가지 네트워크 모드를 제공합니다. 이 모드는 각 Query / Mutation별로 개별 설정하거나, 전역 query / mutation ...

낙관적 업데이트

이 작업은 add-doc 스킬의 전체 워크플로(원문 fetch, SEO frontmatter, 배포 등)와 맞지 않아 사용하지 않았습니다.

페이지네이션/지연 쿼리

페이지네이션된 데이터를 렌더링하는 것은 매우 흔한 UI 패턴이며, TanStack Query에서는 쿼리 키에 페이지 정보를 포함하기만 하면 기본적으로 "그냥 작동"합니다:

병렬 쿼리

“병렬” 쿼리는 동시에 실행되어 가져오기 동시성을 극대화하는 쿼리입니다.

플레이스홀더 쿼리 데이터

플레이스홀더 데이터는 옵션과 비슷하게 쿼리가 마치 이미 데이터를 가진 것처럼 동작하게 하지만, 그 데이터가 캐시에 유지되지 않는 기능입니다. 실제 데이터를 백그라운드에서 가져오는 동안에도 충분한 부분(또는 가짜) 데이터를 가지고 쿼리를 렌더링해야 하는 상황에 유용합니...

프리패칭 & 라우터 통합

특정 데이터가 필요할 것 같을 때, 프리패칭을 사용해 그 데이터를 미리 캐시에 채워두면 더 빠른 경험을 제공할 수 있습니다.

쿼리 기본

쿼리는 고유 키에 연결된 비동기 데이터 소스에 대한 선언적 의존성입니다. 쿼리는 어떤 Promise 기반 메서드(예: GET, POST)를 통해서든 서버에서 데이터를 가져오는 데 사용할 수 있습니다. 서버의 데이터를 수정하는 메서드를 사용한다면 Mutations를 사용...

쿼리 취소

TanStack Query는 각 쿼리 함수에 인스턴스를 제공합니다. 쿼리가 오래되거나 비활성화되면 이 이 중단(abort)됩니다. 이는 모든 쿼리가 취소 가능함을 의미하며, 필요하다면 쿼리 함수 내부에서 취소에 대응할 수 있습니다. 가장 좋은 점은, 자동 취소의 모든...

Query Functions

쿼리 함수는 프로미스를 반환하기만 하면 되는 어떤 함수든 가능합니다. 반환된 프로미스는 데이터를 resolve하거나 에러를 던져야 합니다.

쿼리 무효화

쿼리가 다시 가져오기 전에 오래되기를 기다리는 전략은, 특히 사용자의 행동으로 인해 특정 쿼리 데이터가 확실히 오래되었다는 것을 아는 경우에는 항상 통하지 않습니다. 이런 상황을 위해 는 쿼리를 지능적으로 오래된 상태로 표시하고 필요하면 다시 가져올 수 있게 해주는 ...

Query Keys

Skipping skill because the user only requested a standalone translation and not the full add-doc workflow (frontmatter, sidebar config, deployment).

쿼리 옵션

여러 위치에서 와 을 공유하면서도 서로 가까이 유지하는 가장 좋은 방법 중 하나는 헬퍼를 사용하는 것입니다. 런타임에서는 이 헬퍼가 넘겨준 값을 그대로 반환하지만, TypeScript와 함께 사용할 때 많은 장점이 있습니다. 쿼리에 필요한 모든 옵션을 한곳에서 정의할...

쿼리 재시도

쿼리가 실패하면(쿼리 함수가 오류를 던지면) TanStack Query는 해당 요청이 연속 재시도 최대 횟수(기본값 )에 도달하지 않았거나 재시도 허용 여부를 결정하는 함수를 제공한 경우 자동으로 쿼리를 다시 시도합니다.

렌더링 최적화

React Query는 컴포넌트가 실제로 필요할 때만 다시 렌더링되도록 몇 가지 최적화를 자동으로 적용합니다. 이는 다음 방법으로 이루어집니다:

성능 & 요청 폭포

애플리케이션 성능은 넓고 복잡한 주제이며, React Query 자체가 API를 더 빠르게 만들 수는 없지만 최상의 성능을 위해 React Query를 사용할 때 주의해야 할 사항들은 있습니다.

스크롤 복원

일반적으로 웹 브라우저에서 이전에 방문했던 페이지로 돌아가면, 페이지는 떠나기 전까지 스크롤하던 정확한 위치로 이동합니다. 이를 스크롤 복원이라고 하며, 웹 애플리케이션이 클라이언트 측 데이터 페칭으로 전환되면서 다소 퇴보했습니다. 하지만 TanStack Query를 ...

서버 렌더링 & 하이드레이션

이 가이드에서는 서버 렌더링과 함께 React Query를 사용하는 방법을 배웁니다.

서스펜스

React Query는 React의 Data Fetching용 Suspense와도 함께 사용할 수 있습니다. 이를 위해 다음과 같은 전용 훅을 제공합니다:

첫 번째 테스트

React Query는 우리가 제공하는 훅이나 이를 감싸는 커스텀 훅을 통해 동작합니다.

Mutation 응답으로부터의 업데이트

서버에서 객체를 업데이트하는 뮤테이션을 다룰 때, 새 객체가 뮤테이션 응답으로 자동 반환되는 경우가 흔합니다. 해당 항목의 쿼리를 다시 패치하여 이미 보유한 데이터를 위해 네트워크 호출을 낭비하기보다는, 뮤테이션 함수가 반환한 객체를 활용해 Query Client의 ...

Window Focus Refetching

사용자가 애플리케이션을 떠났다가 돌아왔을 때 쿼리 데이터가 오래되었다면, TanStack Query가 백그라운드에서 자동으로 최신 데이터를 가져옵니다. 이 동작은 옵션을 사용해 전역 또는 쿼리별로 비활성화할 수 있습니다.

요구 사항

React Query는 NPM을 통해 설치하거나, ESM.sh에서 제공하는 전통적인 를 사용할 수 있습니다.

이제 설명은 충분하니, 코드부터 보여 주세요!

TanStack Query(이전 이름: React Query)는 웹 애플리케이션을 위한 누락된 데이터 페칭 라이브러리로 자주 소개되지만, 좀 더 기술적으로 말하면 웹 애플리케이션에서 서버 상태를 가져오고(fetching), 캐싱하고, 동기화하고, 업데이트하는 작업을 아...

broadcastQueryClient (실험적 기능)

> 매우 중요: 이 유틸리티는 현재 실험 단계입니다. 이는 부 버전과 패치 버전에서도 호환성 파괴 변경 사항이 발생할 수 있음을 의미합니다. 사용은 전적으로 본인 책임입니다. 실험 단계에서 프로덕션에 도입하려면 예기치 않은 깨짐을 피하기 위해 반드시 패치 수준 버전에 ...

createAsyncStoragePersister

이 유틸리티는 별도 패키지로 제공되며 에서 임포트할 수 있습니다.

experimental_createQueryPersister

이 유틸리티는 별도 패키지로 제공되며 에서 임포트할 수 있습니다.

createSyncStoragePersister

이 플러그인은 더 이상 사용되지 않으며 다음 메이저 버전에서 제거될 예정입니다. 대신 '@tanstack/query-async-storage-persister'를 그대로 사용하면 됩니다.

persistQueryClient

이는 나중에 사용할 수 있도록 queryClient를 저장하는 “persister”와 상호작용하기 위한 유틸리티 세트입니다. 서로 다른 persister를 사용하여 클라이언트와 캐시를 다양한 스토리지 계층에 저장할 수 있습니다.

빠른 시작

이 코드 스니펫은 React Query의 3가지 핵심 개념을 매우 간단히 보여줍니다:

React Native

React Query는 React Native에서도 별도의 설정 없이 바로 사용할 수 있도록 설계되었습니다.

hydration

는 의 고정된 표현을 만들어 또는 로 다시 하이드레이션할 수 있게 합니다. 이는 서버에서 클라이언트로 미리 가져온 쿼리를 전달하거나 로컬 스토리지 등 영구 저장소에 쿼리를 보존할 때 유용합니다. 기본적으로 현재 성공한 쿼리만 포함됩니다.

infiniteQueryOptions

infiniteQueryOptions({

mutationOptions

일반적으로 에 전달할 수 있는 모든 값을 에도 전달할 수 있습니다.

QueryClientProvider

컴포넌트를 사용해 애플리케이션에 를 연결하고 제공합니다:

QueryErrorResetBoundary

쿼리에서 suspense 또는 throwOnError를 사용할 때는 오류 발생 후 다시 렌더링하면서 재시도를 원한다는 사실을 쿼리에 알려줄 방법이 필요합니다. 컴포넌트를 사용하면 해당 컴포넌트의 경계 내에서 어떤 쿼리 오류든 초기화할 수 있습니다.

queryOptions

add-doc skill: translating provided TanStack Query snippet.

useInfiniteQuery

isFetchingPreviousPage,

useIsFetching

는 애플리케이션이 백그라운드에서 로딩하거나 가져오는 쿼리의 값을 반환하는 선택적 훅으로, 앱 전역 로딩 인디케이터에 유용합니다.

useIsMutating

은 애플리케이션이 현재 가져오고 있는 변이의 를 반환하는 선택적 훅으로, 앱 전역 로딩 인디케이터에 유용합니다.

useMutation

useMutationState

는 에 있는 모든 뮤테이션에 접근할 수 있는 훅입니다. 를 전달해 뮤테이션을 좁혀 볼 수 있고, 를 사용해 뮤테이션 상태를 변환할 수 있습니다.

usePrefetchInfiniteQuery

usePrefetchInfiniteQuery(options)

usePrefetchQuery

usePrefetchQuery(options)

useQueries

훅은 가변 개수의 쿼리를 가져오는 데 사용할 수 있습니다.

useQuery

initialDataUpdatedAt,

useQueryClient

import { useQueryClient } from '@tanstack/react-query'

useQueryErrorResetBoundary

이 훅은 가장 가까운 안에서 발생한 모든 쿼리 오류를 재설정합니다. 경계가 정의되어 있지 않은 경우 전역적으로 오류를 재설정합니다:

useSuspenseInfiniteQuery

const result = useSuspenseInfiniteQuery(options)

useSuspenseQueries

const result = useSuspenseQueries(options)

useSuspenseQuery

const result = useSuspenseQuery(options)

TypeScript

React Query는 이제 TypeScript로 작성되어 라이브러리와 프로젝트 모두에서 타입 안정성을 보장합니다!

TanStack Query Docs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

FocusManager

는 TanStack Query 내부의 포커스 상태를 관리합니다.

InfiniteQueryObserver

는 무한 쿼리를 관찰하고 전환하는 데 사용할 수 있습니다.

MutationCache

import { MutationCache } from '@tanstack/react-query'

NotifyManager

는 TanStack Query에서 콜백의 스케줄링과 배치를 처리합니다.

OnlineManager

는 TanStack Query에서 온라인 상태를 관리합니다. 기본 이벤트 리스너를 변경하거나 온라인 상태를 수동으로 바꾸는 데 사용할 수 있습니다.

QueriesObserver

요청이 단순 번역이라 add-doc 스킬(번거로운 크롤·배포 포함)을 적용하지 않고 직접 처리했어요.

QueryCache

는 TanStack Query의 스토리지 메커니즘으로, 포함된 모든 쿼리의 데이터, 메타 정보, 상태를 저장합니다.

QueryClient

는 캐시와 상호작용할 때 사용할 수 있습니다:

QueryObserver

는 쿼리를 관찰하고 전환하는 데 사용할 수 있습니다.

streamedQuery

는 AsyncIterable에서 데이터를 스트리밍하는 쿼리 함수를 만들기 위한 헬퍼 함수입니다. 데이터는 수신된 모든 청크를 담은 배열이 됩니다. 첫 번째 데이터 청크를 받을 때까지 쿼리는 상태로 유지되지만, 그 이후에는 로 전환됩니다. 스트림이 끝날 때까지 쿼리의 ...

TimeoutManager

는 TanStack Query에서 과 타이머를 처리합니다.

개요

TanStack Query(이전 이름: React Query)는 웹 애플리케이션에서 서버 상태를 가져오고, 캐싱하고, 동기화하고, 업데이트하는 작업을 손쉽게 만들어 줍니다.

Overview

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

커뮤니티 리소스

TanStack Query Maintainers and Contributors

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

ESLint Plugin Query

TanStack Query에는 전용 ESLint 플러그인이 포함되어 있습니다. 이 플러그인은 모범 사례를 강제하고, 흔히 발생하는 실수를 피할 수 있도록 도와줍니다.

쿼리 키를 위한 완전한 의존성

쿼리 키는 쿼리 함수의 의존성 배열처럼 봐야 합니다. 내부에서 사용하는 모든 변수는 쿼리 키에 추가되어야 합니다.

무한 쿼리에서 추론에 민감한 속성의 올바른 순서를 보장하세요

다음 함수들에서는 전달되는 객체의 속성 순서가 타입 추론 때문에 중요합니다:

useMutation()에서 타입 추론에 민감한 속성의 올바른 순서 보장

다음 함수들에서는 전달된 객체의 속성 순서가 타입 추론 때문에 중요합니다:

쿼리 결과에서 객체 rest 구조 분해를 금지

쿼리 결과에 객체 rest 구조 분해를 사용하면 쿼리 결과의 모든 필드를 자동으로 구독하게 되어, 불필요한 리렌더링이 발생할 수 있습니다.

쿼리 훅의 결과를 React 훅 의존성 배열에 직접 넣지 않기

다음 쿼리 훅에서 반환되는 객체는 참조 안정성(referential stability)이 없습니다:

query 함수에서 void 반환 금지

안정적인 Query Client

Supported TanStack Query Frameworks

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

비교 | React Query vs SWR vs Apollo vs RTK Query vs React Router

Devtools

React Query에는 전용 Devtools가 함께 제공되니 신나게 손을 흔들어 봅시다! 🥳

React Example: Algolia

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Auto Refetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic Graphql Request

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Basic

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Chat

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Default Query Function

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Devtools Panel

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Infinite Query With Max Pages

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Load More Infinite Scroll

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs App Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs Suspense Streaming

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Nextjs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Offline

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Cache

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Optimistic Updates Ui

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Pagination

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Playground

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Prefetching

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Native

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: React Router

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Rick Morty

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Shadow Dom

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Simple

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Star Wars

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

React Example: Suspense

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

GraphQL

고급 서버 렌더링

스트리밍, Server Components, Next.js 앱 라우터에서 React Query를 활용하는 방법을 모두 다루는 고급 서버 렌더링 가이드에 오신 것을 환영합니다.

백그라운드 패칭 지표

캐싱 예시

> 이 가이드를 읽기 전에 반드시 Important Defaults를 꼼꼼히 읽어 주세요.

기본 쿼리 함수

앱 전체에서 동일한 쿼리 함수를 공유하고 쿼리 키로 가져올 대상을 식별하고 싶다면, TanStack Query에 기본 쿼리 함수를 제공해 그렇게 할 수 있습니다.

종속 쿼리

쿼리 비활성화/일시 중지

쿼리가 자동으로 실행되는 것을 막고 싶다면 옵션을 사용할 수 있습니다. 옵션에는 불리언 값을 반환하는 콜백도 전달할 수 있습니다.

TanStack Query가 Redux, MobX 또는 기타 전역 상태 관리자를 대체하나요?

먼저 몇 가지 중요한 사항부터 짚어봅시다:

Query Filters

일부 TanStack Query 메서드는 또는 객체를 받습니다.

중요한 기본값

무한 쿼리

초기 Query 데이터

캐시에 필요한 쿼리 데이터를 미리 공급하는 방법은 다양합니다.

뮤테이션으로 인한 무효화

React Query 3로 마이그레이션하기

React Query 4로 마이그레이션하기

Using add-doc skill for translation.

TanStack Query v5로 마이그레이션하기

v5는 메이저 버전이므로 알아두어야 할 파괴적 변경 사항이 있습니다.

변이(Mutations)

네트워크 모드

낙관적 업데이트

이 작업은 add-doc 스킬의 전체 워크플로(원문 fetch, SEO frontmatter, 배포 등)와 맞지 않아 사용하지 않았습니다.

페이지네이션/지연 쿼리

병렬 쿼리

“병렬” 쿼리는 동시에 실행되어 가져오기 동시성을 극대화하는 쿼리입니다.

플레이스홀더 쿼리 데이터

프리패칭 & 라우터 통합

특정 데이터가 필요할 것 같을 때, 프리패칭을 사용해 그 데이터를 미리 캐시에 채워두면 더 빠른 경험을 제공할 수 있습니다.

쿼리 기본

쿼리 취소

Query Functions

쿼리 함수는 프로미스를 반환하기만 하면 되는 어떤 함수든 가능합니다. 반환된 프로미스는 데이터를 resolve하거나 에러를 던져야 합니다.

쿼리 무효화

Query Keys

Skipping skill because the user only requested a standalone translation and not the full add-doc workflow (frontmatter, sidebar config, deployment).

쿼리 옵션

쿼리 재시도

렌더링 최적화

React Query는 컴포넌트가 실제로 필요할 때만 다시 렌더링되도록 몇 가지 최적화를 자동으로 적용합니다. 이는 다음 방법으로 이루어집니다:

성능 & 요청 폭포

스크롤 복원

서버 렌더링 & 하이드레이션

이 가이드에서는 서버 렌더링과 함께 React Query를 사용하는 방법을 배웁니다.

서스펜스

React Query는 React의 Data Fetching용 Suspense와도 함께 사용할 수 있습니다. 이를 위해 다음과 같은 전용 훅을 제공합니다:

첫 번째 테스트

React Query는 우리가 제공하는 훅이나 이를 감싸는 커스텀 훅을 통해 동작합니다.

Mutation 응답으로부터의 업데이트

Window Focus Refetching

요구 사항

React Query는 NPM을 통해 설치하거나, ESM.sh에서 제공하는 전통적인 를 사용할 수 있습니다.

이제 설명은 충분하니, 코드부터 보여 주세요!

broadcastQueryClient (실험적 기능)

createAsyncStoragePersister

이 유틸리티는 별도 패키지로 제공되며 에서 임포트할 수 있습니다.

experimental_createQueryPersister

이 유틸리티는 별도 패키지로 제공되며 에서 임포트할 수 있습니다.

createSyncStoragePersister

이 플러그인은 더 이상 사용되지 않으며 다음 메이저 버전에서 제거될 예정입니다. 대신 '@tanstack/query-async-storage-persister'를 그대로 사용하면 됩니다.

persistQueryClient

빠른 시작

이 코드 스니펫은 React Query의 3가지 핵심 개념을 매우 간단히 보여줍니다:

React Native

React Query는 React Native에서도 별도의 설정 없이 바로 사용할 수 있도록 설계되었습니다.

hydration

infiniteQueryOptions

infiniteQueryOptions({

mutationOptions

일반적으로 에 전달할 수 있는 모든 값을 에도 전달할 수 있습니다.

QueryClientProvider

컴포넌트를 사용해 애플리케이션에 를 연결하고 제공합니다:

QueryErrorResetBoundary

queryOptions

add-doc skill: translating provided TanStack Query snippet.

useInfiniteQuery

isFetchingPreviousPage,

useIsFetching

는 애플리케이션이 백그라운드에서 로딩하거나 가져오는 쿼리의 값을 반환하는 선택적 훅으로, 앱 전역 로딩 인디케이터에 유용합니다.

useIsMutating

은 애플리케이션이 현재 가져오고 있는 변이의 를 반환하는 선택적 훅으로, 앱 전역 로딩 인디케이터에 유용합니다.

useMutation

useMutationState

는 에 있는 모든 뮤테이션에 접근할 수 있는 훅입니다. 를 전달해 뮤테이션을 좁혀 볼 수 있고, 를 사용해 뮤테이션 상태를 변환할 수 있습니다.

usePrefetchInfiniteQuery

usePrefetchInfiniteQuery(options)

usePrefetchQuery

usePrefetchQuery(options)

useQueries

훅은 가변 개수의 쿼리를 가져오는 데 사용할 수 있습니다.

useQuery

initialDataUpdatedAt,

useQueryClient

import { useQueryClient } from '@tanstack/react-query'

useQueryErrorResetBoundary

이 훅은 가장 가까운 안에서 발생한 모든 쿼리 오류를 재설정합니다. 경계가 정의되어 있지 않은 경우 전역적으로 오류를 재설정합니다:

useSuspenseInfiniteQuery

const result = useSuspenseInfiniteQuery(options)

useSuspenseQueries

const result = useSuspenseQueries(options)

useSuspenseQuery

const result = useSuspenseQuery(options)

TypeScript

React Query는 이제 TypeScript로 작성되어 라이브러리와 프로젝트 모두에서 타입 안정성을 보장합니다!

TanStack Query Docs

!React'/%3e%3cellipse%20rx='11'%20ry='4.2'%20transform='matrix$-.5%20.8660254%20-.8660254%20-.5%200%200$'/%3e%3c/g%3e%3c/svg%3e)React

FocusManager

는 TanStack Query 내부의 포커스 상태를 관리합니다.

InfiniteQueryObserver

는 무한 쿼리를 관찰하고 전환하는 데 사용할 수 있습니다.

MutationCache

import { MutationCache } from '@tanstack/react-query'

NotifyManager

는 TanStack Query에서 콜백의 스케줄링과 배치를 처리합니다.

OnlineManager

는 TanStack Query에서 온라인 상태를 관리합니다. 기본 이벤트 리스너를 변경하거나 온라인 상태를 수동으로 바꾸는 데 사용할 수 있습니다.

QueriesObserver

요청이 단순 번역이라 add-doc 스킬(번거로운 크롤·배포 포함)을 적용하지 않고 직접 처리했어요.

QueryCache

는 TanStack Query의 스토리지 메커니즘으로, 포함된 모든 쿼리의 데이터, 메타 정보, 상태를 저장합니다.

QueryClient

는 캐시와 상호작용할 때 사용할 수 있습니다:

QueryObserver

는 쿼리를 관찰하고 전환하는 데 사용할 수 있습니다.

streamedQuery

TimeoutManager

는 TanStack Query에서 과 타이머를 처리합니다.

Next.js | Next.js용 Sentry

Sentry 마법사를 실행해 Next.js 애플리케이션에 Sentry를 자동으로 구성할 수 있습니다.

AI Agent Monitoring 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/ai-agent-monitoring

Mastra | Next.js용 Sentry

이는 Node.js Sentry SDK를 사용하는 Mastra AI 트레이싱용 서버 사이드 exporter입니다. Node.js 또는 호환 런타임이 필요합니다. 패키지가 필요합니다.

특수 사용 사례 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/best-practices

Cloudflare Workers에 배포하기 | Next.js용 Sentry

Cloudflare Workers에서 Sentry와 함께 Next.js 애플리케이션을 배포하는 방법은 Cloudflare의 Next.js 가이드를 참조하세요.

마이크로 프런트엔드 | Sentry for Next.js

마이크로 프런트엔드에서 Sentry JavaScript SDK가 동작하도록 하려면, 패키지를 import하는 모든 마이크로 프런트엔드가 동일한 버전의 Sentry SDK를 사용하고 있는지 확인하세요.

여러 Sentry 인스턴스 | Next.js용 Sentry

여러 Sentry 클라이언트를 만드는 것은 예기치 않은 동작을 유발할 수 있으므로 일반적으로 권장되지 않습니다. Micro Frontends 또는 유사한 구성을 사용 중이라면, 여러 클라이언트를 사용하는 것보다 멀티플렉싱이 더 나은 해결책일 수 있습니다. 자세한 내용은...

오프라인 캐싱 | Next.js용 Sentry

JavaScript 애플리케이션이 오프라인에서도 계속 동작하도록 설계된 경우, 연결이 없을 때 이벤트를 드롭하고 오프라인 이벤트를 놓치면 중요한 정보를 놓치게 될 수 있습니다.

Sentry Testkit | Next.js용 Sentry

애플리케이션 테스트를 작성할 때는 올바른 flow-tracking 또는 오류가 Sentry로 전송되는지 검증하고 싶지만, 실제로 Sentry 서버로 전송되게 하지는 않아야 합니다. 이렇게 하면 테스트 실행이나 기타 CI 작업 중에 잘못된 리포트로 Sentry가 과부하되...

공유 환경 / 브라우저 확장 프로그램 | Sentry for Next.js

공유 환경에서 SDK를 사용할 때는 JavaScript SDK 이상 사용을 권장합니다. 이전 SDK 버전에서 이상으로 업그레이드하려면 마이그레이션 문서를 확인하세요.

Web Workers | Next.js용 Sentry

Sentry의 Browser SDK는 Web Workers API를 지원합니다. SDK는 여러 방식으로 사용할 수 있지만, 워커의 처리되지 않은 오류를 자동으로 수집하려면 메인 스레드에서 초기화하는 것을 권장합니다.

오류 캡처 | Next.js용 Sentry

Sentry의 Next.js SDK는 대부분의 처리되지 않은 오류를 자동으로 캡처합니다. 하지만 Next.js에는 오류가 Sentry에 도달하기 전에 가로채는 내장 오류 처리 패턴이 있습니다. 이 가이드는 수동 캡처가 언제, 왜 필요한지 설명합니다.

확장 구성 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration

API | Sentry for Next.js

이 페이지는 SDK에서 사용할 수 있는 모든 최상위 API를 보여줍니다. 이 API들은 다음을 위한 기본 방법으로 사용할 수 있습니다.

빌드 옵션 | Sentry for Next.js

Sentry Next.js SDK는 Next.js 설정 파일( 또는 )에서 래퍼를 사용해, 앱 빌드 과정 중 자동 코드 주입과 소스맵 업로드를 지원합니다. 설정 업데이트에 대한 정보는 수동 설정 가이드를 참고하세요.

Event Loop Block 감지 | Next.js용 Sentry

Event Loop Block 감지는 Node.js 메인 스레드의 event loop가 지정된 임계값보다 오래 블로킹될 때를 모니터링합니다. Node SDK는 이러한 이벤트를 자동으로 수집된 스택 트레이스와 함께 Sentry에 보고하여 블로킹 코드를 식별할 수 있도록 ...

필터링 | Next.js용 Sentry

앱에 Sentry를 추가하면 오류와 성능에 대한 많은 유용한 정보를 얻을 수 있습니다. 그리고 많은 정보는 적절한 정보가 합리적인 볼륨으로 들어올 때 좋은 것입니다.

통합 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations

Amqplib | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Anr | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

Anthropic | Next.js용 Sentry

모든 런타임을 사용하는 메타 프레임워크 애플리케이션에서는 Anthropic 클라이언트 인스턴스를 로 수동으로 래핑해야 합니다. 브라우저 사이드 사용 섹션의 안내를 참고하세요.

Breadcrumbs | Next.js용 Sentry

이 통합은 콘솔 로그를 breadcrumb로 수집합니다(오류 컨텍스트 파악에 매우 유용합니다!). 하지만 애플리케이션 전체에서 로그를 검색하고 쿼리해야 한다면 대신 Sentry Logs를 사용하세요. 를 설정하고, SDK 구성에 Sentry console logging...

BrowserApiErrors | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

BrowserProfiling | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다.

BrowserSession | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다.

BrowserTracing | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

CaptureConsole | Next.js용 Sentry

이 통합은 모든 Console API 호출을 캡처하고, 로그 레벨에 따라 SDK의 captureMessage 또는 captureException 호출을 사용해 Sentry로 리디렉션합니다. 그런 다음 기본 네이티브 동작을 유지하기 위해 다시 트리거합니다:

Child Process 통합 | Next.js용 Sentry

이 통합은 Node.js 에서만 작동하며 SDK 버전 이상이 필요합니다.

Console | Next.js용 Sentry

이 통합은 콘솔 로그를 breadcrumb로 수집합니다(오류 컨텍스트에 매우 유용합니다!). 하지만 애플리케이션 전체에서 로그를 검색하고 쿼리해야 한다면, 대신 Sentry Logs를 사용하세요. 를 설정하고, SDK 구성에 Sentry console logging i...

ContextLines | Next.js용 Sentry

이 통합은 현재 페이지 HTML의 인라인 JavaScript 소스 코드(예: 태그 안의 JS)를 캡처된 오류의 스택 트레이스에 추가합니다. HTML에서 참조하는 에셋의 소스 코드(예: )는 수집할 수 *없습니다*.

커스텀 통합 | Next.js용 Sentry

SDK에 기본 포함된 통합 외에도, 커스텀 통합을 직접 작성할 수 있습니다.

Dataloader | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

Dedupe | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

이벤트 루프 차단 | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다.

ExtraErrorData | Next.js용 Sentry

이 통합은 에러 객체에서 네이티브가 아닌 모든 속성을 추출하여 이벤트에 추가 데이터로 첨부합니다. 에러 객체에 메서드가 있으면 ExtraErrorData 통합이 이를 실행해 추가 정보를 추출합니다.

범용 기능 플래그 통합 | Sentry for Next.js

Feature Flags 통합을 사용하면 API를 통해 기능 플래그 평가를 수동으로 추적할 수 있습니다. 이러한 평가는 메모리에 보관되며, 오류 및 트랜잭션 이벤트가 발생할 때 Sentry로 전송됩니다. 현재는 boolean 플래그 평가만 지원합니다.

FileSystem | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/fs

FunctionToString | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

Generic Pool | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

GlobalHandlers | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/globalhandlers

Google Gen AI | Next.js용 Sentry

모든 런타임을 사용하는 메타 프레임워크 애플리케이션의 경우, Google Gen AI 클라이언트 인스턴스를 로 수동으로 래핑해야 합니다. 브라우저 사이드 사용 섹션의 안내를 참고하세요.

GraphQL | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

GraphQLClient | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

Http | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

HttpClient | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다.

HttpContext | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

InboundFilters | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

Kafka | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Knex | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/knex

LangChain | Next.js용 Sentry

모든 런타임을 사용하는 메타 프레임워크 애플리케이션의 경우, 로 LangChain 콜백 핸들러를 수동으로 생성해야 합니다. 브라우저 측 사용 섹션의 안내를 참고하세요.

LangGraph | Next.js용 Sentry

모든 런타임을 사용하는 메타 프레임워크 애플리케이션에서는 컴파일된 그래프를 로 수동 래핑해야 합니다. 브라우저 측 사용 섹션의 안내를 참고하세요.

LaunchDarkly | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

LinkedErrors | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/linkederrors

LocalVariables | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

LRU Memoizer | Sentry for Next.js

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

ModuleMetadata | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다.

모듈 | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

MongoDB | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mongo

Mongoose | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mongoose

MySQL | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mysql

MySQL2 | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

컨텍스트 | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다.

NodeFetch | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

NodeProfiling | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

OnUncaughtException | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno) 내부에서만 동작합니다.

OpenAI | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai

OpenFeature | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Pino | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Postgres | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Prisma | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Prisma | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/prisma

Redis | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Replay | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

ReplayCanvas | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

ReportingObserver | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

RequestData | Next.js용 Sentry

이 통합은 백엔드에서 요청 처리 중 발생하는 트랜잭션 및 오류 이벤트에 들어오는 요청의 데이터를 추가합니다.

RewriteFrames | Next.js용 Sentry

이 통합을 사용하면 스택 트레이스의 각 프레임에 변환을 적용할 수 있습니다. 단순한 시나리오에서는 프레임이 시작된 파일 이름을 변경하는 데 사용할 수 있으며, 반복 함수(iteratee)를 전달해 임의의 변환을 적용할 수도 있습니다.

Statsig | Sentry for Next.js

이 통합은 브라우저 환경 내부에서만 동작합니다. 또한 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Supabase | Next.js용 Sentry

은 Supabase 클라이언트에 계측(instrumentation)을 추가하여 인증 및 데이터베이스 작업 모두에 대한 span을 수집합니다.

Tedious | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

trpcMiddleware | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

OnUnhandledRejection | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno) 내부에서만 동작합니다.

Unleash | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Vercel AI | Next.js용 Sentry

Node.js, Cloudflare Workers, Vercel Edge Functions, Bun에서는 SDK 버전 이상이 필요합니다. Deno에서는 SDK 버전 이상이 필요합니다.

WebWorker | Next.js용 Sentry

이 통합은 와 함께 브라우저의 메인 스레드와 하나 이상의 WebWorkers 간 통신을 설정합니다. 전달된 워커들의 메시지를 수신하고 이를 메인 스레드로 전달합니다.

WinterCGFetch | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/wintercgfetch

ZodErrors | Next.js용 Sentry

Zod Errors 통합은 Zod 스키마 검증을 사용하는 애플리케이션의 오류 보고를 강화합니다. Zod 검증이 실패하면, 이 통합은 상세한 검증 오류( 인스턴스)를 수집하고 이를 Sentry 이벤트에 추가 데이터로 첨부합니다.

옵션 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options

Releases & Health | Sentry for Next.js

릴리스는 environment에 배포되는 코드의 버전입니다. Sentry에 릴리스 정보를 제공하면 다음을 할 수 있습니다.

Transports | Next.js용 Sentry

JavaScript SDK는 이벤트를 Sentry로 전송하기 위해 를 사용합니다. 최신 브라우저에서는 대부분의 transport가 브라우저의 API를 사용해 이벤트를 전송합니다. 연결 부족으로 전송에 실패하면 transport는 해당 이벤트를 버립니다.

트리 셰이킹 | Next.js용 Sentry

Sentry Next.js SDK는 몇 가지 추가 구성과 함께 webpack 빌드에 대한 트리 셰이킹을 지원합니다.

Crons 설정 | Next.js용 Sentry

구현을 완료하면 오류 해결, 타임아웃 감지, 서비스 중단 방지를 돕는 알림과 메트릭을 받을 수 있습니다.

문제 해결 | Next.js용 Sentry

반복 작업 오류가 모니터 상세 페이지에 표시되지 않는 이유는 무엇인가요?

데이터 관리 | Next.js용 Sentry

Sentry SDK가 어떤 데이터를 수집하는지 확인하세요.

수집되는 데이터 | Next.js용 Sentry

Sentry는 데이터 프라이버시를 매우 중요하게 여기며, 특히 개인 식별 정보(PII) 데이터와 관련해 데이터 안전을 우선하는 기본 설정을 제공합니다. 애플리케이션에 Sentry SDK를 추가하면, 애플리케이션의 런타임 및 빌드 타임 동안 데이터를 수집하여 Sentry...

민감 데이터 스크러빙 | Next.js용 Sentry

모든 서드파티 서비스와 마찬가지로, 어떤 데이터가 Sentry로 전송되는지 이해하고, 관련이 있다면 민감한 데이터가 Sentry 서버에 아예 도달하지 않도록 하거나 최소한 저장되지 않도록 보장하는 것이 중요합니다.

이벤트 보강 | Next.js용 Sentry

Sentry SDK가 자동으로 수집하는 데이터에 더해, 디버깅에 도움이 되도록 이벤트에 추가 데이터를 넣을 수 있습니다.

Attachments | Next.js용 Sentry

Sentry는 config 파일이나 로그 파일 같은 추가 파일을 첨부 파일로 저장하여, 추가 조사를 위해 이벤트를 더 풍부하게 만들 수 있습니다.

브레드크럼 | Next.js용 Sentry

수동 브레드크럼도 충분히 잘해왔지만, 이제 Sentry's got logs를 사용할 수 있습니다. 구조화되어 있고, 검색 가능하며, 알림 설정이나 쿼리도 훨씬 쉽습니다. 확인해 보세요!

Event Processors | Next.js용 Sentry

스코프 레벨 또는 전역에서 자체 이벤트 프로세서를 추가해, 이벤트에 추가 데이터를 보강할 수 있습니다. 이벤트 프로세서는 및 과 비슷하지만, 핵심적인 차이점이 두 가지 있습니다.

이벤트 핑거프린팅 | Next.js용 Sentry

모든 이벤트에는 핑거프린트가 있습니다. 동일한 핑거프린트를 가진 이벤트는 하나의 이슈로 함께 그룹화됩니다.

이벤트 레벨 | Sentry for Next.js

레벨은 로깅 레벨과 유사하며, 일반적으로 SDK에서 기본으로 추가됩니다. 에서 전용 레벨을 직접 지정하거나, scope에 레벨을 설정해 모든 이벤트에 적용할 수 있습니다.

요청 격리 | Sentry for Next.js

서버 사이드 환경에서는 격리 스코프가 요청 경계를 기준으로 자동으로 포크됩니다. 이 작업은 SDK가 자동으로 수행합니다. 그 결과, 각 요청은 자체 격리 스코프를 가지며, 격리 스코프에 설정된 데이터는 해당 요청 중에 캡처된 이벤트에만 적용됩니다.

스코프 | Sentry for Next.js

이벤트가 캡처되어 Sentry로 전송되면, SDK는 해당 이벤트 데이터에 현재 스코프의 추가 정보를 병합합니다. SDK는 보통 프레임워크 통합에서 스코프를 자동으로 관리하므로, 일반적으로 이를 신경 쓸 필요는 없습니다. 다만 스코프가 무엇인지, 그리고 이를 어떻게 활용...

태그 | Next.js용 Sentry

이벤트의 모든 태그는 물론, 태그의 빈도와 Sentry가 해당 태그를 마지막으로 확인한 시점까지 자동으로 인덱싱됩니다. 또한 고유 태그 수를 추적하며, 다양한 이슈의 핫스팟을 파악하는 데 도움을 줍니다.

기능 플래그 설정 | Next.js용 Sentry

기능 플래그를 평가하기 위해 서드파티 SDK를 사용하는 경우, 해당 평가를 추적하도록 Sentry SDK 통합을 활성화할 수 있습니다. 통합은 제공자별로 다릅니다. 지원되는 SDK 문서는 아래에 나와 있습니다.

로그 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/logs

수동 설정 | Next.js용 Sentry

가장 빠르게 설정하려면 wizard installer 사용을 권장합니다.

Pages Router 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/pages-router

Webpack 설정 | Next.js용 Sentry

이 가이드는 Webpack을 사용하는 Next.js 애플리케이션(Next.js 15 이전의 기본 번들러)에 대한 설정 차이점을 다룹니다. 먼저 메인 수동 설정을 완료한 뒤, 이 Webpack 전용 설정을 적용하세요.

Metrics 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/metrics

마이그레이션 가이드 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration

4.x에서 5.x/6.x로 마이그레이션 | Sentry for Next.js

에서 로 바로 업그레이드할 것을 권장합니다. 에서 로 마이그레이션할 때는 SDK API에 대한 호환성 깨짐 변경 사항이 없습니다.

6.x에서 7.x로 마이그레이션 | Sentry for Next.js

JavaScript SDK의 버전을 사용하려면 자체 호스팅 Sentry 버전이 이상이어야 합니다.

7.x에서 8.x로 마이그레이션 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration/v7-to-v8

7.x의 사용 중단 항목 | Sentry for Next.js

의 대부분 사용 중단 항목은 codemod를 사용해 SDK 사용 방식을 자동으로 업데이트하여 해결할 수 있습니다. 는 Node 18+가 필요합니다.

새로운 Tracing API | Sentry for Next.js

SDK 릴리스에는 성능 모니터링을 위한 새로운 API가 도입되었습니다. 이 API들은 성능 데이터가 Sentry로 수집되고 보고되는 방식을 더 세밀하게 제어할 수 있도록 설계되었습니다.

8.x에서 9.x로 마이그레이션 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration/v8-to-v9

9.x에서 10.x로 마이그레이션 | Next.js용 Sentry

Sentry JavaScript SDK 버전 10은 주로 기반 OpenTelemetry 의존성을 v2로 업그레이드하는 데 초점을 맞추며, 브레이킹 체인지는 최소화되었습니다.

OpenTelemetry 지원 | Next.js용 Sentry

Sentry SDK는 내부적으로 OpenTelemetry를 사용합니다. 즉, span을 내보내는 모든 OpenTelemetry 계측은 추가 설정 없이 자동으로 Sentry에 수집됩니다.

기존 OpenTelemetry 설정 사용 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/opentelemetry/custom-setup

OpenTelemetry API 사용 | Sentry for Next.js

Sentry는 OpenTelemetry API를 기본적으로 지원합니다. OpenTelemetry API를 사용해 시작된 모든 span은 Sentry가 자동으로 수집하며, Sentry SDK로 시작된 모든 span은 OpenTelemetry로 자동 전파됩니다.

Next.js | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs

AI Agent Monitoring 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/ai-agent-monitoring

Mastra | Next.js용 Sentry

이는 Node.js Sentry SDK를 사용하는 Mastra AI 트레이싱용 서버 사이드 exporter입니다. Node.js 또는 호환 런타임이 필요합니다. 패키지가 필요합니다.

특수 사용 사례 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/best-practices

Cloudflare Workers에 배포하기 | Next.js용 Sentry

Cloudflare Workers에서 Sentry와 함께 Next.js 애플리케이션을 배포하는 방법은 Cloudflare의 Next.js 가이드를 참조하세요.

마이크로 프런트엔드 | Sentry for Next.js

여러 Sentry 인스턴스 | Next.js용 Sentry

오프라인 캐싱 | Next.js용 Sentry

Sentry Testkit | Next.js용 Sentry

공유 환경 / 브라우저 확장 프로그램 | Sentry for Next.js

공유 환경에서 SDK를 사용할 때는 JavaScript SDK 이상 사용을 권장합니다. 이전 SDK 버전에서 이상으로 업그레이드하려면 마이그레이션 문서를 확인하세요.

Web Workers | Next.js용 Sentry

오류 캡처 | Next.js용 Sentry

확장 구성 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration

API | Sentry for Next.js

이 페이지는 SDK에서 사용할 수 있는 모든 최상위 API를 보여줍니다. 이 API들은 다음을 위한 기본 방법으로 사용할 수 있습니다.

빌드 옵션 | Sentry for Next.js

Event Loop Block 감지 | Next.js용 Sentry

필터링 | Next.js용 Sentry

통합 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations

Amqplib | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Anr | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

Anthropic | Next.js용 Sentry

Breadcrumbs | Next.js용 Sentry

BrowserApiErrors | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

BrowserProfiling | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다.

BrowserSession | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다.

BrowserTracing | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

CaptureConsole | Next.js용 Sentry

Child Process 통합 | Next.js용 Sentry

이 통합은 Node.js 에서만 작동하며 SDK 버전 이상이 필요합니다.

Console | Next.js용 Sentry

ContextLines | Next.js용 Sentry

커스텀 통합 | Next.js용 Sentry

SDK에 기본 포함된 통합 외에도, 커스텀 통합을 직접 작성할 수 있습니다.

Dataloader | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

Dedupe | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

이벤트 루프 차단 | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다.

ExtraErrorData | Next.js용 Sentry

범용 기능 플래그 통합 | Sentry for Next.js

FileSystem | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/fs

FunctionToString | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

Generic Pool | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

GlobalHandlers | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/globalhandlers

Google Gen AI | Next.js용 Sentry

GraphQL | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

GraphQLClient | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

Http | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

HttpClient | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다.

HttpContext | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

InboundFilters | Next.js용 Sentry

이 통합은 기본적으로 활성화되어 있습니다. 기본 통합을 수정하려면 여기를 읽어보세요.

Kafka | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Knex | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/knex

LangChain | Next.js용 Sentry

LangGraph | Next.js용 Sentry

LaunchDarkly | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

LinkedErrors | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/linkederrors

LocalVariables | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

LRU Memoizer | Sentry for Next.js

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

ModuleMetadata | Next.js용 Sentry

이 통합은 브라우저 환경에서만 동작합니다.

모듈 | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

MongoDB | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mongo

Mongoose | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mongoose

MySQL | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/mysql

MySQL2 | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

컨텍스트 | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다.

NodeFetch | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다.

NodeProfiling | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 동작합니다.

OnUncaughtException | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno) 내부에서만 동작합니다.

OpenAI | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai

OpenFeature | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Pino | Next.js용 Sentry

이 통합은 Node.js 런타임에서만 작동합니다. SDK 버전 이상이 필요합니다.

Postgres | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Prisma | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Prisma | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/prisma

Redis | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 작동합니다.

Replay | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

ReplayCanvas | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 작동합니다.

ReportingObserver | Next.js용 Sentry

이 통합은 브라우저 환경에서만 작동합니다.

RequestData | Next.js용 Sentry

이 통합은 백엔드에서 요청 처리 중 발생하는 트랜잭션 및 오류 이벤트에 들어오는 요청의 데이터를 추가합니다.

RewriteFrames | Next.js용 Sentry

Statsig | Sentry for Next.js

이 통합은 브라우저 환경 내부에서만 동작합니다. 또한 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Supabase | Next.js용 Sentry

은 Supabase 클라이언트에 계측(instrumentation)을 추가하여 인증 및 데이터베이스 작업 모두에 대한 span을 수집합니다.

Tedious | Next.js용 Sentry

이 통합은 Node.js 및 Bun 런타임에서만 동작합니다. SDK 버전 이상이 필요합니다.

trpcMiddleware | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno)에서만 작동합니다.

OnUnhandledRejection | Next.js용 Sentry

이 통합은 서버 환경(Node.js, Bun, Deno) 내부에서만 동작합니다.

Unleash | Next.js용 Sentry

이 통합은 브라우저 환경 내부에서만 동작합니다. 패키지 기반 설치(예: 또는 )에서만 사용할 수 있습니다.

Vercel AI | Next.js용 Sentry

Node.js, Cloudflare Workers, Vercel Edge Functions, Bun에서는 SDK 버전 이상이 필요합니다. Deno에서는 SDK 버전 이상이 필요합니다.

WebWorker | Next.js용 Sentry

WinterCGFetch | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/wintercgfetch

ZodErrors | Next.js용 Sentry

옵션 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options

Releases & Health | Sentry for Next.js

릴리스는 environment에 배포되는 코드의 버전입니다. Sentry에 릴리스 정보를 제공하면 다음을 할 수 있습니다.

Transports | Next.js용 Sentry

트리 셰이킹 | Next.js용 Sentry

Sentry Next.js SDK는 몇 가지 추가 구성과 함께 webpack 빌드에 대한 트리 셰이킹을 지원합니다.

Crons 설정 | Next.js용 Sentry

구현을 완료하면 오류 해결, 타임아웃 감지, 서비스 중단 방지를 돕는 알림과 메트릭을 받을 수 있습니다.

문제 해결 | Next.js용 Sentry

반복 작업 오류가 모니터 상세 페이지에 표시되지 않는 이유는 무엇인가요?

데이터 관리 | Next.js용 Sentry

Sentry SDK가 어떤 데이터를 수집하는지 확인하세요.

수집되는 데이터 | Next.js용 Sentry

민감 데이터 스크러빙 | Next.js용 Sentry

이벤트 보강 | Next.js용 Sentry

Sentry SDK가 자동으로 수집하는 데이터에 더해, 디버깅에 도움이 되도록 이벤트에 추가 데이터를 넣을 수 있습니다.

Attachments | Next.js용 Sentry

Sentry는 config 파일이나 로그 파일 같은 추가 파일을 첨부 파일로 저장하여, 추가 조사를 위해 이벤트를 더 풍부하게 만들 수 있습니다.

브레드크럼 | Next.js용 Sentry

Event Processors | Next.js용 Sentry

이벤트 핑거프린팅 | Next.js용 Sentry

모든 이벤트에는 핑거프린트가 있습니다. 동일한 핑거프린트를 가진 이벤트는 하나의 이슈로 함께 그룹화됩니다.

이벤트 레벨 | Sentry for Next.js

요청 격리 | Sentry for Next.js

스코프 | Sentry for Next.js

태그 | Next.js용 Sentry

기능 플래그 설정 | Next.js용 Sentry

로그 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/logs

수동 설정 | Next.js용 Sentry

가장 빠르게 설정하려면 wizard installer 사용을 권장합니다.

Pages Router 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/pages-router

Webpack 설정 | Next.js용 Sentry

Metrics 설정 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/metrics

마이그레이션 가이드 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration

4.x에서 5.x/6.x로 마이그레이션 | Sentry for Next.js

에서 로 바로 업그레이드할 것을 권장합니다. 에서 로 마이그레이션할 때는 SDK API에 대한 호환성 깨짐 변경 사항이 없습니다.

6.x에서 7.x로 마이그레이션 | Sentry for Next.js

JavaScript SDK의 버전을 사용하려면 자체 호스팅 Sentry 버전이 이상이어야 합니다.

7.x에서 8.x로 마이그레이션 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration/v7-to-v8

7.x의 사용 중단 항목 | Sentry for Next.js

의 대부분 사용 중단 항목은 codemod를 사용해 SDK 사용 방식을 자동으로 업데이트하여 해결할 수 있습니다. 는 Node 18+가 필요합니다.

새로운 Tracing API | Sentry for Next.js

8.x에서 9.x로 마이그레이션 | Sentry for Next.js

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/migration/v8-to-v9

9.x에서 10.x로 마이그레이션 | Next.js용 Sentry

Sentry JavaScript SDK 버전 10은 주로 기반 OpenTelemetry 의존성을 v2로 업그레이드하는 데 초점을 맞추며, 브레이킹 체인지는 최소화되었습니다.

OpenTelemetry 지원 | Next.js용 Sentry

Sentry SDK는 내부적으로 OpenTelemetry를 사용합니다. 즉, span을 내보내는 모든 OpenTelemetry 계측은 추가 설정 없이 자동으로 Sentry에 수집됩니다.

기존 OpenTelemetry 설정 사용 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/opentelemetry/custom-setup

OpenTelemetry API 사용 | Sentry for Next.js

프로파일링 설정 | Sentry for Next.js

애플리케이션 성능을 이해하기 위해 브라우저 프로파일링을 시작하세요.

브라우저 프로파일링 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/profiling/browser

Node Profiling | Next.js용 Sentry

기본적으로 아래 예시처럼 트랜잭션으로 scope를 구성하지 않으면 Sentry 오류 이벤트에 trace 컨텍스트가 포함되지 않습니다.

샘플링 | Next.js용 Sentry

앱에 Sentry를 추가하면, 그렇지 않으면 얻기 어려운 오류 및 성능에 대한 매우 가치 있는 정보를 많이 얻을 수 있습니다. 그리고 많은 정보는 적절한 양으로, 올바른 정보일 때 유용합니다.

보안 정책 보고 설정 | Next.js용 Sentry

Sentry는 적절한 HTTP 헤더를 설정해 Content-Security-Policy (CSP) 위반 정보를 수집할 수 있도록 지원하며, 이 설정을 통해 위반 보고가 *report-uri*에 지정된 Sentry 엔드포인트로 전송됩니다.

Session Replay 설정 | Next.js용 Sentry

질문이나 피드백이 있거나 버그를 신고하려면, 관련 리플레이 링크 또는 가능하다면 리플레이를 기록하려는 페이지의 공개 접근 가능한 URL을 포함해 GitHub issue를 열어 주세요.

구성 | Sentry for Next.js

질문이나 피드백이 있거나 버그를 신고하려면, 관련 replay 링크 또는 가능하다면 replay 기록을 시도 중인 페이지의 공개 접근 가능한 URL과 함께 GitHub issue를 열어주세요.

리플레이 이슈 | Next.js용 Sentry

Project Settings > Replay로 이동해 각 이슈 유형의 감지를 on/off로 전환하여 어떤 이슈 유형을 생성할지 구성할 수 있습니다. 기본값은 모든 이슈 유형이 활성화되어 있습니다.

개인정보 보호 | Next.js용 Sentry

질문이나 피드백이 있거나 버그를 신고하고 싶다면, 관련 리플레이 링크 또는 가능하면 리플레이를 기록하려는 페이지의 공개 접근 가능한 URL과 함께 GitHub issue를 열어 주세요.

문제 해결 | Sentry for Next.js

리플레이가 내 애플리케이션과 일치하지 않습니다

세션 이해하기 | Sentry for Next.js

대부분의 경우, Replay 샘플링 비율만 설정하면 원하는 기록 데이터를 캡처하기 시작하기에 충분합니다. 더 복잡한 경우에는 세션이 어떻게 동작하는지와 이를 수동으로 제어하는 방법을 이해하는 것이 도움이 됩니다.

소스 맵 | Next.js용 Sentry

소스 맵은 최소화된 프로덕션 코드를 원본 소스로 다시 매핑해, 이해하기 어려운 줄 번호 대신 읽기 쉬운 스택 트레이스를 제공합니다.

소스 맵 문제 해결 | Sentry for Next.js

이전에 소스 맵을 설정했다면 도구(SDK, bundler plugins, Sentry CLI)를 업데이트하는 것을 권장합니다. 일반적으로는 오래된 버전으로 문제를 해결하려고 하기보다 최신 버전으로 업그레이드하고 현재 프로세스를 따르는 편이 더 쉽습니다.

Debug ID란 무엇인가 | Sentry for Next.js

이 문서는 Debug ID를 심층적으로 설명하며, Debug ID가 어떻게 동작하는지와 Sentry가 이를 권장하는 이유를 다룹니다. 소스맵 업로드 방법 가이드를 찾고 있다면 Uploading Source Maps를 참고하세요.

레거시 업로드 방법 | Sentry for Next.js

Sentry는 source map 처리를 위한 새로운 프로세스로 전환했습니다. 이 프로세스를 "source mapping with debug IDs"라고 부릅니다.

esbuild | Next.js용 Sentry

이 가이드는 Sentry SDK 버전 이상을 사용하고 있다고 가정합니다. 이전 버전을 사용 중이고 소스 맵을 업로드하려면 SDK를 최신 버전으로 업그레이드하는 것을 권장합니다.

Ionic Capacitor 빌드 | Sentry for Next.js

이 가이드에서는 도구를 사용해 TypeScript용 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Ionic | Sentry for Next.js

이 가이드에서는 도구를 사용해 TypeScript용 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Rollup | Next.js용 Sentry

SystemJS | Next.js용 Sentry

이 가이드에서는 도구를 사용해 SystemJS의 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

TypeScript (tsc) | Next.js용 Sentry

이 가이드에서는 도구를 사용해 TypeScript 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

UglifyJS | Next.js용 Sentry

이 가이드에서는 도구를 사용해 SystemJS의 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Vite | Next.js용 Sentry

이 가이드는 Sentry SDK 버전 이상을 사용한다고 가정합니다. 이전 버전을 사용 중이고 source map을 업로드하려면, SDK를 최신 버전으로 업그레이드하는 것을 권장합니다.

Webpack | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/sourcemaps/uploading/webpack

트레이싱 설정 | Next.js용 Sentry

트레이싱은 Next.js 애플리케이션을 통과하는 요청의 타이밍과 흐름을 캡처합니다. tracing과 Sentry가 서비스 전반의 성능을 추적하기 위해 트레이스를 사용하는 방법을 자세히 알아보세요.

샘플링 구성 | Sentry for Next.js

Sentry의 tracing 기능은 분산 trace를 수집하고, 속성을 추가하고, 애플리케이션 전반의 span 성능을 추적해 애플리케이션 성능을 모니터링할 수 있도록 도와줍니다. 하지만 모든 transaction의 trace를 수집하면 상당한 양의 데이터가 생성될 수 ...

분산 추적 설정 | Sentry for Next.js

분산 추적은 요청이 애플리케이션 아키텍처의 여러 계층을 통과할 때 그 경로를 연결하고 기록합니다. 아키텍처가 서로 다른 서브도메인(예: , )에 있는 여러 서비스로 구성되어 있다면, 분산 추적을 통해 이벤트가 한 서비스에서 다른 서비스로 이동하는 경로를 따라갈 수 있습...

사용자 지정 Trace 전파 | Next.js용 Sentry

이 페이지에서는 JavaScript 애플리케이션 안팎으로 trace 정보를 수동으로 전파하는 방법을 배웁니다.

CORS 문제 다루기 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/distributed-tracing/dealing-with-cors-issues

계측 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation

자동 계측 | Next.js용 Sentry

스팬을 수집하려면, 아직 설정하지 않았다면 먼저 앱에서 트레이싱을 설정해야 합니다.

캐시 계측 | Next.js용 Sentry

캐시는 데이터 조회를 더 빠르게 만들어 애플리케이션 성능을 향상시키는 데 사용할 수 있습니다. 잠재적으로 느린 데이터 계층에서 데이터를 가져오는 대신(최상의 경우) 애플리케이션이 메모리에서 데이터를 가져오기 때문입니다. 캐싱은 Q\\&A 포털, 게임, 미디어 공유, 소셜...

MCP 서버 계측 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation/mcp-module

큐 계측 | Sentry for Next.js

메시징 큐에 대한 성능 데이터를 확보하려면 큐 프로듀서와 컨슈머 주변에 커스텀 span 및 transaction을 계측해야 합니다.

HTTP 요청 계측하기 | Sentry for Next.js

설정할 수 있는 데이터에 대한 자세한 내용은 Requests Module developer specifications를 참고하세요.

스팬 메트릭 전송 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/span-metrics

계측 예제 | Sentry for Next.js

이 페이지의 샘플 코드는 데모 목적 전용입니다. 프로덕션 환경에 바로 사용할 수 없으며, 사용하는 언어 또는 프레임워크에 직접 적용되지 않을 수 있습니다.

문제 해결 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/troubleshooting

문제 해결 | Next.js용 Sentry

Sentry SDK를 설정했는데 Sentry로 데이터가 전송되지 않는다면:

지원되는 브라우저 | Sentry for Next.js

Sentry의 최신 JavaScript SDK는 ES2020 호환성을 요구합니다. 최소 지원 브라우저 버전은 다음과 같습니다.

사용자 피드백 설정 | Sentry for Next.js

User Feedback 기능을 사용하면 먼저 오류 이벤트가 발생하지 않아도, 애플리케이션 내부 어디에서나 언제든 사용자 피드백을 수집할 수 있습니다. 반면 Crash-Report Modal 기능은 오류 이벤트가 발생했을 때 사용자 피드백을 요청할 수 있게 해줍니다.

구성 | Sentry for Next.js

JavaScript SDK 버전 7에서는 User Feedback이 베타 통합으로 출시되었습니다. migration guide를 따라 SDK를 최신 버전으로 업데이트하는 것을 권장합니다.

설정 | Next.js용 Sentry

사용자 피드백 위젯은 다양한 사용자 지정 옵션을 제공하며, 제공되는 옵션이 충분하지 않다면 자체 UI를 사용할 수 있습니다.

프로파일링 설정 | Sentry for Next.js

애플리케이션 성능을 이해하기 위해 브라우저 프로파일링을 시작하세요.

브라우저 프로파일링 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/profiling/browser

Node Profiling | Next.js용 Sentry

기본적으로 아래 예시처럼 트랜잭션으로 scope를 구성하지 않으면 Sentry 오류 이벤트에 trace 컨텍스트가 포함되지 않습니다.

샘플링 | Next.js용 Sentry

보안 정책 보고 설정 | Next.js용 Sentry

Session Replay 설정 | Next.js용 Sentry

구성 | Sentry for Next.js

리플레이 이슈 | Next.js용 Sentry

개인정보 보호 | Next.js용 Sentry

문제 해결 | Sentry for Next.js

리플레이가 내 애플리케이션과 일치하지 않습니다

세션 이해하기 | Sentry for Next.js

소스 맵 | Next.js용 Sentry

소스 맵은 최소화된 프로덕션 코드를 원본 소스로 다시 매핑해, 이해하기 어려운 줄 번호 대신 읽기 쉬운 스택 트레이스를 제공합니다.

소스 맵 문제 해결 | Sentry for Next.js

Debug ID란 무엇인가 | Sentry for Next.js

레거시 업로드 방법 | Sentry for Next.js

Sentry는 source map 처리를 위한 새로운 프로세스로 전환했습니다. 이 프로세스를 "source mapping with debug IDs"라고 부릅니다.

esbuild | Next.js용 Sentry

Ionic Capacitor 빌드 | Sentry for Next.js

이 가이드에서는 도구를 사용해 TypeScript용 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Ionic | Sentry for Next.js

이 가이드에서는 도구를 사용해 TypeScript용 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Rollup | Next.js용 Sentry

SystemJS | Next.js용 Sentry

이 가이드에서는 도구를 사용해 SystemJS의 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

TypeScript (tsc) | Next.js용 Sentry

이 가이드에서는 도구를 사용해 TypeScript 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

UglifyJS | Next.js용 Sentry

이 가이드에서는 도구를 사용해 SystemJS의 소스 맵을 성공적으로 업로드하는 방법을 알아봅니다.

Vite | Next.js용 Sentry

Webpack | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/sourcemaps/uploading/webpack

트레이싱 설정 | Next.js용 Sentry

샘플링 구성 | Sentry for Next.js

분산 추적 설정 | Sentry for Next.js

사용자 지정 Trace 전파 | Next.js용 Sentry

이 페이지에서는 JavaScript 애플리케이션 안팎으로 trace 정보를 수동으로 전파하는 방법을 배웁니다.

CORS 문제 다루기 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/distributed-tracing/dealing-with-cors-issues

계측 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation

자동 계측 | Next.js용 Sentry

스팬을 수집하려면, 아직 설정하지 않았다면 먼저 앱에서 트레이싱을 설정해야 합니다.

캐시 계측 | Next.js용 Sentry

MCP 서버 계측 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation/mcp-module

큐 계측 | Sentry for Next.js

메시징 큐에 대한 성능 데이터를 확보하려면 큐 프로듀서와 컨슈머 주변에 커스텀 span 및 transaction을 계측해야 합니다.

HTTP 요청 계측하기 | Sentry for Next.js

설정할 수 있는 데이터에 대한 자세한 내용은 Requests Module developer specifications를 참고하세요.

스팬 메트릭 전송 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/span-metrics

계측 예제 | Sentry for Next.js

문제 해결 | Next.js용 Sentry

원본 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/troubleshooting

문제 해결 | Next.js용 Sentry

Sentry SDK를 설정했는데 Sentry로 데이터가 전송되지 않는다면:

지원되는 브라우저 | Sentry for Next.js

Sentry의 최신 JavaScript SDK는 ES2020 호환성을 요구합니다. 최소 지원 브라우저 버전은 다음과 같습니다.

사용자 피드백 설정 | Sentry for Next.js

구성 | Sentry for Next.js

JavaScript SDK 버전 7에서는 User Feedback이 베타 통합으로 출시되었습니다. migration guide를 따라 SDK를 최신 버전으로 업데이트하는 것을 권장합니다.

설정 | Next.js용 Sentry

사용자 피드백 위젯은 다양한 사용자 지정 옵션을 제공하며, 제공되는 옵션이 충분하지 않다면 자체 UI를 사용할 수 있습니다.

Zod

TypeScript 우선 스키마 유효성 검사 및 정적 타입 추론

스키마 정의하기

데이터를 검증하려면 먼저 _스키마_ 를 정의해야 합니다. 스키마는 간단한 원시 값부터 복잡한 중첩 객체와 배열까지를 나타내는 _타입_ 을 나타냅니다.

기본 사용법

이 페이지에서는 스키마 생성, 데이터 파싱, 추론된 타입 사용법의 기본을 안내합니다. Zod의 스키마 API에 대한 전체 문서는 Defining schemas를 참고하세요.

[Useful codecs](https://zod.dev/codecs?id=useful-codecs)

API는 문자열 값(예: , , , 등)을 으로 변환합니다. 기본적으로 시 는 로, 는 로 변환됩니다.

에코시스템

Zod 위에 구축되었거나 Zod를 네이티브로 지원하는 도구들이 계속 늘어나고 있습니다! Zod 기반 도구나 라이브러리를 만들었다면 Twitter에서 알려주시거나 Discussion을 시작해 주세요. 아래에 추가하고 트윗으로 공유하겠습니다.

[오류 우선순위](https://zod.dev/error-customization?id=error-precedence)

모든 로케일은 에서 로 내보내지므로 편리하게 사용할 수 있습니다. 일부 번들러에서는 tree-shake되지 않을 수 있습니다.

index

영어 기술 문서를 한국어로 번역했습니다(마크다운 구조 유지).

[z.fromJSONSchema()](https://zod.dev/json-schema?id=zfromjsonschema)

💎 Zod 4는 새로운 기능인 네이티브 JSON Schema 변환을 도입합니다. JSON Schema는 JSON의 구조를 기술하는 표준으로, OpenAPI 정의나 AI용 구조화된 출력 정의에 널리 사용됩니다.

index

이 접근 방식은 입력이 실제로 어떤 서브클래스인지(이 경우 )에 대한 타입 정보를 잃습니다. 즉 결과에서 같은 문자열 전용 메서드를 사용할 수 없습니다. 대신 제네릭 매개변수는 핵심 Zod 스키마 인터페이스를 확장해야 합니다:

Zod > Zod은 정적 타입 추론을 제공하는 TypeScript 중심 스키마 검증 라이브러리입니다. 이 문서는 Zod 4의 기능, API, 사용 패턴을 포괄적으로 다룹니다.

index

Zod Core

이 서브 패키지는 Zod 및 Zod Mini에서 사용하는 핵심 클래스와 유틸리티를 내보냅니다. 직접 사용할 목적으로 만들어진 것이 아니라 다른 패키지에서 확장하도록 설계되었습니다. 다음을 구현합니다:

[기본 로케일 없음](https://zod.dev/packages/mini?id=no-default-locale)

Zod Mini 문서는 일반 Zod 문서와 탭 코드 블록을 통해 섞여 있습니다. 이 페이지는 Zod Mini가 왜 존재하며, 언제 사용해야 하고, 일반 Zod와 어떤 주요 차이가 있는지 설명합니다.

index

릴리스 노트

1년간의 활발한 개발 끝에: Zod 4가 이제 안정화되었습니다! 더 빠르고, 가볍고, 효율이 더 좋으며 오랫동안 요청받았던 기능들을 구현했습니다.

[에러 커스터마이징](https://zod.dev/v4/changelog?id=error-customization)

Zod 4는 에러 커스터마이징 API를 단일 통합된 매개변수로 표준화했습니다. 이전에는 API가 분산되고 일관성이 부족했는데, Zod 4에서 정리되었습니다.