PWA의 첫 기둥인 웹 앱 매니페스트(manifest, 앱 정보를 담은 파일)를 오늘은 직접 만들어 볼 거예요. 매니페스트는 어렵게 볼 것 없이 브라우저에게 건네는 앱 소개서라고 보면 돼요. "내 앱 이름은 이거고, 아이콘은 이거고, 열 때는 이렇게 열어줘"라고 적어두는 JSON(제이슨, 데이터를 키와 값으로 적는 형식) 파일 한 장이거든요. 이걸 잘 채워두면 브라우저가 그대로 읽어서 홈 화면 아이콘부터 앱 창 색깔까지 딱 맞춰줘요. 필드 하나하나가 실제 화면에서 어떻게 보이는지 같이 짚어볼게요.

30.1 매니페스트가 뭐예요?

매니페스트는 보통 manifest.json이라는 이름으로 만드는 파일이에요. 안에는 앱에 대한 정보가 키와 값의 쌍으로 들어가요. 가장 기본적인 뼈대는 이래요.


{
"name": "오늘의 메모",
"short_name": "메모",
"start_url": "/",
"display": "standalone"
}


name은 앱의 정식 이름이에요. 설치 안내 창이나 앱 목록에 이 이름이 떠요. short_name은 짧은 이름인데, 홈 화면 아이콘 밑처럼 공간이 좁은 곳에서 name 대신 쓰여요. 이름이 길면 아이콘 밑에서 잘리니까 짧게 하나 더 주는 거죠. 이 두 개만 있어도 브라우저는 "아, 이건 앱이 되고 싶은 사이트구나"하고 알아봐요.

30.2 어떤 필드를 더 적어요?

기본 뼈대에 살을 붙여 볼게요. 실무에서 자주 채우는 필드까지 넣으면 이런 모습이 돼요.


{
"name": "오늘의 메모",
"short_name": "메모",
"start_url": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#4a6cf7"
}


필드가 늘었지만 겁먹을 것 없어요. 하나씩 무슨 일을 하는지 뜯어볼 거예요. 위에서 새로 들어온 start_url, background_color, theme_color가 오늘의 주인공들이에요.

30.3 시작 화면은 어떻게 정해요?

start_url은 아이콘을 눌러 앱을 열 때 처음 뜨는 주소예요. 위처럼 "/"로 두면 앱을 켤 때 항상 홈부터 열려요. 상황을 그려볼게요. 사용자가 어떤 글 상세 페이지를 보다가 설치했다고 쳐요. start_url을 지정하지 않으면 다음에 앱을 열 때 그 글 페이지가 시작 화면이 돼버려요. 엉뚱한 곳에서 앱이 열리는 거죠.


그래서 start_url을 "/"나 "/home"처럼 고정해두면, 언제 설치했든 앱은 늘 같은 첫 화면으로 열려요. 결과적으로 사용자는 앱을 켤 때마다 익숙한 홈을 만나게 돼서 헷갈리지 않아요. 사소해 보여도 앱 느낌을 좌우하는 필드예요.

30.4 색깔은 어떻게 맞춰요?

background_color는 앱이 뜨는 아주 짧은 순간, 화면이 다 그려지기 전에 배경으로 깔리는 색이에요. 이걸 앱 실제 배경색과 맞춰두면 흰 화면이 깜빡 스치는 어색함이 사라져요. theme_color는 앱 창 위쪽 상태 표시줄이나 제목 영역의 색이에요. 브랜드 색을 넣으면 앱 전체가 그 색으로 통일된 느낌을 줘요.


참고로 theme_color는 HTML의 meta 태그로도 같이 알려주면 더 안정적이에요. 매니페스트를 아직 안 읽은 순간에도 색이 적용되거든요.


<meta name="theme-color" content="#4a6cf7">


이렇게 두 군데에 색을 맞춰두면, 앱을 켜는 순간부터 상태 표시줄까지 브랜드 색으로 물든 화면이 떠요. 색 하나 맞췄을 뿐인데 "대충 만든 웹"이 아니라 "신경 쓴 앱"처럼 보이는 효과가 커요.

