PWA

PWA(Progressive Web App)는 설치된 앱에 가까운 경험을 줄 수 있는 web app입니다. 여전히 browser 위에서 실행되지만, 설치 metadata, app icon, standalone 표시 방식, 여러 browser 기능을 사용해 더 앱다운 경험을 만들 수 있습니다.

사용자가 같은 web app을 자주 열고, 홈 화면이나 desktop launcher에서 바로 실행하면 편한 경우에 사용합니다.
Admin tool, 현장 업무 앱, 내부 dashboard, 가벼운 commerce 앱, content 앱에 유용합니다.
PWA 지원은 browser에게 앱의 이름, icon, 시작 URL, 표시 방식, 색상을 알려주는 것에서 시작합니다.

PWA를 쓰기 좋은 경우

PWA는 web app에 다시 들어오기 쉽게 만드는 방법으로 이해하면 좋습니다. 모든 native app을 대체하는 것은 아니지만, web 배포 속도가 중요하고 깊은 device 전용 API가 필요하지 않은 앱에는 좋은 첫 선택입니다.

잘 맞는 경우: office 업무, 승인, 보고서, checklist처럼 사용자가 매일 같은 workflow에 빠르게 접근해야 합니다.
잘 맞는 경우: app store 배포보다 먼저 하나의 배포된 web app으로 desktop과 mobile을 함께 지원하고 싶습니다.
주의할 경우: 깊은 native 기능, 무거운 background 작업, 엄격한 app-store 존재감이 핵심이라면 native wrapper나 native app도 함께 계획하세요.

정적 manifest 파일

이미 `manifest.json` 파일이 있거나 browser가 읽는 JSON을 직접 관리하고 싶다면 이 방식을 사용하세요.

apps/myapp/public/manifest.json

apps/myapp/page/_layout.tsx

Layout manifest object

Akan은 root layout에서 export한 `manifest`도 읽을 수 있습니다. 이 object는 document head의 manifest link로 변환됩니다.

`shortName`, `startUrl`, `themeColor`처럼 작성하기 편한 camelCase key를 사용합니다.
Akan이 이를 `short_name`, `start_url`, `theme_color` 같은 표준 manifest key로 변환합니다.
Manifest를 독립 JSON 파일보다 app code와 함께 관리하고 싶을 때 편합니다.

apps/myapp/page/_layout.tsx

필수 asset

설치 테스트 전에 manifest 안의 모든 URL이 배포된 app에서 접근 가능한지 확인하세요.

`/icon-192x192.png`와 `/icon-512x512.png`는 browser 설치 prompt를 위한 첫 icon 크기로 좋습니다.
`startUrl`은 설치된 앱을 열 때 처음 표시되는 page입니다.
`scope`는 설치된 app window에 속하는 URL 범위를 제한합니다.
`display: "standalone"`은 앱을 일반 browser toolbar 없이 열리게 합니다.

꿀팁

처음에는 단순한 manifest 하나로 시작하고, 설치가 동작한 뒤 screenshots, categories, shortcuts를 추가하세요.
앱이 base path 아래에서 제공된다면 `startUrl`과 `scope`를 `/` 대신 그 경로로 설정하세요.
Designer나 operator가 manifest를 직접 확인해야 한다면 정적 JSON 파일 방식을 사용하세요.
TypeScript 도움을 받고 app metadata를 한곳에서 관리하고 싶다면 layout object 방식을 사용하세요.

PWA

PWA를 쓰기 좋은 경우

정적 manifest 파일

Layout manifest object

필수 asset

꿀팁

인증

PWA

사용자가 같은 web app을 자주 열고, 홈 화면이나 desktop launcher에서 바로 실행하면 편한 경우에 사용합니다.
Admin tool, 현장 업무 앱, 내부 dashboard, 가벼운 commerce 앱, content 앱에 유용합니다.
PWA 지원은 browser에게 앱의 이름, icon, 시작 URL, 표시 방식, 색상을 알려주는 것에서 시작합니다.

PWA를 쓰기 좋은 경우

잘 맞는 경우: office 업무, 승인, 보고서, checklist처럼 사용자가 매일 같은 workflow에 빠르게 접근해야 합니다.
잘 맞는 경우: app store 배포보다 먼저 하나의 배포된 web app으로 desktop과 mobile을 함께 지원하고 싶습니다.
주의할 경우: 깊은 native 기능, 무거운 background 작업, 엄격한 app-store 존재감이 핵심이라면 native wrapper나 native app도 함께 계획하세요.

정적 manifest 파일

이미 `manifest.json` 파일이 있거나 browser가 읽는 JSON을 직접 관리하고 싶다면 이 방식을 사용하세요.

apps/myapp/public/manifest.json

apps/myapp/page/_layout.tsx

Layout manifest object

Akan은 root layout에서 export한 `manifest`도 읽을 수 있습니다. 이 object는 document head의 manifest link로 변환됩니다.

`shortName`, `startUrl`, `themeColor`처럼 작성하기 편한 camelCase key를 사용합니다.
Akan이 이를 `short_name`, `start_url`, `theme_color` 같은 표준 manifest key로 변환합니다.
Manifest를 독립 JSON 파일보다 app code와 함께 관리하고 싶을 때 편합니다.

apps/myapp/page/_layout.tsx

필수 asset

설치 테스트 전에 manifest 안의 모든 URL이 배포된 app에서 접근 가능한지 확인하세요.

`/icon-192x192.png`와 `/icon-512x512.png`는 browser 설치 prompt를 위한 첫 icon 크기로 좋습니다.
`startUrl`은 설치된 앱을 열 때 처음 표시되는 page입니다.
`scope`는 설치된 app window에 속하는 URL 범위를 제한합니다.
`display: "standalone"`은 앱을 일반 browser toolbar 없이 열리게 합니다.

꿀팁

처음에는 단순한 manifest 하나로 시작하고, 설치가 동작한 뒤 screenshots, categories, shortcuts를 추가하세요.
앱이 base path 아래에서 제공된다면 `startUrl`과 `scope`를 `/` 대신 그 경로로 설정하세요.
Designer나 operator가 manifest를 직접 확인해야 한다면 정적 JSON 파일 방식을 사용하세요.
TypeScript 도움을 받고 app metadata를 한곳에서 관리하고 싶다면 layout object 방식을 사용하세요.

PWA

PWA를 쓰기 좋은 경우

정적 manifest 파일

Layout manifest object

필수 asset

꿀팁