Next.js App Router vs. Pages Router 파헤치기 1: 라우팅 매칭

function findDir(dir, name) {
  let curDir = path.join(dir, name);
  if (fs.existsSync(curDir)) return curDir;
  curDir = path.join(dir, 'src', name); // 루트에 없으면 src/ 아래도 한 번 더 시도
  if (fs.existsSync(curDir)) return curDir;
  return null;
}
 
function findPagesDir(dir) {
  const pagesDir = findDir(dir, 'pages') || undefined;
  const appDir = findDir(dir, 'app') || undefined;
  return { pagesDir, appDir }; // 둘 다 반환 —> 한 프로젝트에서 동시 사용을 허용
}

async function collectPagesFiles(pagesDir, validFileMatcher) {
  return recursiveReadDir(pagesDir, {
    pathnameFilter: validFileMatcher.isPageFile,
  });
}

async function collectAppFiles(appDir, validFileMatcher) {
  const allAppFiles = await recursiveReadDir(appDir, {
    pathnameFilter: (p) =>
      validFileMatcher.isAppRouterPage(p) ||
      validFileMatcher.isRootNotFound(p) ||
      validFileMatcher.isAppLayoutPage(p) ||
      validFileMatcher.isAppDefaultPage(p),
    ignorePartFilter: (part) => part.startsWith('_'), // _components, _utils 같은 private 폴더는 빌드에서 제외
  });
  // 역할별로 분리 — 이후 loader tree 빌드 단계에서 layout/default를 따로 끼워 넣으려면 분리가 필요
  const appPaths = allAppFiles.filter(
    (p) => validFileMatcher.isAppRouterPage(p) || validFileMatcher.isRootNotFound(p),
  );
  const layoutPaths = allAppFiles.filter((p) => validFileMatcher.isAppLayoutPage(p));
  const defaultPaths = allAppFiles.filter((p) => validFileMatcher.isAppDefaultPage(p));
  return { appPaths, layoutPaths, defaultPaths };
}

class PagesManifestPlugin {
  async createAssets(compilation) {
    const entrypoints = compilation.entrypoints;
    const pages = {};    // pages-manifest.json에 들어갈 항목
    const appPaths = {}; // app-paths-manifest.json에 들어갈 항목
 
    for (const entrypoint of entrypoints.values()) {
      const pagePath = getRouteFromEntrypoint(entrypoint.name, this.appDirEnabled);
      if (!pagePath) continue;
 
      const files = entrypoint
        .getFiles()
        .filter((f) => !f.includes('webpack-runtime') && f.endsWith('.js'));
      const file = files[files.length - 1]; // 마지막 파일이 이 entry의 실제 청크
 
      // entry 이름의 prefix만 보고 두 매니페스트로 분기
      if (entrypoint.name.startsWith('app/')) {
        appPaths[pagePath] = file;
      } else {
        pages[pagePath] = file;
      }
    }
  }
}

class AppBuildManifestPlugin {
  createAsset(compilation) {
    const manifest = { pages: {} };
    const mainFiles = new Set(getEntrypointFiles(
      compilation.entrypoints.get(CLIENT_STATIC_FILES_RUNTIME_MAIN_APP)
    ));
    for (const entrypoint of compilation.entrypoints.values()) {
      if (SYSTEM_ENTRYPOINTS.has(entrypoint.name)) continue;
      const pagePath = getAppRouteFromEntrypoint(entrypoint.name);
      if (!pagePath) continue;
      const filesForPage = getEntrypointFiles(entrypoint);
      manifest.pages[pagePath] = [...new Set([...mainFiles, ...filesForPage])];
    }
  }
}

{
  "/_error": "pages/_error.js",
  "/_app": "pages/_app.js",
  "/_document": "pages/_document.js",
  "/404": "pages/404.html"
}

{
  "/about/page": "app/about/page.js",
  "/blog/page": "app/blog/page.js",
  "/page": "app/page.js",
  "/blog/[slug]/page": "app/blog/[slug]/page.js",
  "/api/chat/route": "app/api/chat/route.js",
  "/api/media/route": "app/api/media/route.js",
  "/sitemap.xml/route": "app/sitemap.xml/route.js",
  "/robots.txt/route": "app/robots.txt/route.js"
}

{}

{
  "/api/comments/route": "app-edge-has-no-entrypoint",
  "/api/likes/route": "app-edge-has-no-entrypoint",
  "/api/views/route": "app-edge-has-no-entrypoint",
  "/blog/[slug]/page": "app/blog/[slug]/page.js",
  "/icon.png/route": "app/icon.png/route.js",
  "/page": "app/page.js"
}

