Skip to content
This page is also available as Markdown: request this page's URL with an Accept: text/markdown header. For an index of Next.js documentation, see /docs/llms.txt.

How to build single-page applications with Next.js

Last updated August 14, 2026

Build Single-Page Applications (SPAs) with client-side navigation and data fetching. Next.js supports client and server patterns in the same app, and existing SPAs can migrate without a full rewrite.

What is a Single-Page Application?

The definition of a SPA varies. We'll define a "strict SPA" as:

  • Client-side rendering (CSR): The app is served by one HTML file (e.g. index.html). Every route, page transition, and data fetch is handled by JavaScript in the browser.
  • No full-page reloads: Rather than requesting a new document for each route, client-side JavaScript manipulates the current page's DOM and fetches data as needed.

Strict SPAs often require large amounts of JavaScript to load before the page can be interactive. Further, client data waterfalls can be challenging to manage. Building SPAs with Next.js can address these issues.

Why use Next.js for SPAs?

Next.js can automatically code split your JavaScript bundles, and generate multiple HTML entry points into different routes. This avoids loading unnecessary JavaScript code on the client-side, reducing the bundle size and enabling faster page loads.

The next/link component automatically prefetches routes, giving you the fast page transitions of a strict SPA, but with the advantage of persisting application routing state to the URL for linking and sharing.

Next.js can start as a static site or even a strict SPA where everything is rendered client-side. If your project grows, you can progressively add more server features (e.g. React Server Components, Server Actions, and more) as needed.

Build common SPA patterns

The following examples cover common patterns for building an SPA with Next.js. The companion demo (source) shows each pattern in action.

Using React's use within a Context Provider

You can use React's use API to stream data from the server to a Client Component. Fetch the data in a Server Component (a parent or layout) and pass the Promise down. The Client Component unwraps it with use(), since it cannot await during render.

Starting the request on the server, before the rest of the app renders, lets the response stream immediately and avoids client-side request waterfalls.

You can pass a single Promise as a prop and unwrap it with use(), or pair it with a React context provider so any Client Component can read the value through a custom hook.

When a Client Component needs focus revalidation, polling, mutations, or request deduplication, use a library such as SWR or TanStack Query. See Client-side data fetching for direct browser fetching, providing initial data from a Server Component, and coordinating the library cache with the Next.js server and client caches.

Start the request in a Server Component (here, the root layout) without awaiting it, and pass the Promise to the provider:

app/layout.tsx
import { UserProvider } from './user-provider'
import { getUser } from './user' // some server-side function
 
export default function RootLayout({ children }: LayoutProps<'/'>) {
  let userPromise = getUser() // do NOT await
 
  return (
    <html lang="en">
      <body>
        <UserProvider userPromise={userPromise}>{children}</UserProvider>
      </body>
    </html>
  )
}

Good to know: Refetching a Promise set high in the tree re-runs the Server Component that set it, so for data only part of the app needs, place the provider on that subtree instead of the root layout. See React's caveat on reading a Promise from context.

If several components read the same data in one request, wrap getUser in React's cache so they share a single call. See Reusing data with React.cache for more on this pattern.

The provider forwards the Promise through context:

app/user-provider.tsx
'use client'
 
import { createContext, useContext } from 'react'
 
type User = { id: string; name: string }
 
const UserContext = createContext<Promise<User> | null>(null)
 
export function useUser() {
  const userPromise = useContext(UserContext)
  if (!userPromise) {
    throw new Error('useUser must be used within a UserProvider')
  }
  return userPromise
}
 
export function UserProvider({
  children,
  userPromise,
}: {
  children: React.ReactNode
  userPromise: Promise<User>
}) {
  return (
    <UserContext.Provider value={userPromise}>{children}</UserContext.Provider>
  )
}

Finally, call the useUser() hook in any Client Component and unwrap the Promise with use(), which suspends the component until the data is ready:

app/profile.tsx
'use client'
 
