아이콘을 apps/<app>/public/에 둡니다. 이 폴더는 사이트 루트에서 제공되므로 public/icon-192x192.png는 /icon-192x192.png로 열립니다.
매니페스트를 두 방법 중 하나로 선언합니다. .head()에서 링크하는 정적 manifest.json, 또는 rootLayout().manifest({...})입니다.
배포한 뒤 매니페스트 안의 URL이 모두 열리는지 확인하고, 설치를 시험합니다.

선언하는 두 방법

정적 JSON 파일

apps/<app>/public/manifest.json

키. 브라우저가 읽는 그대로의 snake_case로 씁니다.
연결. .head()에 직접 쓰는 <link rel="manifest">로 연결합니다.
이럴 때. 디자이너나 운영자가 JSON을 직접 확인해야 할 때 고릅니다.

.manifest() 객체

apps/<app>/page/_layout.tsx

키. camelCase로 쓰면 snake_case로 바꿔 줍니다.
연결. Akan이 head에 넣는 data: URL 링크라서 파일은 따로 없습니다.
이럴 때. TypeScript 도움을 받으며 앱 메타데이터를 한곳에 두고 싶을 때 고릅니다.

PWA를 쓰기 좋은 경우

PWA는 웹 앱에 다시 들어오기 쉽게 만드는 방법입니다. 모든 네이티브 앱을 대신하지는 못하지만, 웹으로 빨리 배포하는 것이 중요하고 깊은 기기 API가 필요 없다면 좋은 첫 선택입니다.

상황

PWA만으로

네이티브 병행

잘 맞는 경우

매일 쓰는 업무 흐름

✓

사무 업무, 승인, 보고서, 체크리스트처럼 사용자가 매일 같은 흐름으로 돌아옵니다.

스토어보다 웹 먼저

✓

앱스토어에 내기 전에, 배포한 웹 앱 하나로 데스크톱과 모바일을 함께 지원합니다.

주의할 경우

깊은 네이티브 기능

✓

제품의 핵심이 브라우저가 열어 주지 않는 기기 기능에 달려 있습니다.

무거운 백그라운드 작업

✓

앱이 화면에 없을 때도 무거운 작업을 계속해야 합니다.

앱스토어 입점

✓

앱스토어에 올라가 있는 것이 꼭 필요합니다.

✓해당해당 없음

주의할 세 경우에는 PWA와 함께 네이티브 래퍼나 네이티브 앱도 계획하세요.

정적 매니페스트 파일

이미 manifest.json이 있거나, 브라우저가 읽는 JSON을 직접 다루고 싶을 때 씁니다. 먼저 파일을 public/에 둡니다.

apps/myapp/public/manifest.json

그다음 루트 _layout.tsx의 .head()에서 링크합니다.

apps/myapp/page/_layout.tsx

표준 키. 파일이 그대로 전달되므로 short_name, start_url처럼 브라우저가 쓰는 snake_case 키로 씁니다.
실제 URL. public/manifest.json은 /manifest.json으로 제공되므로 브라우저에서 바로 열어 확인할 수 있습니다.

레이아웃 매니페스트 객체

rootLayout().manifest({...})를 쓰면 매니페스트를 별도 JSON 파일이 아닌 앱 코드에 둘 수 있습니다. 키는 camelCase로 씁니다.

apps/myapp/page/_layout.tsx

camelCase로 쓰고 snake_case로 전달. shortName, startUrl, themeColor는 어느 깊이에 있든 표준 키인 short_name, start_url, theme_color로 바뀌어 전달됩니다.
따로 제공할 파일 없음. 객체는 head의 <link rel="manifest">가 되고 href는 data: URL이라서, 열어 볼 /manifest.json은 없습니다.
루트 레이아웃 전용. .manifest()는 rootLayout()의 단계이므로 앱(또는 base path)의 루트 _layout.tsx에 씁니다.

쓸 수 있는 키

인자 타입은 akanjs/client의 WebAppManifest입니다. 모든 키는 선택입니다.

namestring

설치 창과 앱 목록에 보이는 전체 이름입니다.

shortNamestring

홈 화면 아이콘 아래에 붙는 짧은 이름입니다.

descriptionstring

앱을 한 줄로 설명합니다.

startUrlstring

설치된 앱을 열면 처음 뜨는 페이지입니다.

scopestring

설치된 앱 창 안에 머무는 URL 범위입니다.

display"fullscreen" | "standalone" | "minimal-ui" | "browser"

창을 여는 방식으로, standalone은 브라우저 도구 막대를 숨깁니다.

displayOverridestring[]

display보다 먼저 차례대로 시도할 표시 방식 목록입니다.

orientationstring

portrait 같은 기본 화면 방향입니다.

themeColorstring

앱을 둘러싼 제목 표시줄과 시스템 UI의 색입니다.

backgroundColorstring

앱이 뜨는 동안 보이는 시작 화면의 배경색입니다.

langstring

name, description 같은 텍스트 값의 언어(예: ko)입니다.

dir"ltr" | "rtl" | "auto"

그 텍스트 값들의 쓰기 방향입니다.

iconsWebAppManifestIcon[]

앱 아이콘 목록으로, 항목마다 src는 필수이고 sizes, type, purpose는 선택입니다.

categoriesstring[]

business처럼 앱을 분류하는 값입니다.

screenshotsWebAppManifestIcon[]

더 풍부한 설치 창에 쓰는 이미지로, 항목 형태는 icons와 같습니다.

[key: string]unknown

shortcuts, id 같은 다른 멤버도 키 이름만 snake_case로 바뀌어 그대로 전달됩니다.

필요한 파일과 URL

설치를 시험하기 전에, 매니페스트 안의 모든 URL이 배포된 앱에서 열리는지 확인하세요. 먼저 볼 것은 다음과 같습니다.

파일 또는 키설명

/icon-192x192.png/icon-512x512.png

설치 안내에 쓰기 좋은 첫 크기이며, Chrome은 144px 이상인 아이콘이 하나는 있어야 합니다.

startUrl

설치된 앱을 시작하면 열리는 페이지라서, 배포된 앱에서 실제로 열려야 합니다.

scope

설치된 앱 창에 속하는 URL 범위를 제한합니다.

display: "standalone"

앱을 일반 브라우저 도구 막대 없이 엽니다.

팁과 주의점

단순하게 시작하세요. 처음에는 단순한 매니페스트 하나로 시작하고, 설치가 되면 screenshots, categories, shortcuts를 더하세요.
base path 아래라면. startUrl과 scope를 / 대신 그 경로로 지정하세요. 자기 .manifest()가 없는 base path 루트 _layout.tsx는 앱 루트의 매니페스트를 씁니다.
방법은 하나만. 둘 다 쓰면 페이지에 <link rel="manifest">가 두 개 생기고, 브라우저는 첫 번째만 읽습니다.
HTTPS에서 시험하세요. 브라우저는 HTTPS나 localhost에서만 설치를 제안합니다. Chrome 개발자 도구의 Application → Manifest에서 읽힌 값과 설치가 안 되는 이유를 볼 수 있습니다.

이어서 읽기

루트 레이아웃 단계→

.manifest()와 함께 루트 레이아웃만 받는 단계를 모았습니다.

Base Path→

한 앱이 page 폴더를 나눠 여러 서비스를 제공하는 방법입니다.

모바일 설정→

같은 앱을 @akanjs/native 런타임으로 iOS·Android 네이티브 앱으로 만듭니다.

이전쿠버네티스 다음테스트