manifest.json은 주로 언제 사용되나요?

특히 PWA(Progressive Web App)를 구현할 때 중요한 역할을 하며, 일반적인 웹페이지를 모바일이나 데스크톱에서 마치 하나의 앱처럼 사용할 수 있도록 만들 때 활용됩니다.

manifest.json의 주요 설정값에는 어떤 것이 있나요?

대표적으로 웹 애플리케이션의 전체 이름을 지정하는 name, 짧은 이름을 뜻하는 short_name을 비롯해 icons, start_url, display 등의 설정이 들어갑니다.

“manifest.json” 하나로 달라지는 웹사이트, 도대체 무슨 파일일까?

Q: manifest.json 파일은 무엇인가요?

manifest.json은 웹사이트나 웹 애플리케이션이 어떤 이름과 아이콘을 가지고 어떻게 실행될 것인지 브라우저에 알려주는 설정 파일입니다.

홍TV 2026년 9월 9일 읽는 시간 약 8분

들어가며

웹 개발을 하다 보면 manifest.json이라는 파일을 한 번쯤 만나게 됩니다. 처음 보면 단순한 JSON 파일처럼 보이는데, 막상 내용을 열어보면 name, icons, start_url, display 같은 낯선 설정들이 들어 있어서 “이 파일은 대체 어디에 사용하는 거지?”라는 생각이 들기도 합니다.

간단하게 말하면 manifest.json은 웹사이트나 웹 애플리케이션이 어떤 이름과 아이콘을 가지고 어떻게 실행될 것인지 브라우저에 알려주는 설정 파일이라고 볼 수 있습니다.

특히 PWA(Progressive Web App)를 구현할 때 중요한 역할을 합니다. 일반적인 웹페이지를 모바일이나 데스크톱에서 마치 하나의 앱처럼 사용할 수 있도록 만드는 과정에서 manifest.json이 활용됩니다.

manifest.json은 어떤 역할을 할까?

웹사이트에 접속하면 브라우저는 HTML, CSS, JavaScript 등을 읽고 화면을 만들어 보여줍니다. 그런데 웹사이트를 단순한 페이지가 아니라 하나의 애플리케이션처럼 보이게 하려면 추가적인 정보가 필요합니다.

예를 들어 사용자가 웹사이트를 스마트폰 홈 화면에 추가했다고 생각해보겠습니다.

이때 홈 화면에는 어떤 이름을 표시할지, 어떤 아이콘을 사용할지, 아이콘을 눌렀을 때 어느 주소로 이동할지 등의 정보가 필요합니다. 이런 정보를 브라우저에 전달하는 데 manifest.json이 사용됩니다.

즉, 웹사이트의 기본적인 내용이 HTML이라면 manifest.json은 “이 웹사이트를 앱처럼 사용할 때 이렇게 보여주세요”라고 알려주는 설정 정보에 가깝습니다.

대표적인 설정값 알아보기

manifest.json에는 여러 가지 속성을 넣을 수 있습니다.

가장 먼저 name은 웹 애플리케이션의 전체 이름을 지정합니다. 사용자가 앱을 설치하거나 브라우저가 애플리케이션 정보를 표시할 때 활용될 수 있는 이름입니다.

short_name은 말 그대로 짧은 이름입니다. 화면 공간이 부족한 경우 긴 이름 대신 사용할 수 있도록 짧은 이름을 지정합니다.

icons는 애플리케이션 아이콘에 대한 정보를 설정합니다. 스마트폰 홈 화면 등에 추가했을 때 어떤 이미지를 아이콘으로 사용할 것인지 지정할 수 있습니다. 여러 화면 크기와 환경에 대응하기 위해 다양한 크기의 아이콘을 등록하는 경우가 많습니다.

start_url은 사용자가 애플리케이션을 실행했을 때 처음 열릴 주소를 지정합니다. 일반적인 웹사이트 주소가 될 수도 있고, 특정 페이지를 지정할 수도 있습니다.

display는 웹 애플리케이션이 어떤 형태로 표시될지를 결정하는 중요한 설정입니다. 예를 들어 standalone을 사용하면 일반적인 브라우저 UI를 최대한 줄이고 독립적인 앱처럼 실행하는 형태를 만들 수 있습니다.

