# WordPress 헤드리스와 Next.js 조합 아키텍처 ## 개요 이 문서는 WordPress를 헤드리스 CMS로 활용하고 Next.js로 프론트엔드를 구축하는 아키텍처에 대해 설명합니다. 이 접근법은 WordPress의 강력한 콘텐츠 관리 기능과 Next.js의 현대적인 프론트엔드 개발 경험을 결합하여, 기존 WordPress 사이트를 점진적으로 현대화할 수 있는 방법을 제공합니다. ## 아키텍처 다이어그램 ``` ┌─────────────────────────────────────────────────────────────┐ │ Client (Browser/Mobile) │ └───────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────▼─────────────────────────────────┐ │ Next.js Frontend │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Pages │ │ UI │ │ API │ │ State │ │ │ │ │ │Components│ │ Routes │ │ Management│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ └───────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────▼─────────────────────────────────┐ │ WordPress REST API / GraphQL │ └───────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────▼─────────────────────────────────┐ │ WordPress Backend │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Posts │ │ Pages │ │ Custom │ │ Media │ │ │ │ │ │ │ │Post Types│ │ Library │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Plugins │ │ Users │ │ Comments│ │ Settings│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 헤드리스 WordPress + Next.js의 장점 ### WordPress의 강점 활용 - **친숙한 관리자 경험**: 콘텐츠 편집자들에게 익숙한 편집 환경 제공 - **풍부한 플러그인 생태계**: 수천 개의 플러그인을 통한 기능 확장 - **성숙한 사용자 관리**: 역할 및 권한 관리 시스템 - **다양한 콘텐츠 타입**: 포스트, 페이지, 사용자 정의 포스트 타입, 분류 등 - **기존 콘텐츠 보존**: 기존 WordPress 사이트의 콘텐츠를 그대로 활용 ### Next.js의 강점 활용 - **우수한 성능**: 서버 사이드 렌더링(SSR) 및 정적 사이트 생성(SSG) - **SEO 최적화**: 검색 엔진 친화적인 페이지 제공 - **개발자 경험**: React 기반의 현대적인 개발 환경 - **API 라우트**: 서버리스 함수를 통한 백엔드 기능 구현 - **증분 정적 재생성(ISR)**: 동적 콘텐츠의 정적 이점 활용 ## 구현 방법 ### 1. WordPress 설정 - **REST API 활성화**: WordPress의 내장 REST API 활용 - **필수 플러그인 설치**: - **JWT Authentication**: 안전한 API 인증 - **ACF to REST API**: Advanced Custom Fields 데이터를 API에 노출 - **WPGraphQL**: GraphQL 지원 (선택사항) - **CORS 설정**: Next.js 애플리케이션의 API 접근 허용 - **커스텀 엔드포인트 생성**: 필요한 데이터 형식에 맞는 API 엔드포인트 추가 ### 2. Next.js 프로젝트 구성 - **프로젝트 초기화**: ```bash npx create-next-app my-headless-wp cd my-headless-wp ``` - **필요 패키지 설치**: ```bash npm install swr axios @wordpress/block-serialization-default-parser ``` - **환경 변수 설정**: ``` WORDPRESS_API_URL=https://your-wordpress-site.com/wp-json ``` ### 3. 데이터 페칭 구현 **WordPress API 클라이언트 설정**: ```javascript // lib/api.js const API_URL = process.env.WORDPRESS_API_URL; async function fetchAPI(endpoint, params = {}) { const res = await fetch(`${API_URL}${endpoint}`, params); if (!res.ok) { throw new Error(`API error: ${res.status} ${res.statusText}`); } return await res.json(); } export async function getAllPosts() { return fetchAPI('/wp/v2/posts?_embed&per_page=100'); } export async function getPostBySlug(slug) { const posts = await fetchAPI( `/wp/v2/posts?slug=${slug}&_embed` ); return posts[0]; } // 기타 필요한 API 함수들... ``` ### 4. 페이지 생성 **블로그 포스트 페이지 예시**: ```jsx // pages/posts/[slug].js import { useRouter } from 'next/router'; import { getPostBySlug, getAllPosts } from '../../lib/api'; import Head from 'next/head'; import PostBody from '../../components/post-body'; export default function Post({ post }) { const router = useRouter(); if (router.isFallback) { return
Loading...
; } return (
{post.title.rendered}

); } export async function getStaticProps({ params }) { const post = await getPostBySlug(params.slug); return { props: { post }, revalidate: 60 // ISR: 60초마다 재생성 }; } export async function getStaticPaths() { const posts = await getAllPosts(); return { paths: posts.map((post) => ({ params: { slug: post.slug }, })), fallback: 'blocking', }; } ``` ## 콘텐츠 렌더링 전략 ### 1. WordPress 블록(Gutenberg) 처리 방법 WordPress 5.0 이후 도입된 Gutenberg 블록 에디터의 콘텐츠를 Next.js에서 렌더링하는 세 가지 접근법: #### a) HTML 직접 렌더링 ```jsx
``` - **장점**: 구현 간단 - **단점**: React 컴포넌트의 이점 활용 불가 #### b) HTML 파싱 및 React 컴포넌트로 변환 ```jsx import parse from 'html-react-parser'; const PostContent = ({ content }) => { return
{parse(content)}
; }; ``` - **장점**: 일부 React 이점 활용 - **단점**: 복잡한 인터랙션 구현 어려움 #### c) 블록 데이터 파싱 및 커스텀 컴포넌트 매핑 ```jsx import { parse } from '@wordpress/block-serialization-default-parser'; const BlockRenderer = ({ blocks }) => { return blocks.map((block, index) => { switch (block.blockName) { case 'core/paragraph': return

{block.attrs.content}

; case 'core/heading': return

{block.attrs.content}

; // 다른 블록 타입들... default: return null; } }); }; const PostContent = ({ rawContent }) => { const blocks = parse(rawContent); return ; }; ``` - **장점**: 완벽한 맞춤형 경험, 최적의 SEO - **단점**: 구현 복잡성, 모든 블록 타입 지원 필요 ### 2. 이미지 최적화 Next.js의 Image 컴포넌트를 활용하여 WordPress 미디어 최적화: ```jsx import Image from 'next/image'; const PostImage = ({ mediaItem }) => { return ( {mediaItem.alt_text} ); }; ``` ## 인증 및 미리보기 기능 ### 1. 인증 구현 JWT 인증을 통한 보호된 콘텐츠 접근: ```javascript // lib/auth.js export async function login(username, password) { const response = await fetch(`${process.env.WORDPRESS_API_URL}/jwt-auth/v1/token`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username, password }) }); const data = await response.json(); if (response.ok) { // 토큰 저장 localStorage.setItem('wpToken', data.token); return true; } return false; } export function getAuthHeader() { const token = typeof window !== 'undefined' ? localStorage.getItem('wpToken') : null; return token ? { 'Authorization': `Bearer ${token}` } : {}; } ``` ### 2. 드래프트 및 미리보기 비공개 콘텐츠 미리보기 구현: ```jsx // pages/api/preview.js export default async function preview(req, res) { const { secret, slug, id } = req.query; // 시크릿 검증 if (secret !== process.env.WORDPRESS_PREVIEW_SECRET || !slug) { return res.status(401).json({ message: '유효하지 않은 토큰' }); } // 미리보기 모드 활성화 res.setPreviewData({}); // 해당 포스트로 리디렉션 res.redirect(`/posts/${slug}`); } ``` ## SEO 최적화 ### 1. 메타데이터 처리 ```jsx import Head from 'next/head'; const SEO = ({ title, description, ogImage, canonicalUrl }) => { return ( {title} ); }; ``` ### 2. Yoast SEO 통합 WordPress의 Yoast SEO 메타데이터를 Next.js에서 활용: ```javascript export async function getPostSEOData(slug) { const post = await getPostBySlug(slug); const yoastData = post.yoast_head_json || {}; return { title: yoastData.title || post.title.rendered, description: yoastData.description || post.excerpt.rendered, ogImage: yoastData.og_image?.[0]?.url || post._embedded?.['wp:featuredmedia']?.[0]?.source_url, canonical: yoastData.canonical || `https://your-site.com/posts/${slug}` }; } ``` ## 배포 및 캐싱 전략 ### 1. 배포 옵션 - **Vercel/Netlify**: Next.js 애플리케이션 배포에 가장 적합 - **Self-hosted**: 커스텀 서버 설정이 필요한 경우 ### 2. 캐싱 전략 - **ISR(Incremental Static Regeneration)**: 대부분의 페이지에 적합 ```javascript export async function getStaticProps() { // 데이터 가져오기 return { props: { data }, revalidate: 60 // 60초마다 재생성 }; } ``` - **주기적인 완전 재빌드**: 콘텐츠 업데이트가 빈번하지 않은 경우 - Vercel/Netlify webhook을 WordPress에 연결 - 콘텐츠 업데이트 시 빌드 트리거 ### 3. WordPress 캐싱 - Redis 캐시 활용 - WordPress 캐싱 플러그인(WP Super Cache, W3 Total Cache) 설치 ## 마이그레이션 전략 ### 1. 점진적 마이그레이션 접근법 1. **분석 및 계획**: - 가장 중요한 페이지 식별 - URL 구조 및 리디렉션 계획 수립 2. **핵심 페이지부터 구현**: - 홈페이지, 주요 랜딩 페이지 - 인기 블로그 포스트 3. **프록시 설정**: - Next.js로 마이그레이션된 경로는 새 애플리케이션으로 - 나머지 경로는 기존 WordPress 사이트로 리디렉션 4. **점진적 롤아웃**: - 트래픽이 적은 페이지로 시작 - 모니터링 및 이슈 수정 - 성공적으로 검증된 후 주요 페이지로 확장 ### 2. URL 구조 및 리디렉션 기존 WordPress URL 구조를 유지하거나 301 리디렉션 설정: ```javascript // next.config.js module.exports = { async redirects() { return [ { source: '/blog/:year/:month/:slug', destination: '/posts/:slug', permanent: true, }, // 다른 리디렉션 규칙들... ]; }, }; ``` ## 성능 최적화 ### 1. 코어 웹 바이탈(Core Web Vitals) 최적화 - **LCP(Largest Contentful Paint)**: 이미지 최적화, 중요 CSS 인라인화 - **FID(First Input Delay)**: 자바스크립트 청크 분할, 중요하지 않은 JS 지연 로드 - **CLS(Cumulative Layout Shift)**: 이미지 크기 명시, 폰트 최적화 ### 2. 이미지 및 폰트 최적화 - Next.js Image 컴포넌트 활용 - 폰트 preload 및 display: swap 적용 ### 3. API 응답 최적화 - WordPress REST API 응답에서 필요한 필드만 요청 - API 응답 캐싱 구현 ## 유지보수 및 워크플로우 ### 1. 콘텐츠 편집 워크플로우 - WordPress 관리자 패널에서 콘텐츠 생성/편집 - 미리보기 기능을 통해 Next.js에서 변경사항 확인 - 게시 시 Next.js 페이지 자동 업데이트(ISR 또는 webhook 활용) ### 2. 개발자 워크플로우 - WordPress 플러그인 및 테마 업데이트 관리 - Next.js 애플리케이션 코드 업데이트 - API 변경사항 모니터링 및 대응 ### 3. 모니터링 및 분석 - WordPress 및 Next.js 애플리케이션 모니터링 - API 응답 시간 및 성능 추적 - 사용자 분석 데이터 수집 ## 주의사항 및 한계 - **API 속도 제한**: WordPress REST API의 속도 제한 고려 - **플러그인 호환성**: 일부 WordPress 플러그인은 헤드리스 환경과 완벽하게 호환되지 않음 - **실시간 기능**: 댓글, 양식 제출과 같은 양방향 기능 구현 복잡성 ## 결론 WordPress를 헤드리스 CMS로 활용하고 Next.js로 프론트엔드를 구현하는 접근법은 기존 WordPress 사이트의 모든 콘텐츠 관리 기능을 유지하면서 현대적인 프론트엔드 개발 경험을 제공합니다. 이 아키텍처는 WordPress 기반 사이트를 점진적으로 현대화하고, 더 나은 성능과 사용자 경험을 제공하는 효과적인 전략입니다. 특히 개발 리소스가 제한적이거나, 콘텐츠 편집자들에게 익숙한 환경을 유지해야 하는 경우, 또는 대규모 콘텐츠 마이그레이션의 위험을 줄이고자 할 때 이상적인 선택이 될 수 있습니다.