🤖 Next.js MetadataRoute 정복: Robots, Sitemap, Manifest까지 한 번에

1) Robots 

robots.txt는 검색 엔진 크롤러가 사이트를 어떻게 탐색할 수 있는지 정의하는 파일이다.

Next.js에서는 app/robots.ts 파일을 생성하면 자동으로 /robots.txt 경로가 생성된다.

import type { MetadataRoute } from "next"; 

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [{ userAgent: '*', allow: '/' }],
    sitemap: 'https://pyomin.com/sitemap.xml'
  }
}

함수 이름은 자유롭게 지정 가능하며 파일명은 반드시 robots.ts 여야 /robots.txt 경로로 자동 라우팅 된다. 

2) Sitemap 

sitemap.xml은 사이트의 URL 구조를 검색 엔진에 전달하는 파일이다.

sitemap 역시 app/sitemap.ts 파일을 만들면 자동으로 /sitemap.xml이 생성된다.

또한 API 데이터를 활용해 동적 sitemap 생성도 가능하다. 블로그처럼 글이나 카테고리가 많은 사이트에서 매우 유용하다.

import type { MetadataRoute } from "next";
import { getApiBase } from "@/lib/api/apiBases";

export const revalidate = 86400;

const SITE_URL = 'https://pyomin.com';

// 정적 페이지 정보
const staticPagesInfo = [
  { path: '/', changeFrequency: 'weekly', priority: 1.0, lastModified: undefined },
  { path: '/posts', changeFrequency: 'weekly', priority: 0.7, lastModified: undefined },
  { path: '/about', changeFrequency: 'yearly', priority: 0.5, lastModified: '2025-09-05T00:00:00.000Z' },
  { path: '/guestbooks', changeFrequency: 'yearly', priority: 0.5, lastModified: '2025-07-01T00:00:00.000Z' },
] as const;

// API 데이터 타입 정의
type Sitemap = { key: string; lastModified: string };
type SitemapResponse<T> = { sitemap: T[] };

// sitemap 정보 가져오기
async function fetchPostSitemap(): Promise<Sitemap[]> {
  const res = await fetch(`${getApiBase()}/posts/sitemap`);
  if (!res.ok) throw new Error('posts/sitemap 실패');
  
  const json = (await res.json()) as SitemapResponse<Sitemap>;
  return json.sitemap ?? [];
}

async function fetchCategorySitemap(): Promise<Sitemap[]> {
  const res = await fetch(`${getApiBase()}/categories/sitemap`);
  if (!res.ok) return [];
  
  const json = (await res.json()) as SitemapResponse<Sitemap>;
  return json.sitemap ?? [];
}

// sitemap 생성
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const [posts, categories] = await Promise.all([fetchPostSitemap(), fetchCategorySitemap()]);
  
  const latestPostDateISO = posts.at(0)?.lastModified ?? new Date().toISOString();
  
  const staticPages: MetadataRoute.Sitemap = staticPagesInfo.map(({ path, lastModified, changeFrequency, priority }) => ({
    url: `${SITE_URL}${path}`,
    lastModified: lastModified ?? latestPostDateISO,
    changeFrequency,
    priority
  }));
  
  const categoryPages: MetadataRoute.Sitemap = categories.map((category) => ({
    url: `${SITE_URL}/posts/category/${encodeURIComponent(category.key)}`,
    lastModified: category.lastModified,
    changeFrequency: 'monthly',
    priority: 0.6,
  }));
  
  const postPages: MetadataRoute.Sitemap = posts.map((post) => ({
    url: `${SITE_URL}/posts/${encodeURIComponent(post.key)}`,
    lastModified: post.lastModified,
    changeFrequency: 'monthly',
    priority: 0.8,
  }));
  
  return [...staticPages, ...categoryPages, ...postPages];
}

정적 URL은 고정된 날짜 혹은 최신 글 기준으로 lastModified를 설정하였으며 카테고리/글 목록은 API를 통해 실시간 fetch 하여 URL 및 수정일을 지정하였다. 

또한 export const revalidate = 86400을 통해 하루에 한 번 갱신되도록 캐시 전략을 적용하였다. 

사이트 규모가 커질 경우 검색 엔진 제한이 있으므로 sitemap index 파일을 생성하여 분할 관리하는 것이 필요함

3) PWA Manifest 

manifest 파일은 브라우저에 웹 앱 설치 및 설치 후의 동작 정보를 제공하는 PWA 필수 설정 파일이다.

Next.js에서는 app/manifest.ts 파일을 생성하면 자동으로 /manifest.json 경로가 생성된다.

이 파일에는 앱 이름, 아이콘, 테마 색상, 시작 URL, 바로가기 등의 정보가 포함된다.

import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
  return {
    // 앱의 전체 이름
    name: 'BlueCool Blog',
    
    // 앱의 짧은 이름
    short_name: 'BlueCool',
    
    // 앱 설명
    description: 'BlueCool 블로그의 글들을 빠르게 탐색해보세요!',
    
    // 앱 고유 식별자
    id: '/',
    
    // 앱이 시작되는 기본 URL
    start_url: '/',
    
    // 앱이 접근 가능한 URL 범위
    scope: '/',
    
    // 앱 실행 방식
    display: 'standalone',
    
    // display가 지원되지 않을 경우 우선순위 대안
    display_override: ['standalone', 'browser'],
    
    // 앱 로딩 시 배경 색
    background_color: '#E6F7FB',
    
    // 브라우저 툴바 및 UI의 테마 색상
    theme_color: '#145B6F',
    
    // 화면 방향
    orientation: 'any',
    
    // 텍스트 방향
    dir: 'ltr',
    
    // 기본 언어 설정
    lang: 'ko-KR',
    
    // 앱의 카테고리
    categories: ['programming', 'blog', 'technology', 'education'],
    
    // 홈화면 아이콘들
    icons: [
      { src: '/images/manifest/icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
      { src: '/images/manifest/icon-192-maskable.png', sizes: '192x192', type: 'image/png', purpose: 'maskable' },
      { src: '/images/manifest/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any' },
      { src: '/images/manifest/icon-512-maskable.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
      
      { src: '/images/manifest/icon-256.png', sizes: '256x256', type: 'image/png' },
      { src: '/images/manifest/icon-384.png', sizes: '384x384', type: 'image/png' },
      
      { src: '/images/manifest/icon-32.png', sizes: '32x32', type: 'image/png' },
      { src: '/images/manifest/icon-16.png', sizes: '16x16', type: 'image/png' },
    ],
    
    // 앱 아이콘을 길게 눌렀을 때 나오는 단축 메뉴
    shortcuts: [
      { name: 'Posts', url: '/posts', description: '전체 글 목록' },
      { name: 'About', url: '/about', description: '소개' },
      { name: 'Guestbook', url: '/guestbooks', description: '방명록' },
    ],   
  };
}

manifest 설정에서 주의할 점은 아이콘을 반드시 다양한 해상도(192, 512, 256 등)로 제공해야 웹 앱 설치 버튼이 정상적으로 노출된다. 특히 Android나 일부 플랫폼에서는 maskable icon이 없으면 홈 화면 추가 시 레이아웃이 깨질 수 있다.