function getParametrizedRoute(route, includeSuffix, includePrefix) {
  const groups = {};   // 정규식 capture group 위치 매핑
  let groupIndex = 1;  // capture group은 1번부터
  const segments = [];
 
  for (const segment of removeTrailingSlash(route).slice(1).split('/')) {
    const markerMatch = INTERCEPTION_ROUTE_MARKERS.find((m) => segment.startsWith(m));
    const paramMatches = segment.match(PARAMETER_PATTERN);
 
    if (markerMatch && paramMatches && paramMatches[2]) {
      // 인터셉팅 라우트 + 동적 파라미터: 마커를 그대로 정규식에 박아둠
      const { key, optional, repeat } = parseMatchedParameter(paramMatches[2]);
      groups[key] = { pos: groupIndex++, repeat, optional };
      segments.push('/' + escapeStringRegexp(markerMatch) + '([^/]+?)');
    } else if (paramMatches && paramMatches[2]) {
      const { key, repeat, optional } = parseMatchedParameter(paramMatches[2]);
      groups[key] = { pos: groupIndex++, repeat, optional };
      // catch-all/optional 여부에 따라 패턴이 갈림
      const pattern = repeat
        ? optional
          ? '(?:/(.+?))?'  // [[...slug]]: 슬래시까지 통째로 optional
          : '/(.+?)'       // [...slug]  : 슬래시 포함, 끝까지 매치
        : '/([^/]+?)';     // [slug]     : 한 세그먼트만
      segments.push(pattern);
    } else {
      // 정규식 메타문자만 escape
      segments.push('/' + escapeStringRegexp(segment));
    }
  }
  return { parameterizedRoute: segments.join(''), groups };
}

export const PARAMETER_PATTERN = /^([^[]*)\[((?:\[[^\]]*\])|[^\]]+)\](.*)$/
 
export function parseMatchedParameter(param: string) {
  // 바깥 [[ ]] 한 겹이 있으면 optional, 그 안의 ...은 catch-all
  const optional = param.startsWith('[') && param.endsWith(']')
  if (optional) {
    param = param.slice(1, -1)
  }
  const repeat = param.startsWith('...')
  if (repeat) {
    param = param.slice(3)
  }
  return { key: param, repeat, optional }
}

function getRouteMatcher(param) {
  const { re, groups } = param;
  return (pathname) => {
    const routeMatch = re.exec(pathname);
    if (!routeMatch) return false;
 
    const decode = (p) => {
      try {
        return decodeURIComponent(p);
      } catch {
        throw new DecodeError('failed to decode param');
      }
    };
 
    const params = {};
    for (const [key, group] of Object.entries(groups)) {
      const match = routeMatch[group.pos]; // 정규식 매치 결과에서 capture group 가져오기
      if (match !== undefined) {
        if (group.repeat) {
          params[key] = match.split('/').map(decode); // catch-all은 슬래시 단위 배열로
        } else {
          params[key] = decode(match);
        }
      }
    }
    return params;
  };
}

getRouteMatchers() {
  const manifestLoader = new ServerManifestLoader((name) => {
    switch (name) {
      case PAGES_MANIFEST:
        return this.getPagesManifest() ?? null;
      case APP_PATHS_MANIFEST:
        return this.getAppPathsManifest() ?? null;
      default:
        return null;
    }
  });
 
  const matchers = new DefaultRouteMatcherManager();
  // Page Router 페이지/API는 항상 등록
  matchers.push(new PagesRouteMatcherProvider(this.distDir, manifestLoader, this.i18nProvider));
  matchers.push(new PagesAPIRouteMatcherProvider(this.distDir, manifestLoader, this.i18nProvider));
 
  if (this.enabledDirectories.app) {
    // app 디렉토리가 존재할 때만 App Router 매처도 추가
    matchers.push(new AppPageRouteMatcherProvider(this.distDir, manifestLoader));
    matchers.push(new AppRouteRouteMatcherProvider(this.distDir, manifestLoader));
  }
  return matchers;
}

