로컬 환경 설정

이 가이드에서는 PWA Kit를 사용한 개발을 위한 로컬 환경을 설정하는 방법을 설명합니다.

PWA Kit 개발에는 다음과 같은 Unix 기반 운영 체제를 사용하는 것이 좋습니다.

Linux용 Windows 서브시스템이 설치된 Windows 10
macOS 10.13 이상
Ubuntu Linux 18.x 이상

Windows 사용자: Microsoft의 Node 개발자용 공식 설명서를 참조하십시오.

Managed Runtime에서 지원되는 Node 및 Node Package Manager(NPM)의 특정 버전을 설치해야 합니다.

Node 18.x 다운로드 페이지로 이동하여 시스템에 맞는 설치 관리자를 다운로드합니다.

Windows 사용자: 사용 중인 프로세서에 해당하는 .msi 파일을 다운로드합니다. 예를 들어 64비트 인텔 프로세서를 사용하는 경우 x64 설치 관리자를 선택합니다.

Mac 사용자: .pkg 파일을 다운로드합니다.

Apple 실리콘 사용자: 아직 Rosetta를 설치하지 않은 경우 softwareupdate --install-rosetta를 실행합니다.

Linux 사용자: 사용 중인 프로세서에 해당하는 -linux 파일을 다운로드합니다. 예를 들어 64비트 인텔 프로세서를 사용하는 경우 원하는 아카이브 형식의 linux-x64 설치 관리자를 선택합니다.

이제 적절한 Node 설치 관리자를 다운로드했으므로 Node 설치 관리자를 열고 지시에 따라 설치를 완료합니다.

설치 관리자에서 메시지가 표시되면 기본 옵션을 그대로 사용하여 Node.js 런타임도 설치하고 Node Package Manager를 설치한 다음 경로에 Node.js 런타임을 추가합니다.

계속 진행하기 전에 올바른 버전의 Node 및 NPM이 설치되어 있는지 확인합니다.

터미널을 엽니다.
node -v를 실행합니다.
v18.16.1(또는 최신 18.x 버전)이 반환되는지 확인합니다.
npm -v를 실행합니다.
9.5.1(또는 Node 18.x에 포함된 최신 버전)이 반환되는지 확인합니다.

다른 버전의 NPM이 설치되어 있는 경우 다음과 같이 버전 9.5.1을 수동으로 설치할 수 있습니다.

터미널을 엽니다.
npm install -g npm@9.5.1을 실행합니다.
npm -v를 다시 실행합니다.
9.5.1이 반환되는지 확인합니다.

Windows에서 여러 버전의 Node를 관리하는 데에는 Node Version Switchher 또는 Volta를 사용하는 것이 좋습니다. 테스트 중에 문제가 발생했기 때문에 Corey Butler의 Windows용 Node Version Manager(NVM)는 권장하지 않습니다.

Mac 및 Linux 사용자의 경우 Node Version Manager를 설치하는 것이 좋습니다.

모든 PWA Kit 스토어프런트에는 Runtime Admin에서 생성된 배포 관리용 프로젝트가 있어야 합니다.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

본인 또는 팀의 누군가가 아직 만들지 않았다면, Runtime Admin에서 프로젝트를 만드는 방법은 다음과 같습니다.

Runtime Admin에 로그인합니다.
New Project(새 프로젝트)를 클릭합니다.
프로젝트의 이름을 입력합니다.
Create Project(프로젝트 생성)를 클릭합니다.

개발용 프로젝트 파일을 생성하는 데 필요하므로 프로젝트 ID를 기록해 두십시오.

프로젝트를 처음 만들 경우, 필요한 클라우드 인프라가 구축될 때까지 웹에서 사이트에 액세스할 수 없습니다. 이 배포 프로세스는 최대 40분이 걸릴 수 있습니다.

Runtime Admin에서 수행할 수 있는 작업에 대한 자세한 내용은 Managed Runtime 관리 가이드를 참조하십시오.

대부분의 PWA Kit 개발자는 이전에 생성한 프로젝트 파일 세트가 포함된 리포지토리를 복제하는 것으로 시작합니다. (새 프로젝트를 생성하는 방법을 알아보려면 다음 섹션으로 건너뛰십시오.)

프로젝트 리포지토리를 복제한 후 패키지 종속 구성요소를 설치해야 합니다.

터미널을 엽니다.
프로젝트 디렉터리로 변경합니다.
npm ci를 실행합니다.

기존 PWA Kit 프로젝트가 있고 마지막 섹션의 지침을 완료한 경우 다음 섹션으로 건너뛸 수 있습니다. 그렇지 않으면 프로젝트를 생성해야 합니다.

프로젝트를 생성하려면 터미널을 열고 다음 명령을 실행합니다. ~/PLACEHOLDER-PROJECT-ID를 Runtime Admin의 프로젝트 ID를 포함하는 경로로 바꿉니다.

npx 명령에서, @latest는 @v3.0.0 또는 @v2.7.3와 같은 Retail React App의 특정 버전으로 바꿀 수 있습니다. 버전을 지정하지 않으면 이전 버전의 캐싱으로 인해 예기치 않은 결과가 발생할 수 있습니다.

프로젝트 사전 설정을 선택하라는 메시지가 표시되면 다음 옵션 중 하나를 선택합니다.