import { use } from 'react'
import { useUser } from './user-provider'
 
export function Profile() {
  const userPromise = useUser()
  const user = use(userPromise)
 
  return <p>{user.name}</p>
}

Wrap the consumer in a <Suspense> boundary to show a fallback while the Promise resolves:

app/page.tsx
import { Suspense } from 'react'
import { Profile } from './profile'
 
export default function Page() {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <Profile />
    </Suspense>
  )
}

The component that consumes the Promise (e.g. Profile above) suspends while the Promise resolves, so you see the streamed, prerendered HTML before JavaScript has finished loading.

See the live demo and its source code.

Rendering components only in the browser

Client components are prerendered during next build. If you want to disable prerendering for a Client Component and only load it in the browser environment, you can use next/dynamic:

import dynamic from 'next/dynamic'
 
const ClientOnlyComponent = dynamic(() => import('./component'), {
  ssr: false,
})

This can be useful for third-party libraries that rely on browser APIs like window or document. You can also add a useEffect that checks for the existence of these APIs, and if they do not exist, return null or a loading state which would be prerendered.

See the live demo and its source code.

Shallow routing on the client

If you are migrating from a strict SPA like Create React App or Vite, you might have existing code which shallow routes to update the URL state. This can be useful for manual transitions between views in your application without using the default Next.js file-system routing.

Next.js lets you use the native window.history.pushState and window.history.replaceState methods to update the browser's history stack without reloading the page.

The pushState and replaceState calls integrate into the Next.js Router, allowing you to sync with usePathname and useSearchParams.

app/ui/sort-products.tsx
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SortProducts() {
  const searchParams = useSearchParams()
 
  function updateSorting(sortOrder: string) {
    const urlSearchParams = new URLSearchParams(searchParams.toString())
    urlSearchParams.set('sort', sortOrder)
    window.history.pushState(null, '', `?${urlSearchParams.toString()}`)
  }
 
  return (
    <>
      <button onClick={() => updateSorting('asc')}>Sort Ascending</button>
      <button onClick={() => updateSorting('desc')}>Sort Descending</button>
    </>
  )
}

Learn more about how routing and navigation work in Next.js.

See the live demo and its source code.

Mutating data with Server Actions

Interactivity often requires writing data. A Client Component can call a Server Action to run the mutation on the server. A client data-fetching library can coordinate an optimistic browser update around the same Server Action, as shown in the client-side data fetching guide. The rest of this section coordinates the Server Action with React's built-in state APIs.

A Server Action takes time and can fail. React has useful tools to keep the UI responsive while it runs, so a mutation can feel as instant as a client-rendered SPA: transitions, useOptimistic, useActionState, and useFormStatus.

At its simplest, a Client Component calls a Server Action inside a transition and uses the pending state for feedback:

app/delete-post.tsx
'use client'
 
import { useTransition } from 'react'
import { deletePost } from './actions'
 
export function DeletePost({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition()
 
  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deletePost(id))}
    >
      {isPending ? 'Deleting…' : 'Delete'}
    </button>
  )
}

For list-like state where each change should appear instantly, you can combine useActionState with useOptimistic. The example below is a to-do list: a pure reducer defines how each action changes the list, so the client and server share one copy of that logic:

app/todos-reducer.ts
export type Todo = { id: string; text: string; done: boolean }
 
export type TodoAction =
  | { type: 'add'; id: string; text: string }
  | { type: 'toggle'; id: string }
  | { type: 'edit'; id: string; text: string }
  | { type: 'delete'; id: string }
 
export function todosReducer(todos: Todo[], action: TodoAction): Todo[] {
  switch (action.type) {
    case 'add':
      return [...todos, { id: action.id, text: action.text, done: false }]
    case 'toggle':
      return todos.map((todo) =>
        todo.id === action.id ? { ...todo, done: !todo.done } : todo
      )
    case 'edit':
      return todos.map((todo) =>
        todo.id === action.id ? { ...todo, text: action.text } : todo
      )
    case 'delete':
      return todos.filter((todo) => todo.id !== action.id)
    default:
      return todos
  }
}

