PWA 시작하기 - Next.js 프로젝트로 PWA 만들기

이 글은 기본적으로 Next.js를 알고 계신 분들이 보기 좋은 글입니다.
하지만 모르시는 분들도 이해하실 수 있도록 작성하였습니다.

1. 프로젝트 생성

# 자바스크립트로 생성
npx create-next-app@latest

# 타입스크립트로 생성
npx create-next-app@latest --ts

 

2.  패키지 설치

먼저 Next.js에서 PWA를 적용하기 위해서는 next-pwa라는 패키지를 추가해 주어야 합니다.

따라서 아래 코드를 입력해 패키지를 설치해 줍니다.

# npm
npm install next-pwa

# yarn
yarn add next-pwa

또한 부가적으로 next-compose-plugin을 설치해 줍니다.
(이 플러그인 을 설치하는 이유는 밑에 설명 드립니다.)

# npm
npm install --save next-compose-plugins

# yarn
yarn add --dev next-compose-plugins

3. config 설정

next.config.js에 들어갑니다.

그 후, 아래와 같이 코드를 작성해 줍니다.

/** @type {import('next').NextConfig} */
const withPlugins = require("next-compose-plugins");
const withPWA = require("next-pwa");

const nextConfig = {
	reactStrictMode: true,
};

module.exports = withPlugins(
	[
		[
			withPWA,
			{
				pwa: {
					dest: "public",
				},
			},
		],
		// 추가 플러그인 작성
	],
	nextConfig
);

자 여기서 저희가 next-compose-plugins를 사용하게 되는데요, 이 패키지는 next-pwa를 사용하게 되면 하나의 플러그인만 사용할 수 있지만, 추가적으로 더 사용할 수 있게 한꺼번에 묶어주는 패키지입니다. 따라서 추가 플러그인을 사용할 때는 아래와 같이 사용하시면 됩니다.

module.exports = withPlugins(
	[
		[
			withPWA,
			{
				pwa: {
					dest: "public",
				},
			},
		],
        [
            typescript, 
            {
                typescriptLoaderOptions: {
                    transpileOnly: false,
                },
            }
        ],
        // ...
	],
	nextConfig
);

4. manifest 파일 생성

브라우저가 이 웹은 PWA라는것을 알려주기 위해서 아래와 같은 manifest를 작성해 줍니다.

{
	"theme_color": "#FF98BA",
	"background_color": "#FF98BA",
	"display": "standalone",
	"scope": "/",
	"start_url": "/",
	"short_name": "\ubb34\uc2a8\uc885\uc774\ub0e5",
	"name": "\ubb34\uc2a8\uc885\uc774\ub0e5",
	"description": "\uadc0\uc5ec\uc6b4 \uace0\uc591\uc774\uc758 \uc885\ub958\ub97c \uc54c\ub824\uc8fc\ub294 \uc6f9 \uc571\uc785\ub2c8\ub2e4.",
	"icons": [
		{
			"src": "images/icons/icon-48x48.png",
			"sizes": "48x48",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-72x72.png",
			"sizes": "72x72",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-96x96.png",
			"sizes": "96x96",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-144x144.png",
			"sizes": "144x144",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-192x192.png",
			"sizes": "192x192",
			"type": "image/png",
			"purpose": "any maskable"
		},
		{
			"src": "images/icons/icon-256x256.png",
			"sizes": "256x256",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-384x384.png",
			"sizes": "384x384",
			"type": "image/png"
		},
		{
			"src": "images/icons/icon-512x512.png",
			"sizes": "512x512",
			"type": "image/png",
			"purpose": "any maskable"
		}
	]
}

하지만 이렇게 복잡한 코드를 손으로 한땀 한땀 작성 하는것 보다는 아래 사이트를 이용해서 만드는것을 추천드립니다.

PWA Manifest Generator | SimiCart

여기서 우리가 설정해야 하는 부분은 Name, Short Name, Display, Description, Theme Color, Background Color, Icons입니다.

각 요소의 설명하자면 아래와 같다

 

• Name : PWA의 이름
• Short name : 앱 이름을 표시할 공간이 충분하지 않을 때 나타나는 이름
• Display : homescreen icon을 통해 실행될 때 app 화면이 보여지는 형태
  • browser : 일반 브라우저와 동일하게 보입니다.
  • standalone : 다른 앱들처럼 최상단에 상태표시줄을 제외한 전체화면으로 보입니다.
  • fullscreen : 상태표시줄도 제외한 전체화면으로 보여줍니다.(ex. 게임)
  • minimul-ui : fullscreen과 비슷하지만 뒤로가기, 새로고침등 최소한의 영역만 제공합니다.(모바일 크롬 전용)
• Description : app의 description 정보
• Application Scope(=scope) : app 내에서 PWA 기능을 적용할 범위
• Start url : app이 최초 실행 될 때 load되는 file의 경로
• Background color : 스플래시 배경색
• Theme color : 전체적인 테마색