30.5 아이콘은 어떻게 넣어요?

설치했을 때 홈 화면에 뜰 아이콘이 없으면 앱 티가 안 나겠죠. 아이콘은 icons라는 배열에 넣어요. 크기별로 여러 장을 등록하는 게 핵심이에요.


"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png"
}
]


각 아이콘은 src(파일 경로), sizes(크기), type(이미지 형식)을 적어요. 왜 여러 장이냐면, 기기마다 필요한 아이콘 크기가 달라서예요. 브라우저가 상황에 맞는 크기를 골라 쓰거든요. 실무에서는 최소한 192x192와 512x512 두 장은 꼭 챙겨요. 이 두 크기가 있어야 브라우저가 설치를 허락하는 조건을 채우기 때문이에요. 아이콘이 없거나 크기가 부족하면 설치 안내 자체가 안 뜨니, 여기서 막히는 경우가 은근히 많아요.


한 가지 더 팁을 드리면, 아이콘에 purpose(용도)라는 값을 함께 적기도 해요. 값을 any maskable로 주면, 안드로이드가 아이콘을 동그라미나 둥근 사각형 같은 기기 모양에 맞춰 잘라 넣을 때 그림이 어색하게 잘리지 않아요. 아이콘 가장자리에 여백을 넉넉히 둔 이미지를 maskable용으로 준비해두면 어떤 폰에서든 깔끔하게 떨어져요.

30.6 display 모드는 뭐가 달라요?

아까 나온 display 필드가 사실 체감상 가장 재밌는 부분이에요. 앱을 어떤 창 모양으로 열지 정하거든요. 값에 따라 화면이 확 달라져요.


standalone은 주소창과 탭이 사라진 독립 앱 창으로 열려요. 우리가 흔히 떠올리는 "앱처럼 보이는" 모습이 이거예요. fullscreen은 상태 표시줄까지 싹 가린 완전 전체 화면이라 게임 같은 데 어울려요. minimal-ui는 standalone과 비슷하되 뒤로 가기 같은 최소한의 버튼만 남겨요. browser는 그냥 평범한 브라우저 탭으로 열려서 사실상 설치 앱 느낌이 안 나요. 대부분의 PWA는 standalone을 골라요. 이 한 줄로 "웹사이트"가 "앱"으로 보이느냐가 갈리니 신경 써서 정하세요.

30.7 잘 됐는지 어떻게 확인해요?

파일을 다 만들었으면 HTML에 연결해야 브라우저가 읽어요. head 안에 이 한 줄을 넣어요.


<link rel="manifest" href="/manifest.json">


잘 붙었는지 확인하는 방법도 알려드릴게요. 크롬에서 F12로 개발자 도구를 열고 Application(애플리케이션) 탭에 가면 Manifest 항목이 있어요. 여기서 우리가 적은 name, 아이콘, theme_color가 제대로 읽혔는지 미리보기로 확인할 수 있어요. 필드에 오타가 있거나 아이콘 경로가 틀리면 이 화면에 경고가 떠서 바로 알아챌 수 있으니, 매니페스트를 만들면 꼭 여기서 한번 점검하는 습관을 들이세요.

30.8 오늘 정리

오늘은 PWA의 소개서인 매니페스트를 만들었어요. name과 short_name으로 이름을 정하고, start_url로 앱이 열릴 첫 화면을, display로 창 모양을 골랐죠. background_color와 theme_color로 색을 맞추고, icons 배열에 최소 192와 512 크기 아이콘을 넣는 게 설치 조건의 핵심이었어요. 다 만든 뒤엔 link rel="manifest"로 연결하고 개발자 도구의 Application 탭에서 확인하면 돼요. 필드 하나하나가 화면의 어느 부분을 책임지는지 손에 잡혔다면, 앱 소개서 작성은 이제 여러분 것이에요.