Contents
At the beginning of 2025, Next.js is probably the best choice for React developers building server-side applications. I’m used to building apps without a framework, though. Usually it’s Express.js with a REST API, server-side rendering and client-side rendering on top. That gives maximum flexibility and costs a lot of boilerplate. Caching, prefetching, routing and HTTP cache headers are all on you. Take image optimization: you compress images, serve different sizes and formats, lazy-load them and add placeholders (LQIP, blur-up and so on). Next.js 15 does all of that out of the box.
Does it live up to its reputation? Let’s find out by building an app with Next.js 15, Ant Design 5 for UI components and React Query 5 for data fetching and state management.
Getting started#
You need Node.js 18.18 or newer. Then create the project with create-next-app:
npx create-next-app@latest demoapp
✔ Would you like to use TypeScript? … No / Yes
✔ Would you like to use ESLint? … No / Yes
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like your code inside a `src/` directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to use Turbopack for `next dev`? … No / Yes
✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes
cd demoapp
The generated project looks like this:
We won’t use CSS Modules, so page.module.css goes from src/app, along with its import in page.tsx. The default markup goes too, replaced with a placeholder:
src/app/page.tsx
export default function Home() {
return (<div></div>);
}
What we’re building#
A table-based UI for managing records, say projects. The main component is a table with the records and actions to edit or delete each one. Below the table there’s an “Add Record” button. It opens a modal form, and so does “Edit”. Around it all, a placeholder navbar (header) and a sidebar.
Ant Design#
For the UI we take Ant Design’s Table and Layout. First the dependencies:
npm i antd @ant-design/icons @ant-design/nextjs-registry @ant-design/v5-patch-for-react-19
The last package is needed because Next.js 15 runs on React 19, and Ant Design 5 doesn’t fully support React 19 without the patch.
Next.js splits markup into layouts and pages. The navbar and sidebar are shared by all pages, so they belong in the layout. The table goes into a page.
src/app/layout.tsx
import "@ant-design/v5-patch-for-react-19";
import React from "react";
import type { Metadata } from "next";
import { Layout } from "antd";
import { AntdRegistry } from "@ant-design/nextjs-registry";
import { Content } from "antd/lib/layout/layout";
export const metadata: Metadata = {
title: "Projects",
description: "Demo app built with Next.js 15, Ant Design v5, and React Query v5.",
};
export default function RootLayout({
children
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en">
<body>
<React.StrictMode>
<AntdRegistry>
<Layout className="container-root">
Navbar goes here
<Layout className="container-main">
Sidebar goes here
<Layout className="container-content">
<Content className="content" >
{ children }
</Content>
</Layout>
</Layout>
</Layout>
</AntdRegistry>
</React.StrictMode>
</body>
</html>
);
}
AntdRegistry extracts Ant Design’s first-screen styles and injects them into the HTML, so the page doesn’t flicker on load.
You may have noticed how Content is imported:
import { Content } from "antd/lib/layout/layout";
The official docs use Layout.Content instead. Why the detour? In the App Router, components are Server Components by default, and Ant Design’s components are Client Components. A Server Component can render a Client Component, but it can’t reach into its static properties like Layout.Content, because on the server it only has a reference to the client module. You get a “Could not find the module” error. Marking the layout with "use client" would make it go away, but I’d rather keep the layout a Server Component. So we import the composite parts from their own modules.
The markup also has a few classes. We could define them in globals.css, but I prefer Sass:
npm i -D sass
Rename globals.css to globals.scss and add some styling:
src/app/globals.scss
body {
margin: 0;
padding: 0;
}
.container-root {
min-height: 100vh !important;
.container-main {
flex-direction: row;
}
.container-content {
padding: 0 24px 24px;
}
.content {
padding: 24px;
margin: 0;
min-height: 280px;
}
}
and import it in the layout:
import "./globals.scss";
Note the metadata object in the layout as well. With it, Next.js manages global and per-page metadata, more cleanly than add-ons like React Helmet ever did.
Navbar and sidebar#
These components have nothing to do with routing, so they live outside app.
src/ui/Navbar/Navbar.tsx
import React from "react";
import { Divider } from "antd";
import { Header } from "antd/lib/layout/layout";
import { DesktopOutlined } from "@ant-design/icons";
const AppHeader: React.FC = () => (<Header style={{
display: "flex",
alignItems: "center",
}}>
<a className="logo">
<DesktopOutlined />
</a>
<div style={{ color: "white" }}>
John Doe
<Divider type="vertical" />
<a>logout</a>
</div>
</Header>);
export default AppHeader;
src/ui/Sidebar/Sidebar.tsx
import React from "react";
import { ProjectOutlined } from "@ant-design/icons";
import { Menu } from "antd";
import type { MenuProps } from 'antd';
import Sider from "antd/lib/layout/Sider";
const menu = [ "Item1" ];
const Sidebar: React.FC = () => {
const items: MenuProps[ "items" ] = menu.map( project => ({
label: project,
key: project,
icon: <ProjectOutlined />
}) );
return ( <Sider width={ 200 } style={{ background: "#fff" }}>
<Menu
mode="inline"
style={{ height: "100%", borderRight: 0 }}
items={ items } />
</Sider> );
};
export default Sidebar;
Header and Sider are imported the same way as Content, for the same reason. Now start the development server:
npm run dev
and open http://localhost:3000 (if port 3000 is free) to see the basic layout.
Routing#
So far page.tsx sits at the root of the app directory. We’re building a UI for managing projects, so the page should live at /projects. Following the Next.js routing conventions, we could just move the file to src/app/projects.
But we need two routes:
/projectsshows the table of projects./projects/[id]lets you edit one of them.
We could put the file into src/app/projects/[id], or better, use an optional catch-all route: src/app/projects/[[...id]]/. Then the same page.tsx handles both the list and the editing view. The table is always displayed, and when a project is being edited, a modal with the form shows up on top.
There’s no index page, so we redirect the root URL to /projects in next.config.ts:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
async redirects() {
return [
{
source: "/",
destination: "/projects",
permanent: true
}
]
}
};
export default nextConfig;
Editing records with parallel routes#
The table page is settled. What about editing?
We could read the path with usePathname and render a modal inside the page conditionally. Or we use parallel routes, which give the modal its own route with everything that comes with one: route-aware caching, prefetching, code splitting and partial rendering.
A slot for the modal#
With parallel routes we define a slot. It works much like a page.tsx, but it renders inside the layout whenever the URL matches its route. Our slot holds a modal window, so we call it modal:
A slot folder starts with @. Other than that, it’s set up like any dynamic route:
src/app/@modal/projects/[id]/page.tsx
export default async function ProjectsModal({
params,
}: {
params: Promise<{ id: string }>;
}) {
return <div>Modal window goes here</div>;
}
The slot also needs a default.tsx, which renders when no route in the slot matches:
src/app/@modal/default.tsx
export default function Default() {
return null;
}
Now the modal slot goes into the layout, next to children:
src/app/layout.tsx
export default function RootLayout({
children, modal
}: Readonly<{
children: React.ReactNode;
modal: React.ReactNode;
}>) {
return (
<html lang="en">
<body>
<React.StrictMode>
<AntdRegistry>
<Layout className="container-root">
<Navbar />
<Layout className="container-main">
<Sidebar />
<Layout className="container-content">
<Content className="content" >
{ children }
{ modal }
</Content>
</Layout>
</Layout>
</Layout>
</AntdRegistry>
</React.StrictMode>
</body>
</html>
);
}
The table stays on screen all the time, and the modal appears on top whenever a project is being edited.
For a complete app with modals as routes, see Vercel’s Nextgram example.
Data fetching#
For data fetching, it matters which kind of component you’re in. A Server Component can talk to an ORM or the database directly. A Client Component usually goes through a REST API to read or change data on the server.
For the database I wrote a simple client on top of the mysql2 package. page.tsx is a Server Component, so it uses that client to read from MySQL and passes the data down to a Client Component that renders it:
src/app/projects/[[…id]]/page.tsx
import { projectModel } from "@/utils/model";
import ProjectTable from "./ProjectTable";
export default async function Home() {
const initialData = await projectModel.findAll();
return (<div><ProjectTable initialData={ initialData }/></div>);
}
ProjectTable renders the data with Ant Design’s Table:
src/app/projects/[[…id]]/ProjectTable.tsx
"use client"
import React from "react";
import { Table } from "antd";
import type { ColumnsType } from "antd/es/table";
interface ProjectData {
id: number,
name: string,
env: string,
createdAt: string,
key?: string
};
type TableData = {
total: number;
rows: any[];
};
const ProjectTable = (
{ initialData }: { initialData: TableData } ) => {
const columns: ColumnsType<ProjectData> = [
{
title: "Name",
dataIndex: "name",
sorter: true
},
{
title: "Environment",
dataIndex: "env",
sorter: true
}
];
return <Table<ProjectData>
columns={ columns }
dataSource={ initialData ? initialData.rows : [] }
/>;
}
export default ProjectTable;
Updating the table#
Since this page uses no request-time data, Next.js prerenders it at build time into a static page. The data is frozen at whatever the database held during the build. For an admin UI that’s rarely what you want, so in a real project mark the page dynamic (export const dynamic = "force-dynamic").
Either way, to change the table when the user paginates or sorts, we need route handlers and a REST API client. Route handlers work like controllers. You define how requests are handled in a route.ts file, following the Next.js conventions:
src/app/api/v1/projects/[[…id]]/route.ts
import { type NextRequest } from "next/server";
import { projectModel } from "@/utils/model";
export async function GET( request: NextRequest ) {
const searchParams = request.nextUrl.searchParams,
params = {
pageSize: searchParams.get( "pageSize" ),
current: searchParams.get( "current" ),
sortField: searchParams.get( "sortField" ),
sortOrder: searchParams.get( "sortOrder" )
};
const dataSource = await projectModel.findAll( params );
return Response.json( dataSource );
}
A request to /api/v1/projects?current=1&pageSize=10&sortOrder=ascend&sortField=name now returns a JSON object with the requested rows and the total count from the database.
For the requests themselves, the built-in fetch would do, but I prefer axios. It’s simpler to use and has a few extras:
src/utils/api/index.ts
import axios from "axios";
import { AnyObject } from "@/utils/type";
const client = axios.create({
baseURL: `/api/v1/`
});
export async function getList( collection: string, params: AnyObject = {} ) {
const res = await client.get( collection, { params } );
return res.data;
}
Then ProjectTable.tsx gets a change handler:
src/app/projects/[[…id]]/ProjectTable.tsx
"use client"
import React, { useState } from "react";
import { Table } from "antd";
import type { TableProps } from "antd";
import type { ColumnsType } from "antd/es/table";
import { getList } from "@/utils/api";
interface ProjectData {
id: number,
name: string,
env: string,
createdAt: string,
key?: string
};
type TableData = {
total: number;
rows: any[];
};
const ProjectTable = (
{ initialData }: { initialData: TableData } ) => {
const [ data, setData ] = useState<TableData>( initialData ?? { total: 0, rows: [] } );
const columns: ColumnsType<ProjectData> = [
{
title: "Name",
dataIndex: "name",
sorter: true
},
{
title: "Environment",
dataIndex: "env",
sorter: true
}
];
const onTableChange: TableProps<ProjectData>["onChange"] = async (
{ current = 1, pageSize = 10 }, filters, sorter
) => {
const sortOrder = Array.isArray( sorter ) ? sorter[ 0 ]?.order : sorter?.order,
sortField = Array.isArray( sorter ) ? sorter[ 0 ]?.field : sorter?.field;
setData( await getList(
`projects?current=${ current }&pageSize=${ pageSize }&sortOrder=${ sortOrder }&sortField=${ sortField }` ));
};
return <Table<ProjectData>
columns={ columns }
dataSource={ data.rows }
onChange={ onTableChange }
/>;
}
export default ProjectTable;
onTableChange fires whenever the table changes, whether it’s sorting, filtering or pagination. It calls the REST API and hands the new data to the Table.
React Query#
React Query takes care of data fetching, caching, synchronization and server state. If you wonder why you’d want it on top of plain fetch, TkDodo’s Why You Want React Query makes the case well.
Install the packages:
npm i @tanstack/react-query @tanstack/query-core
Strictly speaking, @tanstack/react-query already re-exports everything from query-core, dehydrate included, so the second package is optional. Two more are worth having:
@tanstack/react-query-devtoolsfor debugging@tanstack/eslint-plugin-queryfor lint rules that catch common mistakes
React Query needs a client provider:
src/utils/providers/ReactQueryProvider.tsx
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
function ReactQueryProvider({ children }: React.PropsWithChildren) {
const [client] = useState(() => new QueryClient());
return (
<QueryClientProvider client={client}>
{children}
</QueryClientProvider>
);
}
export default ReactQueryProvider;
The arrow function in useState(() => new QueryClient()) matters. Pass new QueryClient() directly and a new client is created on every render, only to be thrown away.
The provider wraps the root children:
src/app/layout.tsx
//...
import ReactQueryProvider from "@/utils/providers/ReactQueryProvider";
//...
export default function RootLayout({
children, modal
}: Readonly<{
children: React.ReactNode;
modal: React.ReactNode;
}>) {
return (
<html lang="en">
<body>
<React.StrictMode>
<ReactQueryProvider>
...
</ReactQueryProvider>
</React.StrictMode>
</body>
</html>
);
}
Here’s how page.tsx changes:
src/app/projects/[[…id]]/page.tsx
import { dehydrate } from "@tanstack/query-core";
import { HydrationBoundary, QueryClient } from "@tanstack/react-query";
import ProjectTable from "./ProjectTable";
import { projectModel } from "@/utils/model";
export const dynamicParams = false;
export default async function Projects() {
const queryClient = new QueryClient();
await queryClient.prefetchQuery({
queryKey: [ "projects" ],
queryFn: () => projectModel.findAll(),
});
return (
<div>
<HydrationBoundary state={ dehydrate( queryClient ) }>
<ProjectTable />
</HydrationBoundary>
</div>
);
}
The page prefetches the projects on the server and dehydrates the query cache into the HTML. On the client, HydrationBoundary puts that data back into the cache. So the table renders with data right away, search engines see real content, and there’s no loading spinner on first load. One catch: with the default staleTime of 0, the hydrated data counts as stale immediately, and React Query refetches it in the background as soon as the table mounts. Give the QueryClient a staleTime above zero, as the TanStack SSR guide suggests, and that extra request goes away.
ProjectTable reads from the same cache with useQuery. The key has to match the one used for prefetching:
src/app/projects/[[…id]]/ProjectTable.tsx
import { useQuery } from "@tanstack/react-query";
// ...
const { data, isLoading, error, refetch } = useQuery<TableData>({
queryKey: [ "projects" ],
queryFn: () => getList( "projects" ),
});
data is what the REST API returned, isLoading tells whether the request is still running, error holds the details when it failed, and refetch() reloads the data on demand. Once pagination and sorting come into play, their values belong in the query key too (e.g. [ "projects", tableParams ]), and the server has to prefetch with the same key.
Deleting a project is a mutation. After it succeeds, we invalidate the projects query, and React Query fetches the list again:
src/app/projects/[[…id]]/ProjectTable.tsx
// ...
import { Popconfirm } from "antd";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { remove } from "@/utils/api";
// ...
const queryClient = useQueryClient(),
mutation = useMutation({
mutationFn: ( id: number ) => remove( "projects", id ),
onSuccess: () => {
return queryClient.invalidateQueries({ queryKey: [ "projects" ] });
},
});
const columns: ColumnsType<ProjectData> = [
// ...
{
title: "Action",
key: "action",
render: ( _, { id }: ProjectData ) => (
<Popconfirm title="Delete the project?" onConfirm={ () => mutation.mutate( id ) }>
<a>Delete</a>
</Popconfirm>
),
},
];
Popconfirm asks the user to confirm before onConfirm runs the mutation. remove() sits in the API client next to getList():
src/utils/api/index.ts
export async function remove( collection: string, id: number ) {
const res = await client.delete( `${ collection }/${ id }` );
return res.data;
}
The route handler answers it with a DELETE export, the same way GET is defined above.
So, does it live up to the reputation?#
For this kind of app, yes. Compared to my usual Express setup, routing, image optimization and caching come built in, layouts and parallel routes cover what I’d otherwise wire up by hand, and route handlers replace a separate API server. Next.js 15 is the first platform that felt complete to me. It isn’t friction-free though. Ant Design needs a React 19 patch and special imports to work in Server Components, and you have to keep track of which component runs where. I’d take that trade over maintaining my own boilerplate.