라우팅

사용자가 스토어프런트 도메인에서 요청을 실행하면 pwa-kit-react-sdk/ssr/server/react-rendering에 정의된 render라는 Express.js 핸들러에 의해 처리됩니다. 이 핸들러는 응답에 렌더링할 구성 요소를 선택합니다. 이 유형의 구성요소를 경로라고 합니다. 렌더링에 사용할 수 있는 경로는 app/routes.jsx의 routes라는 오브젝트 배열에 정의됩니다.

경로 배열은 React Router에서 정의한 경로 구성 형태를 따릅니다. routes 배열의 각 오브젝트는 다음 속성을 가질 수 있습니다.

키	유형	설명	참조 문서
path	Express 스타일 문자열, 문자열 배열 또는 정규식	가능한 일치 항목의 들어오는 요청 경로와 비교되는 경로	React Router API → Route component → path
component	함수(`routes.jsx`로 가져옴)	경로가 요청과 일치하는 경우 렌더링할 구성요소	React Router API → Route component → component
exact	부울	경로가 정확히 일치해야 하는지 여부 결정	React Router API → Route component → exact

새로 생성된 프로젝트는 이미 routes 배열에 홈, PLP, PDP 등 여러 표준 이커머스 페이지의 오브젝트가 포함되어 있습니다.

그렇다면 React 앱은 특정 요청에 대해 렌더링할 올바른 구성요소를 어떻게 선택할까요? React Router 라이브러리를 사용하여 요청된 경로와 일치하는 path 문자열을 찾을 때까지 routes 배열의 경로 구성 오브젝트를 순차적으로 검색합니다.

React Router는 path 문자열을 구성하기 위한 다양한 옵션을 제공합니다. 동일한 구성요소에 2개 이상의 경로를 지정하고, 정규식을 사용하여 특정 패턴을 따르는 경로를 매칭할 수 있습니다.

또한 React Router는 Retail React App 전체에서 탐색을 구현하는 데 사용됩니다. 예를 들어 모든 하이퍼링크는 React Router의 Link 구성요소를 사용합니다. React Router는 브라우저 기록, 쿼리 매개변수 등에 액세스할 수 있는 다른 구성요소를 제공합니다.

React Router 사용에 대한 자세한 내용은 공식 설명서를 참조하십시오. (다른 버전에서는 다른 패턴 일치 시스템을 사용하므로 버전 5의 설명서를 준수하십시오.)

routes 배열에 지정된 각 구성요소는 PWA Kit React SDK의 고차 구성요소인 routeComponent 함수에 의해 자동으로 향상됩니다. routeComponent를 구성하는 데 사용되는 기본 클래스는 스토어프런트 개발자가 커스터마이즈할 수 있는 getProps와 shouldGetProps라는 두 가지 중요한 메서드를 비롯하여 몇 가지 정적 메서드를 정의합니다.

getProps 메서드는 API 요청에서 가져오는 데이터를 props 오브젝트를 통해 routeComponent에 제공할 때 사용합니다.

routeComponent가 routes 배열의 구성요소를 향상시키면 getProps라는 이름의 함수가 구성요소 속성 내에서 조회됩니다. 여기서 함수를 정의하면 향상된 구성요소의 메서드로 표시됩니다. routes 배열의 모든 구성요소에 대해 함수를 정의할 필요는 없으며, 렌더링 전에 데이터를 가져오는 구성요소만 정의할 수 있습니다.

정의하는 getProps 함수는 promise를 반환해야 합니다. promise가 확인되면 확인된 값은 구성요소가 렌더링될 때 props 오브젝트를 통해 향상된 구성요소에 전달됩니다.

routes 배열에서 구성요소가 렌더링되면 구성요소의 getProps 메서드가 단일 JavaScript 오브젝트와 함께 제공됩니다. 이 오브젝트에는 렌더링 컨텍스트에 따라 다음과 같은 속성이 있습니다.

키	유형	설명	가용성	추가 정보
`params`	오브젝트	Express 스타일 경로 문자열의 명명된 경로 매개변수에 해당하는 오브젝트 속성을 포함합니다. 예: `/user/:name`이라는 경로가 있는 경우 요청 경로의 `:name` 값은 params.name으로 제공됩니다. 기본값: `{}`.	클라이언트 측 및 서버 측 모두	Express API → Request → req.params
`req`	오브젝트	Express로 향상된 Node의 요청 오브젝트 버전입니다. HTTP 요청을 나타내며 쿼리 문자열, 매개변수, 본문, HTTP 헤더 등에 대한 속성을 포함합니다.	서버 측 전용	Express API → Request
`res`	오브젝트	Express 앱이 HTTP 요청을 수신할 경우 보내는 HTTP 응답을 나타냅니다.	서버 측 전용	Express API → Response
`location`	문자열	요청의 URL입니다.	클라이언트 측 및 서버 측 모두	Express API의 일부가 아님

