Next.js에서 PWA 사용하기

MinJae·2025년 5월 3일

nextjs

목록 보기

12/12

PWA

이미지 출처: wikipedia

Progressive Web Application(PWA)은 웹사이트를 모바일 앱처럼 사용할 수 있게 해주는 기술입니다. 이번 포스트에서는 Next.js 프로젝트에 PWA 기능을 추가하는 방법에 대해 알아보겠습니다.

PWA란?

PWA(Progressive Web Application)는 웹과 네이티브 앱의 장점을 결합한 웹 애플리케이션입니다. 모바일에서 앱 스토어를 통해 설치하는 네이티브 앱처럼 사용할 수 있으면서도, 웹의 접근성과 편리함을 유지합니다.

PWA의 주요 특징

오프라인 작동 가능
홈 화면에 설치 가능
푸시 알림 지원
네이티브 앱과 유사한 사용자 경험 제공
항상 최신 상태 유지

Next.js 프로젝트에서 PWA 적용하기

Next.js 프로젝트에 next-pwa 라이브러리를 사용하여 PWA 기능을 추가하는 방법입니다.

1. next-pwa 패키치 설치

사용하는 패키지 매니저에 따라 next-pwa를 설치합니다.

// npm 
npm install next-pwa

// yarn
yarn add next-pwa

// pnpm
pnpm add next-pwa

2. Next.js 설정 업데이트

next.config.ts 파일을 수정하여 PWA 설정을 추가합니다.

import withPWA from 'next-pwa';

const pwaConfig = withPWA({
  dest: 'public',
  register: true,
  skipWaiting: true,
  disable: process.env.NODE_ENV === 'development',
});

export default pwaConfig(nextConfig);

3. manifest.json 파일 생성

PWA의 메타데이터를 정의하는 manifest.json 파일을 publice 디렉토리에 생성합니다.

{
  "name": "PWA manifest",
  "short_name": "PWA manifest",
  "description": "PWA manifest",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/images/icon.png",
      "sizes": "192x192",
      "type": "image/png",
    },
    {
      "src": "/images/icon.png",
      "sizes": "512x512",
      "type": "image/png",
    }
  ]
}

manifest.json에서 정의한 아이콘들을 public/icons/ 디렉토리에 추가합니다. 최소한 192x192와 512x512 크기의 아이콘을 준비하는 것이 권장됩니다.

4. RootLayout.tsx 설정

저는 App Router를 사용하므로 App Router 기준입니다.

Pages Router를 사용한다면 pages/_document.tsx 파일에 추가합니다.

app/layout.tsx 파일에 PWA 관련 메타태그를 추가합니다.

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
  manifest: '/manifest.json',
};

5. next-pwa 타입 정의 추가

TypeScript를 사용하신다면 next-pwa의 타입 정의를 추가해야 합니다.

// next-pwa.d.ts
/* eslint-disable @typescript-eslint/no-unused-vars */
declare module 'next-pwa' {
  import { NextConfig } from 'next';

  type PWAConfig = {
    dest?: string;
    disable?: boolean;
    register?: boolean;
    skipWaiting?: boolean;
  };

  const withPWA =
    (config: PWAConfig): ((nextConfig: NextConfig) => NextConfig) =>
    (nextConfig: NextConfig) =>
      NextConfig;

  export default withPWA;
}