fix(frontend): align paginated posts routing (#656)

Author: SebastianSchuetze

src/app/(frontend)/posts/_components/PostsPagination.tsx

@@ -0,0 +1,13 @@
+'use client'
+
+import { Pagination, type PaginationProps } from '@/components/molecules/Pagination'
+import { useRouter } from 'next/navigation'
+import React from 'react'
+
+type Props = Omit<PaginationProps, 'onNavigate'>
+
+export const PostsPagination: React.FC<Props> = (props) => {
+  const router = useRouter()
+
+  return <Pagination {...props} onNavigate={router.push} />
+}

src/app/(frontend)/posts/page.tsx

@@ -1,6 +1,5 @@
 import type { Metadata } from 'next/types'
 
-import { Pagination } from '@/components/molecules/Pagination'
 import configPromise from '@payload-config'
 import { getPayload } from 'payload'
 import React from 'react'
@@ -10,6 +9,7 @@ import { BlogHero } from '@/components/organisms/Blog/BlogHero'
 import { BlogCard } from '@/components/organisms/Blog/BlogCard'
 import { normalizePost } from '@/utilities/blog/normalizePost'
 import { Heading } from '@/components/atoms/Heading'
+import { PostsPagination } from './_components/PostsPagination'
 
 export const dynamic = 'force-static'
 export const revalidate = 600
@@ -80,7 +80,7 @@ export default async function Page() {
       )}
 
       <Container>
-        {posts.totalPages > 1 && posts.page && <Pagination page={posts.page} totalPages={posts.totalPages} />}
+        {posts.totalPages > 1 && posts.page && <PostsPagination page={posts.page} totalPages={posts.totalPages} />}
       </Container>
     </div>
   )

src/app/(frontend)/posts/page/[pageNumber]/page.tsx

@@ -1,17 +1,18 @@
 import type { Metadata } from 'next/types'
 
 import { CollectionArchive } from '@/components/organisms/CollectionArchive'
-import { Pagination } from '@/components/molecules/Pagination'
 import configPromise from '@payload-config'
 import { getPayload } from 'payload'
 import React from 'react'
 import PageClient from './page.client'
 import { Heading } from '@/components/atoms/Heading'
-import { notFound } from 'next/navigation'
+import { notFound, redirect } from 'next/navigation'
 import { Container } from '@/components/molecules/Container'
 import { normalizePost } from '@/utilities/blog/normalizePost'
+import { PostsPagination } from '../../_components/PostsPagination'
 
 export const revalidate = 600