async *matchAll(pathname, options) {
  pathname = ensureLeadingSlash(pathname);
 
  // 정적 라우트가 우선 — 단순 문자열 비교라 빠르고 우선순위도 높음
  if (!isDynamicRoute(pathname)) {
    for (const matcher of this.matchers.static) {
      const match = this.validate(pathname, matcher, options);
      if (!match) continue;
      yield match;
    }
  }
 
  // 동적 라우트는 정렬된 순서대로 (정적 자식 > [slug] > [...slug] > [[...slug]])
  for (const matcher of this.matchers.dynamic) {
    const match = this.validate(pathname, matcher, options);
    if (!match) continue;
    yield match;
  }
}

class UrlNode {
  placeholder: boolean = true
  children: Map<string, UrlNode> = new Map()
  slugName: string | null = null             // [slug]     : 자식 키는 '[]'
  restSlugName: string | null = null         // [...slug]  : 자식 키는 '[...]'
  optionalRestSlugName: string | null = null // [[...slug]]: 자식 키는 '[[...]]'
 
  private _smoosh(prefix: string = '/'): string[] {
    // 동적 키들을 일단 빼두고 정적 자식부터 처리해 우선순위를 보장
    const childrenPaths = [...this.children.keys()].sort()
    if (this.slugName !== null) {
      childrenPaths.splice(childrenPaths.indexOf('[]'), 1)
    }
    if (this.restSlugName !== null) {
      childrenPaths.splice(childrenPaths.indexOf('[...]'), 1)
    }
    if (this.optionalRestSlugName !== null) {
      childrenPaths.splice(childrenPaths.indexOf('[[...]]'), 1)
    }
 
    // 정적 자식 먼저 평탄화
    const routes = childrenPaths
      .map((c) => this.children.get(c)!._smoosh(`${prefix}${c}/`))
      .reduce((prev, curr) => [...prev, ...curr], [])
 
    if (this.slugName !== null) {
      routes.push(
        ...this.children.get('[]')!._smoosh(`${prefix}[${this.slugName}]/`)
      )
    }
 
    // 자기 자신이 placeholder가 아니면(= 실제 라우트가 끝나는 노드면) 자기를 routes 앞쪽에 넣어 우선순위를 챙김
    if (!this.placeholder) {
      const r = prefix === '/' ? '/' : prefix.slice(0, -1)
      if (this.optionalRestSlugName != null) {
        throw new Error(
          `You cannot define a route with the same specificity as a optional catch-all route ("${r}" and "${r}[[...${this.optionalRestSlugName}]]").`
        )
      }
 
      routes.unshift(r)
    }
 
    if (this.restSlugName !== null) {
      routes.push(
        ...this.children
          .get('[...]')!
          ._smoosh(`${prefix}[...${this.restSlugName}]/`)
      )
    }
 
    if (this.optionalRestSlugName !== null) {
      routes.push(
        ...this.children
          .get('[[...]]')!
          ._smoosh(`${prefix}[[...${this.optionalRestSlugName}]]/`)
      )
    }
 
    return routes
  }
}

const HTTP_ACCESS_FALLBACKS = {
  'not-found': 'not-found',
  forbidden: 'forbidden',
  unauthorized: 'unauthorized',
} as const
 
const FILE_TYPES = {
  layout: 'layout',
  template: 'template',
  error: 'error',
  loading: 'loading',
  'global-error': 'global-error',
  'global-not-found': 'global-not-found',
  ...HTTP_ACCESS_FALLBACKS,
} as const
 
const GLOBAL_ERROR_FILE_TYPE = 'global-error'
const GLOBAL_NOT_FOUND_FILE_TYPE = 'global-not-found'
const PAGE_SEGMENT = 'page$'
const PARALLEL_VIRTUAL_SEGMENT = 'slot$'

function normalizeAppPath(route) {
  return ensureLeadingSlash(
    route.split('/').reduce((pathname, segment, index, segments) => {
      if (!segment) return pathname;
      if (isGroupSegment(segment)) return pathname;      // (group) 제거
      if (segment[0] === '@') return pathname;           // @slot 제거
      // 말단 page/route는 매니페스트 키 표시용이라 URL에서 제거
      if ((segment === 'page' || segment === 'route') && index === segments.length - 1) return pathname;
      return pathname + '/' + segment;
    }, ''),
  );
}

// order matters here, the first match will be used
const INTERCEPTION_ROUTE_MARKERS = ['(..)(..)', '(.)', '(..)', '(...)'] as const;

class AppPageRouteMatcher extends RouteMatcher {
  // identity만 오버라이드 — 매칭 로직 자체는 부모(RouteMatcher) 그대로
  get identity() {
    return `${this.definition.pathname}?__nextPage=${this.definition.page}`;
  }
}