Azure Static Web Apps에 대한 로컬 개발 설정

아티클
02/29/2024

Azure Static Web Apps 사이트는 클라우드에 게시될 때 동일한 애플리케이션인 것처럼 함께 작동하는 많은 서비스를 함께 연결합니다. 이러한 서비스는 다음과 같습니다.

정적 웹앱
Azure Functions API
인증 및 권한 부여 서비스
라우팅 및 구성 서비스

이러한 서비스는 서로 통신해야 하며, Azure Static Web Apps는 클라우드에서 이 통합을 처리합니다.

그러나 애플리케이션을 로컬로 실행하는 경우 이러한 서비스는 자동으로 함께 연결되지 않습니다.

Azure에서 제공하는 것과 유사한 환경을 제공하기 위해 Azure Static Web Apps CLI는 다음과 같은 서비스를 제공합니다.

로컬 정적 사이트 서버
프런트 엔드 프레임워크 개발 서버에 대한 프록시
API 엔드포인트에 대한 프록시 - Azure Functions Core Tools를 통해 사용 가능
모의 인증 및 권한 부여 서비스
로컬 경로 및 구성 설정 적용

참고 항목

일반적으로 프런트 엔드 프레임워크를 사용하여 빌드된 사이트에서는 api 경로에서 요청을 올바르게 처리하려면 프록시 구성 설정이 필요합니다. Azure Static Web Apps CLI를 사용하는 경우 프록시 위치 값은 /api이고 CLI를 사용하지 않는 경우 값은 http://localhost:7071/api입니다.

작동 방식

다음 차트에서는 요청을 로컬로 처리하는 방법을 보여 줍니다.

Diagram showing the Azure Static Web App CLI request and response flow.

Important

http://localhost:4280으로 이동하여 CLI에서 제공하는 애플리케이션에 액세스합니다.

포트 4280으로 전송되는 요청은 요청 형식에 따라 적합한 서버로 전달됩니다.
HTML 또는 CSS와 같은 정적 콘텐츠 요청은 내부 CLI 정적 콘텐츠 서버에서 처리되거나 디버깅을 위해 프런트 엔드 프레임워크 서버에서 처리됩니다.
인증 및 권한 부여 요청은 애플리케이션에 가짜 ID 프로필을 제공하는 에뮬레이터에서 처리됩니다.
Functions Core Tools 런타임¹은 사이트의 API에 대한 요청을 처리합니다.
모든 서비스의 응답은 모두 단일 애플리케이션처럼 브라우저에 반환됩니다.

UI와 Azure Functions API 앱을 독립적으로 시작하면 Static Web Apps CLI를 시작하고 다음 명령을 사용하여 실행 중인 앱을 가리킵니다.

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

필요에 따라 swa init 명령을 사용하는 경우 Static Web Apps CLI는 애플리케이션 코드를 살펴보고 CLI에 대한 swa-cli.config.json 구성 파일을 빌드합니다. swa-cli.config.json 파일을 사용하는 경우 swa start를 실행하여 애플리케이션을 로컬로 시작할 수 있습니다.

¹ Azure Functions Core Tools는 시스템에 아직 설치되지 않은 경우 CLI에 의해 자동으로 설치됩니다.

다음 문서에서는 노드 기반 애플리케이션을 실행하는 단계를 자세히 설명하지만 모든 언어 또는 환경에 대해 프로세스가 동일합니다.

필수 조건

기존 Azure Static Web Apps 사이트: 사이트가 없는 경우 vanilla-api 스타터 앱으로 시작합니다.
npm이 있는 Node.js: npm에 대한 액세스를 포함하는 Node.js LTS 버전을 실행합니다.
Visual Studio Code: API 애플리케이션을 디버깅하는 데 사용되지만 CLI에는 필요하지 않습니다.

시작하기

기존 Azure Static Web Apps 사이트의 루트 폴더에 대한 터미널을 엽니다.

CLI를 설치합니다.
```
npm install -D @azure/static-web-apps-cli
```
팁

SWA CLI를 전역적으로 설치하려면 -D 대신 -g를 사용합니다. 그러나 SWA를 개발 종속성으로 설치하는 것이 좋습니다.
애플리케이션에 필요한 경우 앱을 빌드합니다.

npm run build를 실행하거나 프로젝트에 해당하는 명령을 실행합니다.
CLI에 대한 리포지토리를 초기화합니다.
```
swa init
```
CLI에서 제기한 질문에 답변하여 구성 설정이 올바른지 확인합니다.
CLI를 시작합니다.
```
swa start
```
http://localhost:4280으로 이동하여 브라우저에서 앱을 봅니다.

CLI를 시작하는 다른 방법

