v3로 업그레이드

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

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

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

⚛️ 필수:

  • getProps의 획기적인 변화
  • React 18, Node 18, Chakra 2 등에 대한 지원을 포함한 주요 라이브러리 업데이트

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

🪝 선택 사항: @salesforce/commerce-sdk-react "후크" 통합 - 프로젝트 구현에서 API 호출을 분리하고, API 호출을 npm 라이브러리 종속성으로 업그레이드하도록 허용하며, TanStack 쿼리를 통해 여러 가지 뛰어난 기능(상태 관리 등 포함)을 가져올 수 있습니다. 시작하려면 Commerce SDK React 문서를 참조하십시오.

PWA Kit SDK가 @salesforce NPM 조직으로 이동되었습니다. v3로 업그레이드하려면 새 패키지를 설치하고 다음 패키지에 대한 모든 import 문을 바꿉니다.

  • pwa-kit-react-sdk -> @salesforce/pwa-kit-react-sdk@^3
  • pwa-kit-runtime -> @salesforce/pwa-kit-runtime@^3
  • pwa-kit-dev -> @salesforce/pwa-kit-dev@^3
  • pwa-kit-create-app -> @salesforce/pwa-kit-create-app@^3
  • retail-react-app -> @salesforce/retail-react-app@^3

v3.0.0부터 PWA Kit에는 새로운 데이터 가져오기 전략 withReactQuery가 도입되었습니다. 이 전략은 react-query 라이브러리를 사용하며 React 후크를 작성하여 데이터를 동일한 형식으로 가져올 수 있습니다. getProps와 달리 더 이상 클라이언트 측과 서버 측에 대한 데이터 가져오기 로직을 복제할 필요가 없습니다. 이 버전에서는 @salesforce/retail-react-app이 기본적으로 react-query로 구동되는 @salesforce/commerce-sdk-react를 사용합니다.

  • withReactQuery와 withLegacyGetProps를 동시에 사용할 수 있습니다.
  • getProps와 shouldGetProps는 Retail React App 페이지의 기본 템플릿에서 제거되었지만 사용 중지되지 않았습니다. 이 방법에 대한 장기적인 지원은 유지됩니다.

아래와 같이 package.json의 종속성을 변경합니다. peerDependencies에서 @chakra-ui/system을 제거하고 dependencies 또는 devDependencies 아래에 포함합니다.

Node 18 및 npm 9를 지원하도록 package.json에서 엔진을 업데이트합니다.

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

v2.7.x에서 v3.x로 마이그레이션할 때 템플릿 확장성을 사용할지 여부를 선택할 수 있습니다. 이 기능을 활용하려면 @salesforce/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 디렉터리 전체를 제거하는 것 자체가 중요한 변화의 시작점이 되었습니다.

템플릿 확장성을 사용하도록 프로젝트를 마이그레이션할 경우, PWA Kit SDK 버전 2.x와 npx pwa-kit-create-app@2.x를 통해 생성된 프로젝트는 @salesforce/commerce-sdk-react에 종속되지 않지만 최신 코드 @salesforce/retail-react-app@^1.x에서는 이 라이브러리를 많이 사용하므로 많은 파일이 변경됩니다. 변경 사항의 크기를 파악하려면 이 Github diff https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket에서 release-2.7.x → release-3.0.x를 비교하고 @salesforce/commerce-sdk-react를 검색한 후 이 가져오기를 추가하는 모든 추가 사항을 기록하면 됩니다.

앱이 버전 2.x(app/commerce-api 디렉터리 포함)와 코드를 공유하려고 하면, commerce-api 폴더와 @salesforce/commerce-sdk-react npm 모듈 모두에 이미 서로 매우 다른 형식으로 존재하는 해당 코드를 번들에 불필요하게 추가하게 될 위험성이 있습니다.

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

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

레거시 getProps() 호출이 계속 작동하도록 하려면 기본 가져오기 전략으로서 @salesforce/retail-react-app@^1을 ReactQuery로 마이그레이션하는 과정에서 변경이 필요합니다.

위에서 설명한 종속성 업그레이드를 완료하면 프로젝트에서 아래의 라이브러리와 관련한 문제가 발생할 수 있습니다. 아래 섹션에서는 이러한 문제를 해결하기 위한 솔루션을 제안합니다. 프로젝트의 세부 사항은 다양하며 제안된 솔루션은 절대적인 규칙이 아닌 지침으로 취급해야 합니다.

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

  1. errors 오브젝트를 formState 오브젝트로 이동할 때 errors 오브젝트에서 app/components/forms/의 후크를 위해 파괴하는 또 다른 계층으로 이동합니다.
  1. Controller 의 render 속성을 field 속성으로 이동합니다. Render의 콜백 시그니처는 field 와 fieldState가 포함된 오브젝트를 반환합니다.

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

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

프로젝트에서 @chakra-ui/react 라이브러리의 구성요소와 API가 Retail React App 템플릿과 다른 경우, 공식 Chakra 2 마이그레이션 문서를 참조하십시오.

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에서 이 가져오기를 포함하는 모든 추가 사항을 기록해 둡니다.