Next.js WooCommerce 통합 (nextjs-woocommerce)
WPGraphQL, WooGraphQL 및 JWT 인증을 통해 Next.js App Router 애플리케이션을 헤드리스 WooCommerce 백엔드와 아키텍처, 쿼리 및 통합하기 위한 운영 런북 및 체크리스트입니다.
사전 요구 사항 및 문서 참조
- Next.js 14+ 프로젝트가 App Router 및 TypeScript로 초기화되어 있어야 합니다.
- WPGraphQL, WooGraphQL 및 wp-graphql-jwt-authentication 플러그인이 설치된 활성 WooCommerce 백엔드가 있어야 합니다.
- 완전한 API 스키마 및 Next.js 코드 패턴은 nextjs-woocommerce-reference.md를 참조하세요.
- 재사용 가능한 데이터 페칭 클라이언트 구현은 woocommerce-fetcher.ts를 참조하세요.
단계별 구현 체크리스트
flowchart TD
S1["1. 환경 및 클라이언트 설정"] --> S2["2. 공개 제품 카탈로그 (ISR/SSG)"]
S2 --> S3["3. 사용자 인증 (JWT + 쿠키)"]
S3 --> S4["4. 보호된 프로필 및 주문 내역"]
S4 --> S5["5. 장바구니 세션 및 네이티브 체크아웃 브리지"]
1단계: 환경 및 클라이언트 구성
- 환경 변수 구성:
.env.example및.env.development파일에NEXT_PUBLIC_WORDPRESS_API_URL=https://your-store.com/graphql을 추가합니다.- 체크아웃 리디렉션을 위해
NEXT_PUBLIC_WORDPRESS_URL=https://your-store.com을 추가합니다.
- 범용 페처 설정:
- ISR 캐싱 및 인증 헤더를 지원하는 woocommerce-fetcher.ts를 구현합니다.
2단계: 공개 제품 카탈로그 및 분류 체계
- 카테고리 탐색: 헤더 및 카테고리 메뉴를 위해
hideEmpty: true옵션과 함께productCategories를 쿼리합니다. - 제품 그리드 아카이브: 유니온 프래그먼트(
... on SimpleProduct,... on VariableProduct)를 사용하여products를 쿼리합니다.next: { revalidate: 300, tags: ['products'] }를 구성합니다. - 제품 상세 페이지: 모든 제품 슬러그를 쿼리하는
generateStaticParams()와 함께 동적 라우트(app/products/[slug]/page.tsx)를 사전 렌더링합니다.
3단계: JWT 인증 파이프라인
- 로그인 뮤테이션:
login(input: { username, password })를 실행하는 서버 액션을 구현합니다. - 쿠키 저장: 반환된
authToken을 보안HttpOnly쿠키(auth_token)에 저장합니다. - 세션 바인딩: 고객이
sessionToken을 반환하는 경우wc_session쿠키에 저장합니다. - 로그아웃: 사용자 로그아웃 시 인증 쿠키를 삭제합니다.
4단계: 보호된 사용자 데이터 및 주문
- 고객 프로필:
Authorization: Bearer <authToken>헤더와 함께viewer { id name email }을 쿼리합니다. - 주문 내역:
cache: 'no-store'와 함께customer { orders { nodes { id orderNumber total status } } }를 쿼리합니다.
5단계: 장바구니 관리 및 체크아웃 전략
- 장바구니 상태:
addToCart뮤테이션에서 반환된woocommerce-session헤더를 캡처하고 유지합니다. - 네이티브 체크아웃 브리지:
- 사용자를
https://your-store.com/checkout으로 리디렉션하여 맞춤형 게이트웨이 재작성 없이 네이티브 WooCommerce 결제 게이트웨이(ZarinPal, Mellat, Stripe), 지역 물류 및 규정 준수 인증을 활용합니다.
- 사용자를
에지 케이스 및 알려진 함정
- 정적 vs 동적 최적화 저하: 루트 레이아웃 또는 제품 페이지에서 쿠키를 읽으면 Next.js가 전체 SSR 동적 모드로 전환됩니다. 인증 쿠키는 서버 액션, 라우트 핸들러 또는 분리된 계정 대시보드 서브 트리(
app/account/...) 내에서만 읽으십시오. - 다형성 프래그먼트:
products { nodes { price } }와 같은 직접 쿼리는 WooCommerce GraphQL에서 유효성 검사에 실패합니다. 가격 및 변형은 항상... on SimpleProduct및... on VariableProduct로 래핑하십시오. - 세션 손실: 장바구니에 항목을 추가할 때
woocommerce-session헤더를 다시 보내지 않으면 모든 뮤테이션에서 새 빈 장바구니가 생성됩니다. - GraphQL 엔드포인트의 CORS: WordPress가 Next.js 도메인에 대해
Access-Control-Allow-Origin및Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session헤더를 보내는지 확인하십시오.
검증 및 사전 점검 테스트
-
pnpm build가 제품 페이지의 정적 생성과 함께 성공합니다. - 로그인 양식이
auth_token을 발행하고 대시보드로 리디렉션되는지 테스트합니다. - 계정 페이지가 유효한 토큰으로 고객 세부 정보 및 주문 목록을 렌더링합니다.
- 장바구니 추가가 여러 클라이언트 요청에서 장바구니 항목 수를 업데이트합니다.