설명	명령	설명
특정 폴더 제공	`swa start ./<OUTPUT_FOLDER_NAME>`	`<OUTPUT_FOLDER_NAME>`을 출력 폴더의 이름으로 바꿉니다.
실행 중인 프레임워크 개발 서버 사용	`swa start http://localhost:3000`	이 명령은 포트 `3000`에서 실행 중인 애플리케이션의 인스턴스가 있을 때 작동합니다. 구성이 다른 경우 포트 번호를 업데이트합니다.
폴더에서 함수 앱 시작	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	`<OUTPUT_FOLDER_NAME>`을 출력 폴더의 이름으로 바꿉니다. 이 명령은 애플리케이션의 API에 `api` 폴더에 파일이 있어야 합니다. 구성이 다른 경우 이 값을 업데이트합니다.
실행 중인 함수 앱 사용	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	`<OUTPUT_FOLDER_NAME>`을 출력 폴더의 이름으로 바꿉니다. 이 명령은 포트 `7071`을 통해 Azure Functions 애플리케이션을 사용할 수 있을 것으로 예상합니다. 구성이 다른 경우 포트 번호를 업데이트합니다.

인증 및 권한 부여 에뮬레이션

Static Web Apps CLI는 Azure에 구현된 보안 흐름을 에뮬레이트합니다. 사용자가 로그인할 때 앱에 반환되는 가짜 ID 프로필을 정의할 수 있습니다.

예를 들어 /.auth/login/github로 이동하려고 하면 ID 프로필을 정의할 수 있는 페이지가 반환됩니다.

참고 항목

에뮬레이터는 GitHub뿐만 아니라 모든 보안 공급자와 함께 작동합니다.

Local authentication and authorization emulator

에뮬레이터는 다음과 같은 클라이언트 보안 주체 값을 제공할 수 있는 페이지를 제공합니다.

값	설명
사용자 이름	보안 공급자와 연결된 계정 이름입니다. 이 값은 클라이언트 보안 주체의 `userDetails` 속성으로 나타나며 값을 제공하지 않으면 자동으로 생성됩니다.
사용자 ID	CLI에서 자동으로 생성되는 값입니다.
Roles	각 이름이 새 줄에 있는 역할 이름 목록입니다.
클레임	각 이름이 새 줄에 있는 사용자 클레임 목록입니다.

로그인되면 다음을 수행합니다.

/.auth/me 엔드포인트 또는 함수 엔드포인트를 사용하여 사용자의 클라이언트 보안 주체를 검색할 수 있습니다.
/.auth/logout로 이동하면 클라이언트 보안 주체가 지워지고 모의 사용자가 로그아웃됩니다.

디버깅

정적 웹앱에는 두 가지 디버깅 컨텍스트가 있습니다. 첫 번째는 정적 콘텐츠 사이트용이고, 두 번째는 API 함수용입니다. Static Web Apps CLI가 이러한 컨텍스트 중 하나 또는 둘 모두에 대해 개발 서버를 사용할 수 있도록 하여 로컬 디버깅을 수행할 수 있습니다.

다음 단계에서는 두 가지 디버깅 컨텍스트 모두에 대해 개발 서버를 사용하는 일반적인 시나리오를 설명합니다.

정적 사이트 개발 서버를 시작합니다. 이 명령은 사용 중인 프런트 엔드 프레임워크에만 적용되지만, npm run build, npm start, 또는 npm run dev와 같은 명령의 형태로 제공되는 경우가 많습니다.
Visual Studio Code에서 API 애플리케이션 폴더를 열고 디버깅 세션을 시작합니다.
다음 명령을 사용하여 Static Web Apps CLI를 시작합니다.
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
<DEV_SERVER_PORT_NUMBER>를 개발 서버의 포트 번호로 바꿉니다.

다음 스크린샷에는 일반적인 디버깅 시나리오를 위한 터미널을 보여줍니다.

정적 콘텐츠 사이트는 npm run dev를 통해 실행되고 있습니다.

Static site development server

Azure Functions API 애플리케이션이 Visual Studio Code에서 디버그 세션을 실행하고 있습니다.

Visual Studio Code API debugging

Static Web Apps CLI는 두 개발 서버를 사용하여 시작됩니다.

Azure Static Web Apps CLI terminal

이제 포트 4280을 통과하는 요청이 정적 콘텐츠 개발 서버 또는 API 디버깅 세션으로 라우팅됩니다.

포트 및 서버 주소를 사용자 지정하는 방법에 대한 지침과 다양한 디버깅 시나리오에 대한 자세한 내용은 Azure Static Web Apps CLI 리포지토리를 참조하세요.

샘플 디버깅 구성

Visual Studio Code는 파일을 사용하여 편집기에서 디버깅 세션을 사용하도록 설정합니다. Visual Studio Code가 launch.json 파일을 생성하지 않는 경우 .vscode/launch.json에 다음 구성을 배치할 수 있습니다.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

다음 단계

애플리케이션 구성