Next.js App Routerで破綻しない設計──本番で使えるアーキテクチャ実践ガイド

frontend/src/
├─ app/           
├─ features/      
├─ shared/        
└─ external/      

import { RequestDetailPageTemplate } from '@/features/requests/components/server/RequestDetailPageTemplate'
import type { PageProps } from '@/shared/types/next'

export default async function RequestDetailPage(
  props: PageProps'/requests/[requestId]'>
) {
  const { requestId } = await props.params
  const searchParams = await props.searchParams
  const highlight =
    Array.isArray(searchParams.highlight) ? searchParams.highlight[0] : searchParams.highlight

  return (
    RequestDetailPageTemplate
      requestId={requestId}
      highlightCommentId={highlight}
    />
  )
}

features/requests/
├─ components/
│  ├─ server/    
│  └─ client/    
├─ hooks/        
├─ queries/      
├─ actions/      
└─ types/        

components/client/RequestList/
├─ RequestListContainer.tsx   
├─ RequestListPresenter.tsx   
├─ useRequestList.ts          
├─ RequestList.test.tsx       
└─ index.ts                   

external/
├─ dto/           
├─ handler/       
├─ service/       
├─ repository/    
└─ client/        

frontend/eslint-local-rules/
├─ restrict-service-imports.js     # service層を直接import禁止（handlerのみ許可）
├─ restrict-action-imports.js      # *.action.ts は client/hooks からのみ利用可能
└─ use-nextjs-helpers.js           # PageProps/LayoutProps の統一／next/navigation利用チェック

import { AuthenticatedLayoutWrapper } from '@/shared/components/layout/server/AuthenticatedLayoutWrapper'
import type { LayoutProps } from '@/shared/types/next'

export const dynamic = 'force-dynamic'

export default function AuthenticatedLayout(props: LayoutProps"https://zenn.dev/">) {
  return AuthenticatedLayoutWrapper>{props.children}AuthenticatedLayoutWrapper>
}

export async function AuthenticatedLayoutWrapper({
  children,
}: {
  children: React.ReactNode
}) {
  await requireAuthServer()

  const queryClient = getQueryClient()

  return (
    HydrationBoundary state={dehydrate(queryClient)}>
      div className="bg-background text-foreground flex min-h-screen">
        Sidebar />
        div className="flex flex-1 flex-col">
          Header />
          main className="flex-1 overflow-y-auto">{children}main>
        div>
      div>
    HydrationBoundary>
  )
}

export const metadata = {
  title: 'Request List | Request & Approval System',
  description: 'Browse, filter, and search submitted requests.',
}

import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
import { RequestList } from '@/features/requests/components/client/RequestList'
import { requestKeys } from '@/features/requests/queries/keys'
import {
  ensureRequestListResponse,
  selectRequestListFetcher,
} from '@/features/requests/queries/requestList.helpers'
import { getQueryClient } from '@/shared/lib/query-client'
import {
  listAllRequestsServer,
  listAssignedRequestsServer,
  listMyRequestsServer,
} from '@/external/handler/request/query.server'

export async function RequestsPageTemplate({
  filters = {},
  activeTabKey,
}) {
  const queryClient = getQueryClient()

  await queryClient.prefetchQuery({
    queryKey: requestKeys.list(filters),
    queryFn: async () => {
      const fetcher = selectRequestListFetcher(filters, {
        listMine: listMyRequestsServer,
        listAssigned: listAssignedRequestsServer,
        listAll: listAllRequestsServer,
      })
      const response = await fetcher()
      return ensureRequestListResponse(response)
    },
  })

  return (
    section className="space-y-6 px-6 py-8">
      HydrationBoundary state={dehydrate(queryClient)}>
        RequestList filters={filters} />
      HydrationBoundary>
    section>
  )
}

'use client'

import { useQuery } from '@tanstack/react-query'
import { requestKeys } from '@/features/requests/queries/keys'
import {
  ensureRequestListResponse,
  selectRequestListFetcher,
} from '@/features/requests/queries/requestList.helpers'
import {
  listAllRequestsAction,
  listAssignedRequestsAction,
  listMyRequestsAction,
} from '@/external/handler/request/query.action'

export const useRequestListQuery = (filters = {}) =>
  useQuery({
    queryKey: requestKeys.list(filters),
    queryFn: async () => {
      const fetcher = selectRequestListFetcher(filters, {
        listMine: listMyRequestsAction,
        listAssigned: listAssignedRequestsAction,
        listAll: listAllRequestsAction,
      })
      const response = await fetcher()
      return ensureRequestListResponse(response)
    },
  })

'use client'

import { RequestListPresenter } from './RequestListPresenter'
import { useRequestList } from './useRequestList'

export function RequestListContainer({ filters }) {
  const { summaries, isLoading, isRefetching, errorMessage } = useRequestList({ filters })

  return (
    RequestListPresenter
      requests={summaries}
      isLoading={isLoading}
      isRefetching={isRefetching}
      errorMessage={errorMessage}
    />
  )
}

return useMutation({
  mutationFn: async ({ requestId }) => {
    const result = await approveRequestAction({ requestId })
    if (!result.success) throw new Error(result.error ?? 'Failed to approve request')
    return { requestId }
  },
  onSuccess: async (_data, { requestId }) => {
    await Promise.all([
      queryClient.invalidateQueries({ queryKey: approvalKeys.pending() }),
      queryClient.invalidateQueries({ queryKey: requestKeys.detail(requestId) }),
      queryClient.invalidateQueries({ queryKey: requestKeys.all }),
      queryClient.invalidateQueries({ queryKey: requestKeys.history(requestId) }),
      queryClient.invalidateQueries({ queryKey: notificationKeys.list() }),
    ])
  },
})

frontend/eslint-local-rules/
├─ restrict-service-imports.js  # client層からservice層へのimportを禁止
├─ restrict-action-imports.js   # Server Actionsはclient/hooksでのみ利用可
├─ use-nextjs-helpers.js        # PageProps/LayoutProps、next/navigationの利用を強制
├─ use-client-check.js          # 'use client' の配置を検証
└─ use-server-check.js          # 'use server' の配置を検証

import type { RequestListResponse, RequestListResult } from './types'

const DEFAULT_LIMIT = 20

export function ensureRequestListResponse(response: RequestListResponse): RequestListResult {
  if (!response.success || !response.requests) {
    throw new Error(response.error ?? 'Failed to load requests')
  }
  return {
    requests: response.requests,
    total: response.total ?? response.requests.length,
    limit: response.limit ?? DEFAULT_LIMIT,
    offset: response.offset ?? 0,
  }
}

components/client/RequestList/
├─ RequestListPresenter.tsx
├─ RequestListPresenter.test.tsx