v3로 업그레이드

v3부터는 npm 종속 구성요소로 추가하고 프로젝트에서 템플릿 확장성을 활성화하여 @salesforce/retail-react-app 업데이트를 사용할 수 있습니다.

이 가이드에서는 PWA Kit 프로젝트를 v2.7.x에서 v3.0.0으로 업데이트하는 방법을 다룹니다.

PWA Kit v3에는 다음과 같은 새로운 기능이 많이 추가되었습니다.

🔨 템플릿 확장성: 프로젝트의 코드 설치 공간을 크게 줄이고 개발 작업, 소유 비용 및 향후 업그레이드 문제를 줄일 수 있습니다. 자세한 내용은 템플릿 확장성 가이드를 참조하십시오.

🪝 @salesforce/commerce-sdk-react "후크" 통합: 프로젝트의 구현에서 API 호출을 분리하고, API 호출을 npm 라이브러리 종속 구성요소로서 업그레이드할 수 있도록 하며, TanStack 쿼리를 통해 여러 가지 유용한 기능(상태 관리 등)을 제공합니다. 시작하려면 Commerce SDK React 문서를 참조하십시오.

⚛️ React 18, Node 16/18, Chakra 2 등에 대한 지원을 포함한 주요 공급업체 라이브러리 업데이트

v2.7.x에서 v3.x로 마이그레이션할 때 가장 먼저 결정해야 하는 사항 중 하나는 템플릿 확장성을 활용할지 여부입니다. 이 기능을 활용하려면 @salesforcef/retail-react-app(또는 다른 확장 가능 앱)에서 하나 이상의 파일을 가져와야 합니다. 기본 템플릿에서 상속할 파일 수를 선택할 수 있지만, 하나 이상의 파일을 가져오도록 커밋해야 합니다.

여기서는 npx pwa-kit-create-app@2.x를 통해 생성한 원래 프로젝트에서 수정한 파일의 수를 고려합니다. 일부 고객의 경우 많은 수(약 수백 개)의 파일을 보유하고 있지만, 이 경우에도 상당수의 파일을 수정하지 않을 수 있습니다. 수정되지 않은 파일은 @salesforce/retail-react-app에서 가져오기에 적합하지만, 이 프로세스를 신중하고 점진적으로 수행하는 것이 좋습니다. @salesforce/retail-react-app의 파일은 유사한 경우가 많지만 PWA Kit Retail React App v2.x의 이전 상태에서 변경되었습니다. 특히 @salesforce/commerce-sdk-react 통합(마이그레이션에 대해서는 나중에 자세히 설명)으로 인해 파일 구조뿐만 아니라 가져오기 측면에서도 많은 파일이 변경되어 앱에서 commerce-api 디렉터리 전체를 제거하는 것 자체가 중요한 변화의 시작점이 되었습니다.

v3.0.0을 기준으로, PWA Kit는 withReactQuery라는 완전히 다른 가져오기 전략을 사용합니다. 이 전략은 react-query 라이브러리를 활용하고 SSR 렌더링 전달 시에 쿼리를 활성화합니다. @salesforce/retail-react-app은 react-query에 의해 구동되는 @salesforce/commerce-sdk-react를 사용합니다.

서버 측에서 후크가 작동하려면 AppConfig 구성요소를 새로운 상위 구성요소 withReactQuery로 래핑해야 합니다.

v3로 업그레이드하고 getProps를 계속 사용하려는 프로젝트의 경우, AppConfig 구성요소를 withLegacyGetProps 구성요소로 래핑합니다.

package.json의 종속 구성요소를 다음과 같이 변경합니다.

Node 18 및 npm 9를 지원하도록 package.json의 엔진을 업데이트합니다. Chakra의 최신 메이저 버전은 버전 2이므로 package.json의 peerDependencies에서 @chakra-ui/system을 제거합니다.

Chakra 2와 호환되지 않는 jest-environment-jsdom의 종속 구성요소인 버그 nswapi가 있습니다. 이로 인해 Modal 구성요소를 사용한 일부 테스트에서 ')([disabled]' is not a valid selector라는 오류가 발생합니다. 이 버그는 단위 테스트에만 영향을 미치며 브라우저 실행에는 영향을 미치지 않습니다. npm 8을 사용하고 재정의를 추가하여 2.2.2 버전의 nwsapi 패키지를 적용하면 npm 7 지원이 중단됩니다.

package.json에 overrides 속성을 추가하여 패키지 버전을 적용합니다.

npm i를 사용하여 프로젝트의 종속 구성요소를 다시 설치합니다.

react-hook-form 마이그레이션의 경우, 여기에서 react-hook-form 공식 문서를 참조하십시오. PWA 프로젝트에서는 다음과 같이 두 곳을 변경해야 합니다.