이외에도 theme_color, background_color, description, orientation 등 다양한 설정을 사용할 수 있습니다.

그렇다면 모든 웹사이트에 manifest.json이 필요한가?

꼭 그렇지는 않습니다.

단순한 회사 소개 페이지나 개인 블로그처럼 일반적인 웹페이지로 운영되는 사이트라면 manifest.json이 없어도 웹사이트 자체는 정상적으로 동작합니다.

하지만 웹사이트를 모바일 환경에서 좀 더 앱처럼 사용하도록 만들고 싶거나 PWA 기능을 적용하려는 경우에는 이야기가 달라집니다.

특히 사용자가 웹사이트를 홈 화면에 추가해서 자주 사용하도록 만들 계획이라면 manifest.json을 활용하는 것이 좋습니다.

다만 여기서 한 가지 알아둘 점이 있습니다. manifest.json만 추가한다고 해서 웹사이트가 완전한 PWA가 되는 것은 아닙니다. PWA는 웹 앱 매니페스트뿐 아니라 서비스 워커(Service Worker), HTTPS 등 여러 요소가 함께 구성되어야 합니다.

실제로는 어떤 형태로 작성할까?

아주 기본적인 형태라면 다음과 같은 구조를 생각할 수 있습니다.

{
  "name": "My Web App",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

여기서 중요한 것은 JSON 문법을 지키는 것입니다. 쉼표 하나가 빠지거나 문자열에 따옴표가 잘못 들어가면 브라우저가 파일을 제대로 읽지 못할 수 있습니다.

또한 아이콘 파일의 실제 경로가 manifest.json에 작성한 경로와 일치하는지도 확인해야 합니다.

manifest.json은 어디에 연결할까?

파일을 만들어 놓기만 하면 브라우저가 자동으로 사용하는 것은 아닙니다. 일반적으로 HTML 문서의 <head> 영역에서 매니페스트 파일을 연결합니다.

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

이렇게 연결하면 브라우저가 해당 웹페이지의 웹 앱 매니페스트 정보를 확인할 수 있습니다.

개발자 도구를 자주 사용하는 분이라면 Chrome의 개발자 도구에서도 매니페스트가 제대로 인식되는지 확인할 수 있습니다. 파일 경로가 틀렸거나 JSON 형식에 문제가 있다면 이 과정에서 오류를 발견할 수 있습니다.

정리하면

manifest.json은 처음 봤을 때는 별것 아닌 JSON 설정 파일처럼 보이지만, 웹사이트를 하나의 애플리케이션처럼 구성할 때 꽤 중요한 역할을 합니다.

웹사이트의 이름과 아이콘을 지정하고, 실행할 시작 페이지를 정하고, 브라우저 화면에서 어떤 형태로 보여줄 것인지 결정하는 등 사용자에게 보이는 웹 앱의 기본적인 정보를 담고 있기 때문입니다.

특히 최근에는 웹사이트와 모바일 앱의 경계가 점점 줄어들고 있습니다. 별도의 앱을 설치하지 않아도 웹 브라우저에서 다양한 기능을 사용할 수 있고, 필요한 경우 홈 화면에 추가해 앱처럼 사용하는 방식도 자연스러워졌습니다.

이런 환경에서 manifest.json의 개념을 알아두면 PWA를 공부할 때도 훨씬 수월합니다.

처음부터 모든 옵션을 외울 필요는 없습니다. 우선 name, short_name, icons, start_url, display 정도의 역할부터 이해하고, 실제 프로젝트에서 필요한 설정을 하나씩 추가해 나가는 것이 가장 편합니다.

결국 manifest.json은 어려운 파일이라기보다 웹 애플리케이션의 기본적인 정체성과 실행 방식을 브라우저에 설명해 주는 설정 파일이라고 생각하면 이해하기 쉽습니다.

웹사이트를 단순한 페이지에서 한 단계 더 발전시켜 앱처럼 만들어 보고 싶다면, manifest.json부터 살펴보는 것이 좋은 출발점이 될 수 있습니다.

이 게시물이 얼마나 유용했나요?

별점을 클릭하여 평가하세요!

평균 평점 4.5 / 5. 투표 수: 300

아직 투표가 없습니다! 첫 번째로 평가해보세요.

홍TV