Payload는 오픈소스 TypeScript 네이티브 헤드리스 CMS로, Next.js 앱 옆에 있는 것이 아니라 같은 /app 폴더에 직접 포함됩니다. 좌석당 비용을 부과하거나 독점 API로 콘텐츠를 잠그는 호스팅된 CMS 플랫폼에 실망한 경험이 있다면, Payload는 진지하게 살펴볼 가치가 있습니다.

하지만 2026년에는 반전이 일어났습니다. Figma가 Payload를 인수했고, Payload Cloud는 신규 가입을 중단했으며, 개발자들은 갑자기 스스로 호스팅을 관리해야 하게 되었습니다. 이 가이드는 초기 설치부터 프로덕션 배포까지 모든 것을 다루며, 현재 Payload 3 코드 예제와 Payload의 강점과 약점에 대한 솔직한 평가를 포함합니다.

Payload CMS란? (개발자가 사랑하는 이유)

Payload는 오픈소스 TypeScript 네이티브 헤드리스 CMS이자 애플리케이션 프레임워크로, Next.js 앱 내부에서 실행됩니다. 호스팅된 CMS 플랫폼과 달리, Payload는 코드 우선 설정, 세 가지 내장 API(REST, GraphQL, Local), 그리고 완전히 커스터마이징 가능한 관리 패널을 모두 단일 코드베이스에서 제공합니다. 공식 Payload 문서에 따르면, 이는 "현대적인 백엔드를 구축하는 최고의 방법"으로 설계되었습니다.

이 프로젝트는 2021년 Node.js/Express CMS로 시작했습니다. Payload 2는 2023년 개선된 TypeScript 지원과 함께 출시되었습니다. 그런 다음 Payload 3가 게임을 완전히 바꿨습니다. CMS가 Next.js 애플리케이션 내부로 이동했습니다. 별도의 서버 프로세스가 없습니다. 별도의 배포가 없습니다. 당신의 CMS와 프론트엔드는 같은 Next.js 런타임, 같은 라우트, 같은 빌드 파이프라인을 공유합니다.

이는 Sanity, Strapi, 또는 Contentful이 제공하는 것과는 진정으로 다른 아키텍처입니다. 그리고 그것이 당신이 어떻게 구축하고, 배포하고, 콘텐츠 계층을 생각하는지에 대한 실질적인 결과가 있습니다.

코드 우선 철학

대부분의 CMS 플랫폼은 콘텐츠 모델을 정의하기 위한 GUI를 제공합니다. "필드 추가"를 클릭하고, "텍스트"를 선택하고, "제목"이라고 이름을 지으세요. Payload는 이를 뒤집습니다. 당신은 TypeScript 파일에서 모든 것을 정의합니다. 당신의 스키마는 코드입니다. 그것은 버전 제어에 있습니다. 당신은 풀 리퀘스트에서 이를 검토합니다.

이는 환경 간 스키마 드리프트가 없다는 것을 의미하며, "누군가 스테이징에서 콘텐츠 모델을 변경했는데 아무도 무엇이 일어났는지 모른다"는 놀라운 일이 없습니다. 콘텐츠 모델이 클라우드 대시보드에 있는 팀에서 일한 경험이 있다면, 이것이 왜 중요한지 정확히 알 것입니다.

Payload 3 아키텍처 - Next.js 네이티브

Payload 3는 Next.js 앱 옆에 실행되지 않습니다. 그것은 내부에 실행됩니다. 관리 패널은 /app/(payload)/admin에 있고, API 라우트는 /app/(payload)/api에 있으며, 프론트엔드 페이지는 같은 프로젝트에 공존합니다. 프로덕션에서 Next.js를 사용해본 적이 있다면, 편안함을 느낄 것입니다.

Payload를 차별화하는 주요 기능

Payload의 두드러진 기능에는 콘텐츠 모델링을 위한 Collections, 삼중 API 계층(REST, GraphQL, Local), 필드 수준 세분성을 가진 역할 기반 접근 제어, 내장 인증, Lexical 리치 텍스트 편집기, 시각적 편집을 위한 라이브 미리보기가 포함됩니다. 이러한 각각이 실제로 당신의 코드베이스에 대해 무엇을 의미하는지 살펴봅시다.

Collections, Globals & Fields

Collections는 Payload의 핵심 콘텐츠 모델링 기본 단위입니다. 이들을 데이터베이스 테이블처럼 생각하되, TypeScript에서 완전히 정의됩니다. 각 Collection은 자체 REST 및 GraphQL 엔드포인트, 자체 관리 패널 보기, 그리고 자체 접근 제어 규칙을 가지며, 모두 단일 설정 파일에서 생성됩니다.

Globals는 유사하게 작동하지만 싱글톤 데이터의 경우입니다 - 사이트 설정, 네비게이션 설정, 푸터 콘텐츠. 하나의 인스턴스, 콜렉션 목록 보기 없음, 단지 하나의 편집 가능한 문서입니다.

삼중 API 계층 (REST, GraphQL, Local)

이것은 Payload가 다른 모든 오픈소스 CMS보다 진정으로 뛰어난 부분입니다. 당신은 콘텐츠를 쿼리하는 세 가지 방법을 얻으며, 각각은 다른 컨텍스트에 최적화되어 있습니다:

  • Local API: HTTP 오버헤드가 없는 서버 측 쿼리입니다. Next.js 서버 컴포넌트에서 직접 CMS를 호출합니다. 네트워크 왕복 없음, 직렬화 비용 없음. 우리의 테스트에서, Local API는 같은 서버의 REST 호출과 비교하여 페이지 로드 시간을 약 40ms 단축했습니다.

  • REST API: 외부 클라이언트, 모바일 앱, 또는 제3자 통합을 위한 자동 생성 엔드포인트입니다.

  • GraphQL API: 데이터 요청을 정확히 형성해야 하는 프론트엔드를 위한 유연한 쿼리입니다.