retail-react-app-demo: Retail React App 스토어프런트 템플릿과 백엔드에 데모 Sandbox를 사용합니다. 추가 구성은 필요 없습니다.
retail-react-app: Retail React App 스토어프런트 템플릿과 백엔드에 B2C Commerce 인스턴스를 사용합니다. 구성 값을 제공해야 합니다.

retail-react-app 사전 설정을 사용하는 경우 생성기 스크립트에서 몇 가지 구성 값을 입력하라는 메시지가 표시됩니다. 이러한 구성 값은 새 PWA Kit 프로젝트를 Runtime Admin 도구 및 B2C Commerce 인스턴스의 해당 프로젝트와 연결합니다.

다음 표에는 각 프로젝트 구성 값과 해당 값이 있는 위치에 대한 자세한 정보가 나와 있습니다. 구성 값은 B2C Commerce API 설명서에서도 자세히 다룹니다. 구성 값을 참조하십시오.

구성 값	추가 정보
Managed Runtime Admin의 프로젝트 ID	Managed Runtime 관리에서는 프로젝트를 생성하고 기존 프로젝트의 프로젝트 ID를 검색하는 방법에 대해 설명합니다. 예: `example-project`
B2C Commerce 인스턴스의 URL	개발 또는 테스트에 사용할 새로운 B2C Commerce 인스턴스가 필요합니까? On-Demand Sandbox 생성을 참조하십시오. 예: `https://zzdc-001.dx.commercecloud.salesforce.com`
Commerce API 클라이언트 ID	이 식별자는 더 이상 Account Manager에서 확인할 수 없습니다. API 액세스를 위한 클라이언트 ID 생성을 참조하십시오. 예: `1adba44c-ee9b-41f9-b4bf-1bbc3dda1967`
Business Manager의 사이트 ID	특정 이커머스 사이트를 식별하는 데 사용되는 문자열입니다. Business Manager에서 사용 가능한 사이트 및 관련 사이트 ID 목록을 보려면 관리 > 사이트 > 사이트 관리로 이동합니다. 예: `RefArch`
realm 및 인스턴스를 기준으로 API 액세스를 위한 조직을 식별하는 데 사용되는 Business Manager	문자열의 Commerce API 조직 ID입니다. Business Manager에서 조직 ID를 찾으려면 관리 > 사이트 개발 > Salesforce Commerce API 설정으로 이동합니다. 예: `f_ecom_zzdc_001`
Business Manager Commerce API 짧은 코드	라우팅 목적으로 realm에 할당된 8자리 문자열입니다. 짧은 코드는 모든 인스턴스에서 전체 realm 환경에 적용됩니다. (모든 On-Demand Sandbox의 짧은 코드는 `kv7kzm78`입니다.) Business Manager에서 짧은 코드를 찾으려면 관리 > 사이트 개발 > Salesforce Commerce API 설정으로 이동합니다. 예: `kv7kzm78`
Einstein Configurator의 API 클라이언트 ID	Commerce Cloud 개발자를 위한 Einstein API 설명서를 참조하고 Einstein Configurator에 직접 액세스하십시오.

프로젝트를 생성한 후에는 생성된 프로젝트 파일을 리포지토리에 커밋하고 리포지토리를 스토어프런트 개발자와 공유하는 것이 좋습니다.

프로젝트가 생성된 후에도 프로젝트의 구성 값을 편집할 수 있습니다. 자세한 내용은 구성 파일을 참조하십시오.

다른 B2C Commerce 인스턴스와 함께 작동하도록 프로젝트 파일을 맞춤화하는 경우 등, 이 값이 변경될 때마다 구성을 업데이트해야 합니다.

로컬 개발을 위해 웹 서버를 시작하려면 프로젝트 디렉터리에서 다음 명령을 실행합니다.

이제 개발 서버가 실행 중이므로 브라우저를 열고 스토어프런트를 미리 볼 수 있습니다.

http://localhost:3000/으로 이동

언제든지 바로가기 키 Control+C를 사용하여 개발 서버를 중지할 수 있습니다.

서버 측 렌더링 페이지를 미리 보려면 미리 보려는 URL에 ?__server_only 쿼리 문자열을 추가합니다. 예를 들어 URL www.example.com?__server_only를 방문하여 www.example.com의 서버 측 렌더링 버전을 테스트할 수 있습니다.

기존 프로젝트를 복제하고 npm ci를 실행하거나 새 프로젝트를 생성한 후, 터미널에 작업이 표시되기까지 몇 분 정도 걸릴 수 있으므로 완료될 때까지 프로세스를 취소하지 마십시오. 또한 바이러스 백신 소프트웨어(특히 Windows)로 인해 설치 시간이 평소보다 훨씬 길어질 수 있습니다.
authorize 엔드포인트에서 HTTP 401 오류 응답이 나타날 경우 Shopper Login and API Access Service(SLAS)에 구성 문제가 있는 것입니다. SLAS 구성을 수정하려면 API 액세스 설정의 지침을 참조하십시오.

이제 로컬 개발 환경이 설정되었으므로 다음 단계에서는 코드 번들을 Managed Runtime에 푸시하고 Runtime Admin을 사용하여 배포합니다. Runtime Admin에 액세스할 수 있으면, 시작하기 시리즈의 마지막 가이드, 번들 푸시 및 배포를 진행할 수 있습니다.