The Server Action applies the reducer, persists the result, and returns the next list:

app/actions.ts
'use server'
 
import { db } from './db'
import { todosReducer, type Todo, type TodoAction } from './todos-reducer'
 
export async function saveTodos(
  todos: Todo[],
  action: TodoAction
): Promise<Todo[]> {
  const next = todosReducer(todos, action)
  await db.saveTodos(next)
  return next
}

The client passes the same reducer to useOptimistic, so the optimistic update and the server compute the next state identically. A runAction helper applies the optimistic change and dispatches the Server Action in the same transition, so every change shows immediately:

app/todo-list.tsx
'use client'
 
import { useActionState, useOptimistic, startTransition } from 'react'
import { saveTodos } from './actions'
import { todosReducer, type Todo, type TodoAction } from './todos-reducer'
 
export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  const [todos, dispatch, isPending] = useActionState(saveTodos, initialTodos)
  const [optimisticTodos, addOptimistic] = useOptimistic(todos, todosReducer)
 
  function runAction(action: TodoAction) {
    startTransition(() => {
      addOptimistic(action)
      dispatch(action)
    })
  }
 
  return (
    <>
      <form
        action={(formData) =>
          runAction({
            type: 'add',
            id: crypto.randomUUID(),
            text: String(formData.get('text')),
          })
        }
      >
        <input name="text" />
        <button>Add</button>
      </form>
      <ul>
        {optimisticTodos.map((todo) => (
          <li key={todo.id}>
            <input
              type="checkbox"
              checked={todo.done}
              onChange={() => runAction({ type: 'toggle', id: todo.id })}
            />
            <span
              style={{ textDecoration: todo.done ? 'line-through' : 'none' }}
            >
              {todo.text}
            </span>
            <button onClick={() => runAction({ type: 'delete', id: todo.id })}>
              Delete
            </button>
          </li>
        ))}
      </ul>
      {isPending && <p>Syncing to server…</p>}
    </>
  )
}

The optimistic update shows instantly, while useActionState's pending flag lets you display a subtle indicator (such as Syncing to server…) until the Server Action resolves.

See the live demo and its source code.

To learn more about adding interactivity on top of server-rendered apps so they feel like SPAs, see the Building interactive apps guide and its runnable demo.

Static export (optional)

Next.js also supports generating a fully static site. This has some advantages over strict SPAs:

  • Automatic code-splitting: Instead of shipping a single index.html, Next.js will generate an HTML file per route, so your visitors get the content faster without waiting for the client JavaScript bundle.
  • Improved user experience: Instead of a minimal skeleton for all routes, you get fully rendered pages for each route. When users navigate client side, transitions are still instant and SPA-like.

To enable a static export, update your configuration:

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  output: 'export',
}
 
export default nextConfig

After running next build, Next.js will create an out folder with the HTML/CSS/JS assets for your application.

Note: Next.js server features are not supported with static exports. Learn more.

Migrating existing projects to Next.js

You can incrementally migrate to Next.js by following our guides:

If you are already using a SPA with the Pages Router, you can learn how to incrementally adopt the App Router.

Related guides and references.

Client-side data fetching

Fetch data in Client Components with a data-fetching library, optionally provide initial data from a Server Component, and coordinate server and client caches.

Interactive apps

Learn how to build responsive interactions with Server Functions, transitions, optimistic UI, and pending feedback.

Server Actions

How Server Actions work in Next.js, including the single-roundtrip response model, sequential dispatch, security, and caching integration.

Forms

Learn how to create forms in Next.js with React Server Actions.

Streaming

Learn how streaming works in Next.js and how to use it to progressively render UI as data becomes available.

Static Exports

Next.js enables starting as a static site or Single-Page Application (SPA), then later optionally upgrading to use features that require a server.
Edit this page on GitHub

Was this helpful?

supported.