Next.js 서버 컴포넌트에서의 Local API 호출 예시입니다:

fetch 호출이 없습니다. API URL이 없습니다. 인증 토큰이 없습니다. 당신은 서버 컴포넌트에서 직접 데이터베이스를 쿼리하고 있으며, TypeScript는 응답에 대한 완전한 타입 안전성을 제공합니다. 이것은 이기기 어렵습니다.

접근 제어 & 인증

Payload의 접근 제어 시스템은 함수 기반입니다. 대시보드에서 권한을 구성하는 대신, true 또는 false를 반환하는 TypeScript 함수를 작성합니다. 필드 수준, 콜렉션 수준, 또는 작업 수준 - 당신이 세분성을 결정합니다.

인증은 내장되어 있습니다: JWT 토큰, 새로고침 토큰, 비밀번호 찾기 흐름, 이메일 확인. Clerk나 NextAuth가 필요하지 않습니다. 많은 프로젝트의 경우, Payload의 인증으로 충분합니다.

Lexical 리치 텍스트 편집기

Payload는 Lexical을 사용합니다. Meta의 리치 텍스트 프레임워크(Draft.js의 뒤를 이은 같은 팀이지만 더 나음). 당신은 커스텀 블록, 인라인 요소, 그리고 슬래시 명령어를 추가할 수 있습니다. 편집기는 구조화된 JSON 형식으로 직렬화되며, 이를 HTML이나 React 컴포넌트로 변환할 수 있습니다.

이것이 중요한 이유는 대부분의 CMS 리치 텍스트 편집기가 너무 기본적이거나(평문 텍스트 영역) 너무 불명확하기(예측 불가능한 HTML을 생성하는 WYSIWYG) 때문입니다. Lexical은 당신이 완전히 제어할 수 있는 구조화되고 예측 가능한 출력을 제공합니다.

라이브 미리보기 & 시각적 편집

Payload 3는 라이브 미리보기를 포함하며, 편집자들은 관리 패널과 나란히 실제 프론트엔드에 반영되는 콘텐츠 변경 사항을 실시간으로 볼 수 있습니다. 이는 시각적 편집이 전혀 없는 Strapi와 비교하면 상당한 격차를 채웁니다.

Sanity Studio의 실시간 협업 기능만큼 광택이 나지는 않습니다 - Sanity의 시각적 편집은 정말로 동급 최고입니다. 하지만 Sanity의 좌석당 가격을 지불하지 않고 "충분히 좋은" 시각적 미리보기가 필요한 팀의 경우, Payload의 구현으로 충분합니다.

버전 관리, 초안 & 자동 저장

Payload는 내장된 초안 관리, 버전 기록, 그리고 자동 저장을 포함합니다 - 상위 랭크의 Payload 가이드 중 전혀 언급되지 않은 기능입니다. 당신은 컬렉션별로 버전 관리를 활성화할 수 있으며(우리는 위의 Posts 예제에서 versions: { drafts: true }로 했습니다), 최대 버전 수를 설정하고, 관리 UI에서 개정판을 비교할 수 있습니다.

편집팀의 경우, 이는 "실수로 초안을 발행했습니다"라는 재앙이 더 이상 일어나지 않는다는 것을 의미합니다. 개발자의 경우, 이는 별도의 버전 관리 시스템을 추가로 구축할 필요가 없다는 것을 의미합니다.

Payload CMS 시작하기

새로운 Payload 프로젝트를 시작하려면, npx create-payload-app@latest를 실행하고, 템플릿을 선택한 후(웹사이트 또는 빈 템플릿), 데이터베이스 어댑터를 선택합니다(PostgreSQL, MongoDB, 또는 SQLite). 2분 이내에 localhost:3000/admin에서 작동하는 관리 패널을 가지게 될 것입니다. 공식 설치 가이드는 엣지 케이스를 다룹니다.

설치

Node.js 18+ 그리고 패키지 매니저만 필요합니다. 이게 전부입니다.

웹사이트 템플릿은 대부분의 프로젝트에 가장 좋은 시작점입니다 - 작동하는 블로그, 페이지 컬렉션, 미디어 업로드, 그리고 프론트엔드가 포함되어 있습니다. 빈 템플릿은 처음부터 구축하려는 경우입니다.

프로젝트 구조

설치 후, 당신의 프로젝트는 Payload가 섞여 있는 표준 Next.js 앱처럼 보입니다:

payload.config.ts 파일은 모든 것의 중심입니다:

첫 번째 Collection

개발 서버가 실행 중이면, /collections에 파일을 추가하여 새로운 컬렉션을 생성합니다. Payload는 설정에서 관리 UI, API 엔드포인트, 그리고 TypeScript 타입을 자동 생성합니다. 간단한 Pages 컬렉션의 예입니다:

당신의 payload.config.ts 컬렉션 배열에 추가하고, 개발 서버를 재시작하면, 시각적 관리 인터페이스가 있는 완전히 기능적인 페이지 빌더를 가지게 됩니다. 플러그인 없음, 마켓플레이스 다운로드 없음.

데이터베이스 옵션 - Postgres, MongoDB & SQLite

...

출처 바로가기