1. errors 오브젝트가 formState 오브젝트로 이동되었으므로 app/components/forms/*의 후크에 대해 errors 오브젝트를 하나 더 상위의 분해 계층으로 이동합니다.

2. Controller의 render 속성을 field 속성으로 이동합니다. Render의 콜백 시그니처는 field와 fieldState가 포함된 오브젝트를 반환합니다.

React 18을 기준으로, 하이드레이션 경고는 React 17에서와 마찬가지로 경고가 아닌 오류로 나타납니다. 하이드레이션 오류가 있을 때 애플리케이션이 생성되지 않도록 하는 이러한 잠재적 오류를 방지하기 위해 몇 가지 코드 업데이트를 적용해야 했습니다. 앱이 동일한 형식으로 렌더링할 수 있도록 이러한 오류를 반드시 수정해야 합니다. 이 오류는 서버 또는 클라이언트 간의 불일치로 인해 발생합니다. 구성요소 또는 페이지가 조건부로 렌더링되는 경우, 클라이언트별 코드를 렌더링하기 전에 하이드레이션이 완료되었는지 확인해야 합니다.

프로젝트에서 utility 함수를 생성하여 하이드레이션이 완료되었는지 확인합니다. pwa-kit-react-sdk의 window.__HYDRATING__에서 제공하는 내장 변수를 사용할 수 있습니다.

조건부 렌더링을 사용하는 곳에 이 함수를 추가합니다. PWA Kit 프로젝트에는 이 함수를 추가할 수 있는 몇몇 위치가 있습니다.

여기를 참조하십시오.

DOM 렌더링을 방해하는 브라우저 플러그인이 설치되어 있는 경우, 푸터에서 하이드레이션 오류가 발생할 수 있습니다. 예를 들어 LastPass 확장을 사용하는 경우 LastPass가 브라우저의 렌더링을 이어받아 아이콘을 삽입함으로써 인필드 팝업을 활성화하기 때문에, 푸터의 Subscribe 구성요소에 오류가 표시됩니다. 하이드레이션 과정에서 이 탈취가 발생하면 오류가 나타납니다. isHydrated()를 사용할 필요 없이, 다음과 같이 입력 구성요소의 순서를 바꾸는 간단한 방법을 사용할 수 있습니다.

Chakra 2를 지원하려면 Retail React App 템플릿을 기반으로 하는 프로젝트에 대해 몇 가지 파일을 업데이트해야 합니다.

Chakra 2에서는 allowMultiple과 allowToggle을 동시에 사용할 수 없으므로, Accordion 구성요소에서 allowToggle을 제거합니다.

Footer 구성요소의 @chakra-ui/react에서 StylesProvider를 직접 가져오는 기능은 더 이상 사용되지 않습니다. 대신 createStylesContext('Footer')를 통해 생성해야 합니다.

작업을 호출하기 전에 userEvent를 설정하고 userEvent를 사용하는 단위 테스트에서 작업을 기다립니다. React 테스트 라이브러리 v14.0.0에서는 모든 사용자 작업이 비동기로 이루어지므로 사용자 작업을 수행하기 전에 setup을 호출해야 합니다.

예:

자세한 내용은 테스트 라이브러리에서 userEvent에 대한 공식 문서를 참조하십시오.

또는 많은 단위 테스트에서 setup()을 반복적으로 호출하지 않도록 테스트 구성요소를 렌더링하기 직전에 app/utils/test-util.js의 userEvent를 설정하고, 렌더링 결과와 함께 반환함으로써 테스트에서 setup()을 호출하지 않고 사용자 작업을 수행할 수 있습니다.

jest-setup에는 jest-setup.js에 TextDecoder가 정의되어 있지 않은 데 대한 오류를 유발할 수 있는 모의 종속 구성요소가 있습니다. jest-setup.js에 다음을 추가합니다.

npx pwa-kit-create-app@2.x를 통해 생성된 프로젝트 또는 PWA Kit SDK 버전 2.x에서 마이그레이션하는 과정에서, app/commerce-api/* 디렉터리를 제거하기 위해 @salesforce/commerce-sdk-react 코드가 대폭 리팩터링되었습니다. API 요청을 처리하고 SDK 역할을 하는 파일을 대신하여 @salesforce/commerce-sdk-react가 해당 기능을 수행합니다. SDK가 이 라이브러리를 많이 사용하므로, SDK의 v3 릴리스는 @salesforce/retail-react-app@^1.x의 첫 번째 릴리스와 관련이 있습니다.

@salesforce/commerce-sdk-react를 구현하면 Retail React App의 많은 파일이 변경됩니다. 변경 내용의 크기를 파악하려면 이 GitHub diff에서 release-2.7.x → release-3.0.x를 비교하고 @salesforce/commerce-sdk-react를 검색하십시오. diff에서 이 가져오기를 추가하는 모든 추가 사항을 기록하십시오.