getProps 함수의 오류를 처리하는 방법은 두 가지가 있습니다.

첫 번째 옵션은 pwa-kit-react-sdk/ssr/universal/errors에서 가져올 수 있는 HTTPError 오브젝트를 throw하는 것입니다. HTTPError를 throw하면 전용 Error 구성요소가 렌더링됩니다.

두 번째 옵션은 맞춤형 오류 처리 로직에 사용할 수 있도록 속성을 사용하여 렌더링된 구성요소에 오류를 알리는 것입니다.

다음은 두 가지 오류 처리 방법을 모두 사용하는 예입니다.

getProps에서 반환된 오브젝트는 직렬화되어 페이지 소스의 __PRELOADED_STATE__라는 오브젝트를 통해 렌더링된 HTML에 임베딩됩니다.

렌더링된 HTML의 크기를 줄이려면 getProps에서 반환할 데이터를 선택해야 합니다. 예를 들어 가능하면 API 요청에서 전체 응답을 반환하지 않도록 합니다.

브라우저에서 서버 측에 렌더링된 페이지의 버전을 미리 보려면 URL에 ?__server_only를 추가합니다. 이 쿼리 매개변수는 hydration 프로세스를 중지하므로, 브라우저가 렌더링을 인계하지 않고 서버 측 렌더링 후 페이지를 변경하지 않습니다. __PRELOADED_STATE__ 오브젝트의 깔끔한 인쇄 버전을 보려면 쿼리 문자열에 ?__server_only&__pretty_print를 추가합니다.

클라이언트 측 렌더링 중에 사용자가 뒤쪽 페이지로 이동하면 페이지가 즉시 렌더링됩니다. getProps가 데이터를 가져오는 동안 렌더링이 발생할 수 있으므로, 정의되지 않은 속성을 처리하기 위해 항상 구성요소에 조건부 코드를 작성해야 합니다. 또한 속성이 정의되지 않은 상태에서 자리 표시자 구성요소(예: Chakra UI의 Skeleton)를 렌더링해야 합니다.

클라이언트 측에서는 getProps가 확인되기 전후에 구성요소의 render 메서드가 호출됩니다. 구성요소에 전달된 isLoading 속성을 사용하여 로딩 화면을 렌더링할지 여부를 결정합니다.

getProps에서 여러 건의 HTTP 요청을 하는 경우 가급적 병렬로 합니다. 병렬로 할 수 없는 경우 클라이언트 측 렌더링으로 옮기는 것을 고려할 수 있습니다.

클라이언트 측에서만 데이터를 가져오려는 경우 구성요소에 getProps 대신 React 후크를 사용합니다.

모든 경로에 대해 동일한 코드를 실행하려는 경우 특수 구성요소 중 하나인 App 구성요소에 속하는 getProps 함수를 정의할 수 있습니다. 특수 구성요소는 여러 경로에 공유되는 기능을 추가하는 데 사용됩니다. App 구성요소 및 기타 특수 구성요소에 대한 자세한 내용은 특수 구성요소 가이드를 참조하십시오.

shouldGetProps 메서드는 getProps 메서드를 호출할 시점을 제어합니다. 서버 측 렌더링 중에 shouldGetProps는 한 번만 호출됩니다. 클라이언트 측 렌더링 중에 React 라이프사이클 메서드 componentDidUpdate가 호출될 때마다 호출됩니다.

기본적으로, getProps는 location.pathname의 값이 변경될 때마다 getProps를 호출합니다. shouldGetProps라는 자체 함수를 구성요소의 속성으로 정의하여 routes 배열에 있는 각 구성요소의 기본 동작을 재정의할 수 있습니다. shouldGetProps를 맞춤화하여 요청을 검사하고 특정 요청에 대해서만 getProps를 호출할 수 있습니다.

소스 코드를 검토하여 라우팅에 대한 이해도를 높이십시오. 다음은 Retail React App에서 살펴볼 몇 가지 주요 파일입니다.

app/routes.jsx: 명명된 경로 매개변수를 포함하여, 경로 매칭을 위한 Express 스타일 구문을 보여줍니다.
app/pages/product-detail/index.jsx: 이 PDP용 샘플 구성요소에는 getProps와 shouldGetProps에 적용되는 맞춤형 함수가 모두 포함되어 있습니다.
app/components/_app_config/index.jsx: 다양한 구성 코드와 앱 전체에 적용되는 getProps 함수가 포함되어 있습니다.

PWA Kit 설명서에서 Retail React App의 아키텍처 가이드를 놓치지 마십시오.