W3Techs에 따르면 WordPress는 전체 웹사이트의 43%를 차지합니다. 점점 더 많은 팀이 PHP 프론트엔드를 완전히 제거하고 WordPress를 콘텐츠 API로 사용하고 있습니다. 다음은 WordPress를 헤드리스 방식으로 운영하는 데 필요한 모든 정보입니다. REST API와 WPGraphQL 중 선택하는 방법부터 Vercel에 ISR을 사용하여 Next.js 프론트엔드를 배포하는 방법까지 모두 다룹니다.
헤드리스 WordPress란? (왜 신경 써야 할까?)
헤드리스 WordPress는 WordPress가 콘텐츠 관리 및 저장을 담당하고, Next.js, Nuxt, Astro 또는 다른 프레임워크로 구축된 별도의 프론트엔드 애플리케이션이 API를 통해 그 콘텐츠를 가져오는 구조입니다. WordPress는 관리자 대시보드, 에디터, 플러그인 생태계, MySQL 데이터베이스를 유지합니다. 하지만 PHP 테마로 페이지를 렌더링하는 대신, WordPress REST API 또는 WPGraphQL을 통해 콘텐츠를 노출하고, 프론트엔드가 프레젠테이션 계층을 완전히 담당합니다.
이렇게 생각해보세요: WordPress는 주방이고, 프론트엔드 프레임워크는 식당입니다. 주방은 음식(콘텐츠)을 준비하지만, 식당이 어떻게 담아낼지, 식당의 인테리어가 어떨지, 손님들이 어떻게 경험할지를 결정합니다.
전통적 아키텍처 vs 헤드리스 아키텍처
전통적인 WordPress에서는 모든 것이 모놀리식입니다. 방문자가 페이지를 요청하면, PHP가 요청을 처리하고, MySQL을 쿼리하며, 테마의 템플릿 파일을 통해 실행한 후 렌더링된 HTML을 반환합니다. 테마가 레이아웃, 스타일링, 라우팅 등 모든 것을 제어합니다.
헤드리스 WordPress에서는 전체 렌더링 계층을 제거합니다. WordPress는 API 뒤에 있으며, 보통 WP Engine이나 Kinsta 같은 관리형 호스팅에서 실행됩니다. 프론트엔드(React, Vue, Svelte 앱)는 API 요청을 하여 콘텐츠를 가져온 다음 원하는 대로 렌더링합니다. 두 시스템은 완전히 다른 서버, 다른 기술 스택, 다른 배포 파이프라인에서 실행될 수 있습니다.
여기서 10명 중 9명의 가이드가 간과하는 미묘한 차이가 있습니다: 분리된(decoupled) WordPress와 헤드리스 WordPress는 정확히 같은 것이 아닙니다. 분리된 WordPress는 특정 페이지(예: 관리자 영역이나 레거시 경로)에 대해 여전히 PHP 렌더링으로 돌아갈 수 있습니다. 완전히 헤드리스라는 것은 WordPress 프론트엔드가 완전히 비활성화되었다는 의미입니다. 즉, API만 사용하고 테마 렌더링이 전혀 없습니다. 이 가이드에서는 완전히 헤드리스한 방식을 다룹니다.
헤드리스로 전환할 때 (그리고 전통적 방식을 유지할 때)
헤드리스로 전환하는 것이 합리적인 경우는 팀에 현대 도구로 작업하고 싶은 프론트엔드 개발자가 있을 때, 여러 채널(웹, 모바일 앱, 디지털 사이니지)에 걸쳐 콘텐츠를 전달해야 할 때, 성능이 타협의 여지가 없을 때입니다. 하지만 모든 사람에게 적합한 것은 아니며, 이에 대해 솔직하면 낭비되는 주간을 절약할 수 있습니다.
헤드리스로 전환하면 좋은 경우...
- 팀이 이미 React/Vue/Svelte를 알고 있습니다. 프론트엔드 개발자들이 하루 종일 JSX를 작성하고 있다면, 그들을 PHP 테마로 강제하는 것은 셰프에게 전자레인지로 요리하라고 하는 것과 같습니다.
- 다중 채널 전달이 필요합니다. 하나의 WordPress 백엔드가 같은 API를 통해 마케팅 사이트, 모바일 앱, 매장 키오스크에 콘텐츠를 제공할 수 있습니다.
- 성능이 필수 요건입니다. CDN 엣지에서 제공되는 정적 페이지는 항상 공유 서버의 PHP 렌더링을 능가합니다.
- 헤드리스 WooCommerce를 운영 중입니다. 복잡한 전자상거래 프론트엔드는 맞춤형 React/Next.js 스토어프론트로부터 엄청난 이점을 얻습니다.
- 현대적인 개발자 경험을 원합니다. Hot module replacement, TypeScript, 컴포넌트 라이브러리, CI/CD 등 전체 프론트엔드 도구 체인을 원합니다.
전통적 방식을 유지하면 좋은 경우...
- 콘텐츠 편집자가 라이브 미리보기와 페이지 빌더가 필요합니다. Gutenberg, Elementor, WPBakery는 전통적인 테마를 가정합니다. 헤드리스로 전환하면 대부분의 시각적 편집 워크플로우가 중단됩니다.
- 솔로 개발자이거나 작은 팀입니다. 헤드리스는 설정 복잡도를 40~60% 증가시킵니다. 블로그를 유지하는 개인이라면 전통적인 테마가 더 간단합니다.
- 프론트엔드 플러그인에 크게 의존합니다. 연락처 양식, SEO 플러그인(Yoast는 서버 측에서 메타 태그를 렌더링), 쿠키 동의 배너 등은 모두 PHP 렌더링을 가정합니다.
- 예산이 빠듯합니다. WordPress와 프론트엔드를 위한 별도의 호스팅이 필요합니다. 이는 한 개가 아닌 두 개의 청구서입니다.
REST API vs WPGraphQL: 데이터 계층 선택하기
WordPress는 헤드리스 설정에서 콘텐츠를 가져오는 두 가지 방법을 제공합니다: 내장 REST API와 WPGraphQL 플러그인입니다. REST API는 WordPress 코어와 함께 제공되며 그대로 작동합니다(플러그인이 필요 없음). WPGraphQL은 플러그인 설치가 필요하지만 필요한 필드만 쿼리할 수 있게 해주어 REST를 괴롭히는 과다 페칭 문제를 제거합니다. 우리의 경험상 WPGraphQL이 대부분의 프로젝트에 승리하지만, REST에는 한 가지 과소평가된 장점이 있습니다: 기본 HTTP 캐싱.
WordPress REST API: 내장 옵션
REST API는 WordPress 버전 4.7(2016년 12월) 이후 모든 WordPress 설치에서 사용 가능합니다. /wp-json/wp/v2/posts에 접속하면 JSON이 반환됩니다. 간단하고 문서가 잘 되어 있으며 설정 없이도 작동합니다.
문제점은? 과다 페칭입니다. 포스트를 요청하면 WordPress는 모든 것을 반환합니다: 렌더링된 콘텐츠, 원본 콘텐츠, 요약, 작성자 ID, 추천 미디어 ID, 카테고리, 태그, 메타 필드, GUID, 댓글 상태, ping 상태, 템플릿 및 아마도 필요하지 않은 약 15개의 다른 필드들. 블로그 목록 페이지에서 제목, slug, 요약만 필요한 경우에도 필요한 것보다 3~5배 더 많은 데이터를 전송하게 됩니다.
_fields 파라미터를 사용하여 반환되는 필드를 제한할 수 있습니다(?_fields=id,title,slug,excerpt), 하지만 임베드된 리소스에는 도움이 되지 않으며, 관련 데이터가 필요하면 여전히 여러 번의 요청을 하게 됩니다.
WPGraphQL: 필요한 것만 쿼리하기
WPGraphQL은 Jason Bahl이 만들고 현재 WP Engine에서 유지보수하는 무료 오픈 소스 플러그인으로, WordPress에 완전한 GraphQL API를 추가합니다. 정확히 원하는 필드를 지정하는 쿼리를 작성하면 정확히 그것만 얻습니다(그 이상도 그 이하도 아닙니다).
나란히 비교한 코드
실제 응답 페이로드가 어떻게 보이는지입니다:
어느 것을 선택해야 할까?
빠르게 무언가를 만들고 있을 때, 팀이 GraphQL을 모를 때, 또는 추가 도구 없이 적극적인 HTTP 캐싱이 필요할 때는 REST를 사용하세요.
복잡한 데이터 요구사항을 가진 프로덕션 프론트엔드를 구축하고 있을 때, 더 작은 페이로드를 원할 때, 또는 팀이 다른 곳에서 이미 GraphQL을 사용하고 있을 때는 WPGraphQL을 사용하세요.
명확한 결론: Next.js를 사용한 진지한 헤드리스 WordPress 프로젝트의 경우, WPGraphQL이 더 나은 선택입니다. 페이로드 절감, GraphiQL IDE를 통한 개발자 경험, 단일 요청 데이터 페칭은 플러그인 의존성의 가치가 있습니다.
WordPress를 헤드리스 CMS로 설정하기
WordPress를 헤드리스 CMS로 설정하는 것은 여섯 가지 단계를 거칩니다: WordPress 설치, 올바른 플러그인 추가, 콘텐츠 모델 구성, 프론트엔드 테마 비활성화, 인증 설정, API 작동 확인. 전체 프로세스는 한 번 해본 적이 있으면 약 30~45분 정도 걸리고, 처음이면 몇 시간 정도 걸립니다.
단계 1: 관리형 호스팅에서 새로운 WordPress 설치로 시작합니다. Kinsta, WP Engine, Cloudways는 모두 WordPress에 최적화된 환경을 제공합니다. 단순히 실험하는 중이라면 LocalWP를 사용한 로컬 설치도 좋습니다.
단계 2: 필수 플러그인을 설치합니다:
단계 3: ACF를 사용하여 콘텐츠 모델을 만듭니다. 프론트엔드 컴포넌트에 매핑되는 필드 그룹을 정의하세요. 포트폴리오 포스트 타입은 projectUrl, techStack(repeater), clientName, projectYear 필드를 가질 수 있습니다.
필수 플러그인
WPGraphQL for ACF는 특별한 주목을 받을 가치가 있습니다. 이 플러그인이 없으면 ACF 필드가 GraphQL 쿼리에 나타나지 않습니다. 설치 후, 다음과 같이 커스텀 필드를 쿼리할 수 있습니다:
WordPress 프론트엔드 비활성화하기
단계 4: 방문자가 WordPress URL에 접속했을 때 깨진 테마를 보지 않기를 원합니다. 테마의 functions.php에 이것을 추가하거나 mu-plugin을 사용하세요:
단계 5: 인증을 위해 Application Passwords를 설정합니다. Users > Your Profile > Application Passwords로 이동하여 비밀번호를 생성하고, 인증된 API 요청(외부 도구에서 콘텐츠 생성/업데이트)에 사용하세요.
API 테스트
...