+const POSTS_PER_PAGE = 12
 
 type Args = {
   params: Promise<{
@@ -21,16 +22,20 @@ type Args = {
 
 export default async function Page({ params: paramsPromise }: Args) {
   const { pageNumber } = await paramsPromise
-  const payload = await getPayload({ config: configPromise })
 
-  const sanitizedPageNumber = Number(pageNumber)
+  if (!/^\d+$/.test(pageNumber)) notFound()
+
+  const sanitizedPageNumber = Number.parseInt(pageNumber, 10)
+
+  if (!Number.isSafeInteger(sanitizedPageNumber) || sanitizedPageNumber < 1) notFound()
+  if (sanitizedPageNumber === 1) redirect('/posts')
 
-  if (!Number.isInteger(sanitizedPageNumber)) notFound()
+  const payload = await getPayload({ config: configPromise })
 
   const posts = await payload.find({
     collection: 'posts',
     depth: 1,
-    limit: 12,
+    limit: POSTS_PER_PAGE,
     page: sanitizedPageNumber,
     overrideAccess: false,
     select: {
@@ -49,6 +54,9 @@ export default async function Page({ params: paramsPromise }: Args) {
       },
     },
   })
+
+  if (!posts.docs.length || sanitizedPageNumber > posts.totalPages) notFound()
+
   const normalizedPosts = posts.docs.map(normalizePost)
   const remainingArticlesCount = Math.max((posts.totalDocs || 0) - 1, 0)
 
@@ -75,7 +83,7 @@ export default async function Page({ params: paramsPromise }: Args) {
       <CollectionArchive posts={normalizedPosts} />
 
       <Container>
-        {posts?.page && posts?.totalPages > 1 && <Pagination page={posts.page} totalPages={posts.totalPages} />}
+        {posts?.page && posts?.totalPages > 1 && <PostsPagination page={posts.page} totalPages={posts.totalPages} />}
       </Container>
     </div>
   )
@@ -95,11 +103,11 @@ export async function generateStaticParams() {
     overrideAccess: false,
   })
 
-  const totalPages = Math.ceil(totalDocs / 10)
+  const totalPages = Math.ceil(totalDocs / POSTS_PER_PAGE)
 
   const pages: { pageNumber: string }[] = []
 
-  for (let i = 1; i <= totalPages; i++) {
+  for (let i = 2; i <= totalPages; i++) {
     pages.push({ pageNumber: String(i) })
   }
 

src/components/molecules/Pagination/index.tsx

@@ -9,28 +9,29 @@ import {
   PaginationPrevious,
 } from '@/components/atoms/pagination'
 import { cn } from '@/utilities/ui'
-import { useRouter } from 'next/navigation'
 import React from 'react'
 
-export const Pagination: React.FC<{
+export type PaginationProps = {
   className?: string
   page: number
   totalPages: number
   onNavigate?: (path: string) => void
-}> = (props) => {
+}
+
+export const Pagination: React.FC<PaginationProps> = (props) => {
   const { className, page, totalPages, onNavigate } = props
   const hasNextPage = page < totalPages
   const hasPrevPage = page > 1
 
   const hasExtraPrevPages = page - 1 > 1
   const hasExtraNextPages = page + 1 < totalPages
 
-  const router = useRouter()
-  const navigate = onNavigate ?? router.push
+  const navigate = onNavigate ?? (() => undefined)
 
   const goToPage = (targetPage: number) => {
     if (targetPage < 1 || targetPage > totalPages) return
-    navigate(`/posts/page/${targetPage}`)
+    const targetPath = targetPage === 1 ? '/posts' : `/posts/page/${targetPage}`
+    navigate(targetPath)
   }
 
   return (

tests/unit/app/frontend/posts/paginatedPostsPage.test.ts

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  getPayloadMock: vi.fn(),
+  findMock: vi.fn(),
+  countMock: vi.fn(),
+  notFoundMock: vi.fn(() => {
+    throw new Error('notFound')
+  }),
+  redirectMock: vi.fn((path: string) => {
+    throw new Error(`redirect:${path}`)
+  }),
+}))
+
+vi.mock('next/navigation', () => ({
+  notFound: mocks.notFoundMock,
+  redirect: mocks.redirectMock,
+}))
+
+vi.mock('@payload-config', () => ({
+  default: {},
+}))
+
+vi.mock('payload', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('payload')>()
+  return {
+    ...actual,
+    getPayload: mocks.getPayloadMock.mockResolvedValue({
+      find: mocks.findMock,
+      count: mocks.countMock,
+    }),
+  }
+})
+
+describe('Paginated posts page route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const getModule = async () => import('@/app/(frontend)/posts/page/[pageNumber]/page')
+
+  it('redirects page 1 to canonical /posts', async () => {
+    const pageModule = await getModule()
+
+    await expect(pageModule.default({ params: Promise.resolve({ pageNumber: '1' }) })).rejects.toThrow(
+      'redirect:/posts',
+    )
+
+    expect(mocks.redirectMock).toHaveBeenCalledWith('/posts')
+    expect(mocks.getPayloadMock).not.toHaveBeenCalled()
+    expect(mocks.findMock).not.toHaveBeenCalled()
+  })
+
+  it('returns notFound for non-numeric page params', async () => {
+    const pageModule = await getModule()
+
+    await expect(pageModule.default({ params: Promise.resolve({ pageNumber: 'abc' }) })).rejects.toThrow('notFound')
+
+    expect(mocks.notFoundMock).toHaveBeenCalled()
+    expect(mocks.getPayloadMock).not.toHaveBeenCalled()
+    expect(mocks.findMock).not.toHaveBeenCalled()
+  })
+
+  it('returns notFound for page 0 and skips payload initialization', async () => {
+    const pageModule = await getModule()
+
+    await expect(pageModule.default({ params: Promise.resolve({ pageNumber: '0' }) })).rejects.toThrow('notFound')
+
+    expect(mocks.notFoundMock).toHaveBeenCalled()
+    expect(mocks.getPayloadMock).not.toHaveBeenCalled()
+    expect(mocks.findMock).not.toHaveBeenCalled()
+  })
+
+  it('returns notFound for out-of-range pages', async () => {
+    mocks.findMock.mockResolvedValueOnce({
+      docs: [],
+      totalPages: 2,
+      totalDocs: 24,
+      page: 3,
+    })
+
+    const pageModule = await getModule()
+
+    await expect(pageModule.default({ params: Promise.resolve({ pageNumber: '3' }) })).rejects.toThrow('notFound')
+
+    expect(mocks.findMock).toHaveBeenCalled()
+    expect(mocks.notFoundMock).toHaveBeenCalled()
+  })
+
+  it('builds static params with page size 12 and skips page 1', async () => {
+    mocks.countMock.mockResolvedValueOnce({ totalDocs: 25 })
+
+    const pageModule = await getModule()
+
+    await expect(pageModule.generateStaticParams()).resolves.toEqual([{ pageNumber: '2' }, { pageNumber: '3' }])
+  })
+})

tests/unit/components/paginationMolecule.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import React from 'react'
+import '@testing-library/jest-dom'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Pagination } from '@/components/molecules/Pagination'
+
+describe('Pagination molecule', () => {
+  it('navigates previous from page 2 to canonical /posts', () => {
+    const onNavigate = vi.fn()
+
+    render(<Pagination page={2} totalPages={5} onNavigate={onNavigate} />)
+
+    fireEvent.click(screen.getByLabelText('Go to previous page'))
+
+    expect(onNavigate).toHaveBeenCalledWith('/posts')
+  })
+
+  it('navigates page 1 button to canonical /posts', () => {
+    const onNavigate = vi.fn()
+
+    render(<Pagination page={1} totalPages={3} onNavigate={onNavigate} />)
+
+    fireEvent.click(screen.getByRole('button', { name: '1' }))
+
+    expect(onNavigate).toHaveBeenCalledWith('/posts')
+  })
+})