다른건 사용자가 원하는 대로 설정해도 되지만 Display와 Application Scope, Start url은 아래와 같이 작성해 준다.

(궁금하면 변경해도 되긴 한다...)

• Display : standalone
• Application Scope : /
• Start url : /

그 후 Generate Manifest를 눌러준다. 그럼 압축파일이 나오게 되는데 압축 파일을 해제 한 후 manifest.webmanifest파일 이름을 manifest.json으로 변경하여 public에 넣어줍니다.

5. 아이콘 적용

이전에 manifest를 만들 떄 아이콘도 넣었다면 아이콘도 나왔을 겁니다. 하지만, 우리는 아래 사이트를 이용해서 아이콘을 만들것입니다. 

PWA Application Icon Generator Free Online Tool

앱에 적용할 512x512 png 이미지 파일을 넣어 아이콘을 생성해 줍니다.

그럼 이렇게 아이콘이 생성됩니다. 이것을 public에 넣거나 원하는 폴더 안에 넣어줍니다. 다만, 이렇게 아이콘을 넣으면 manifest안에 icons의 src 경로도 변경해 주어야 합니다. 저는 publiv/image/icons에 저장해 놓겠습니다.

6. 메타태그 적용

브라우저가 PWA라는것을 알아채고 manifest에 접근할 수 있도록 메타태그를 적용해야합니다.

따라서 아래 링크를 참고하여 _document.jsx 혹은 _document.tsx파일을 pages 폴더 안에 생성해 줍니다.

Advanced Features: Custom `Document` | Next.js

그 후 Head태그 안에 아래와 같이 메타 태그를 넣어줍니다.

 

Manifest 메타태그

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

그러면 브라우저에게 manifest를 제공할 준비가 된겁니다.

추가적으로 아래는 옵션인 메타태그입니다.

 

파비콘 메타태그

파비콘 생성 사이트에서 파비콘을 생성후 public혹은 public 내 폴더에 저장

 

Favicon & App Icon Generator

<link
    href="images/favicons/favicon-16x16.png"
    rel="icon"
    type="image/png"
    sizes="16x16"
/>
<link
    href="images/favicons/favicon-32x32.png"
    rel="icon"
    type="image/png"
    sizes="32x32"
/>

 

ios 아이콘 메타태그

<link rel="apple-touch-icon" href="images/icons/icon-192x192.png"></link>

 

Microsoft App 컬러 메타태그

<meta name="msapplication-TileColor" content="#FF98BA"></meta>

 

7. IOS 스플래시 메타태그

해당 메타태그를 활용하기 위해서는 스플래시 이미지를 만들어야 합니다.

아래 링크를 통해 Splash Screen 이미지를 만들어줍니다.

Online Splash Screen Generator - Apprene.com

다 만든 스플래시 이미지는 아래 사이트에서 각 디바이스 별 스플래시 스크린 이미지를 만든 후 public혹은 public내 원하는 위치로 저장해 줍니다.

Appscope

그리고 아래와 같이 매태태그를 _document 파일 Head 내부에 입력해 줍니다.

<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/iphone5_splash.png"
    media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/iphone6_splash.png"
    media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/iphoneplus_splash.png"
    media="(device-width: 414px) and (device-height: 736px) and (-webkit-device-pixel-ratio: 3) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/iphonex_splash.png"
    media="(device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/ipad_splash.png"
    media="(min-device-width: 768px) and (max-device-width: 1024px) and (-webkit-min-device-pixel-ratio: 2) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/ipadpro1_splash.png"
    media="(min-device-width: 834px) and (max-device-width: 834px) and (-webkit-min-device-pixel-ratio: 2) and (orientation: portrait)"
></link>
<link
    rel="apple-touch-startup-image"
    href="/images/splashscreens/ipadpro2_splash.png"
    media="(min-device-width: 1024px) and (max-device-width: 1024px) and (-webkit-min-device-pixel-ratio: 2) and (orientation: portrait)"
></link>

당연한 이야기지만, href의 위치를 정확히 설정해 주셔야 합니다.

 

8. 빌드 및 실행

아래 커맨드를 프로젝트에서 입력해 줍니다.

# npm
npm run build && npm run dev

# yarn
yarn build && yarn dev

위 커맨드를 통해 빌드를 한 후 실행하면 우리가 생성한 프로젝트가 보여집니다.

여기서 개발자 도구에 진입하여 Lighthouse 탭에서 아래와 같이 설정해 줍니다.

그 후 보고서 생성을 클릭하면 아래와 같이 PWA인지 아닌지를 판단하는 검사가 완료가 됩니다.

 

9. 앱 다운로드

앱 다운로드는 제가 만든 PWA로 만든 서비스인 무슨종이냥? 에서 확인할 수 있습니다. 참고해 주세요
https://cat-type.vercel.app/

무슨종이냥 | 홈

감사합니다.