Building an Offline-First Next.js 15 App with App Router and Dynamic Routes

[TarekAbdelfatah]

Hello everyone,

I'm currently working on a Next.js 15 application using the App Router, and I'm facing a significant challenge in making the entire application work in offline mode, especially with Dynamic Routes.

The core idea is this:
I have a dynamic page at doc/[id]/page.js. I want a user to be able to visit any link like doc/1, doc/2, or doc/12345 even if they've never visited it before and are currently offline.

The Problem:
I cannot statically cache millions of possible pages. The approach I'm considering is to have the app function as an SPA (Single Page Application) when offline. This would involve:

Pre-caching the essential application assets (JS and CSS files).

When a user requests an uncached URL while offline, the Service Worker would serve a single fallback HTML page.

This fallback page would then load the necessary Client Components from the cache to render the data, perhaps from Local Storage.

I've been trying to implement this using Serwist (formerly Workbox) with the Next.js App Router, but I'm running into some difficulties.

Specific questions I need help with:

Is this the correct and recommended approach for handling dynamic routes in an offline-first Next.js app?

How can I properly configure Serwist to work with the Next.js App Router and handle this exact scenario?

Are there any practical examples or code snippets that demonstrate this implementation? (Specifically, the configurations for next.config.ts and the Serwist sw.ts file).

and I can't find a clear, official guide on how to set up a fallback offline page. The examples I've found online haven't worked for me, and I'm unsure if I'm missing a core concept or if the documentation is simply lacking for this specific use case.

[Anipaleja]

Hi @TarekAbdelfatah,

You’re on the right track thinking about SPA-like fallback for offline support with dynamic routes in Next.js 15’s App Router, but this use case is indeed tricky because static pre-caching all dynamic pages is impossible and Next.js’ default static optimizations don’t fully cover this.

1. Conceptual approach: Offline-first with fallback page

• Since you cannot pre-cache all dynamic routes (e.g., millions of doc/[id] pages), the typical pattern is:

  • Pre-cache static assets (JS, CSS, fonts) and the shell HTML (the SPA entry point).
  • For any uncached dynamic URL requested offline, serve a fallback index.html (or a special offline HTML page).
  • That fallback page boots your React app, which then uses client-side routing and cached/local data to render the page dynamically.

2. Service Worker (Serwist/Workbox) configuration

• Configure your service worker to:

  • Cache all static assets during install (JS, CSS, etc).
  • Use a NetworkFirst or StaleWhileRevalidate strategy for API/data requests, if possible.
  • For navigation requests (requests for pages), implement a catch fallback to your offline shell page.

Here’s a sketch for sw.ts with Workbox-like logic:

import { precacheAndRoute, createHandlerBoundToURL } from 'workbox-precaching';
import { registerRoute, NavigationRoute } from 'workbox-routing';

// Precache files injected by build process
precacheAndRoute(self.__WB_MANIFEST || []);

// SPA fallback to index.html for navigation requests
const handler = createHandlerBoundToURL('/index.html');

const navigationRoute = new NavigationRoute(handler, {
  denylist: [/^\/_next\//, /^\/api\//], // Don't fallback API or static assets requests
});

registerRoute(navigationRoute);

// Optionally add runtime caching for API calls here

Make sure index.html is in the precache manifest.

3. Next.js config (next.config.js or .ts)

• You may want to customize the output to ensure your SPA shell (index.html) is available for offline fallback.
• Using output: 'export' or custom serverless config could help generate a fallback page.
• However, with App Router, make sure to handle static fallback properly, which can be tricky since Next.js 13+ focuses on SSR/ISR.

There’s no official built-in Next.js config for Service Worker integration yet, so you typically add your custom sw.ts and integrate it manually or with plugins like next-pwa (which is working on App Router support).

4. Data storage and hydration

• Since users may request dynamic pages offline they haven’t visited before, you’ll need a way to hydrate those pages client-side:

  • Cache data responses (e.g., via IndexedDB or LocalStorage) when online.
  • Your app’s client components should read from this cache and render accordingly.
  • This requires custom logic in your React components to detect offline mode and fallback to cached data.

5. Practical references

• Workbox Recipes - Offline Fallback - general pattern for SPA fallback.
• next-pwa plugin-check if their latest version supports App Router and dynamic fallback.
• Community examples for Next.js 13+ offline apps are sparse, but this thread helps:
  Can you do a fetch post in 13 while keeping header tokens private #42273

Summary

• Your approach is valid: pre-cache static assets + fallback HTML for navigation requests.
• Implement Service Worker to serve your fallback shell for uncached dynamic routes offline.
• Manage data caching client-side with IndexedDB/LocalStorage for offline hydration.
• Watch Next.js and PWA plugin updates for better App Router support.

Feel free to share your config and SW code here if you want feedback!

[TarekAbdelfatah]

Thanks for the replay, I will apply this solution and share my feedback soon

[TarekAbdelfatah]

I gave this a try, but it didn’t work.

[icyJoseph]

Hi,

In our PWA guide we reference this repository for offline support:

• https://nextjs.org/docs/app/guides/progressive-web-apps
• https://github.com/serwist/serwist/tree/main/examples/next-basic

I've found some discussions on that repo though about Offline Mode Support, serwist/serwist#205, and people struggling it to get it to work.

One of the suggestions seems to point to using this https://nextjs.org/docs/app/getting-started/linking-and-navigating#native-history-api which is basically shallow rendering for your app, but then useParams doesn't really work - but usePathname and useSearchParams do work.

[TarekAbdelfatah]

Hi @icyJoseph,

Thanks for your support — your URLs have been very helpful for me.
I found a discussion here: serwist/serwist#205 (comment) that matches my issue. I improved the approach to fit my case, and I’ll share my code in a reply here along with the GitHub URL.

[TarekAbdelfatah]

Based on this discussion, I found a solution to my case, but it needed some improvement.
my code here
https://github.com/TarekAbdelfatah/Pwa-Offline-first-Nextjs-dynamicRoutes.git

First, you should make your application a PWA and use Serwist:

• https://nextjs.org/docs/app/guides/progressive-web-apps
• https://github.com/serwist/serwist/tree/main/examples/next-basic

My setup is as follows:

next.config.ts

import withSerwistInit from '@serwist/next';

const withSerwist = withSerwistInit({
  swSrc: 'src/app/sw.ts',
   
  swDest: "public/sw.js",
  cacheOnNavigation: true,
  additionalPrecacheEntries: [{ url: "/offline", revision: '11' },
    { url: "/offlinedoc", revision: '12' }],
});

export default withSerwist({
  
});

sw.ts

import { defaultCache } from "@serwist/next/worker"
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist"
import { Serwist } from "serwist"

// This declares the value of `injectionPoint` to TypeScript.
// `injectionPoint` is the string that will be replaced by the
// actual precache manifest. By default, this string is set to
// `"self.__SW_MANIFEST"`.
declare global {
    interface WorkerGlobalScope extends SerwistGlobalConfig {
        __SW_MANIFEST: (PrecacheEntry | string)[] | undefined
    }
}

declare const self: ServiceWorkerGlobalScope

const serwist = new Serwist({
    precacheEntries: self.__SW_MANIFEST,
    skipWaiting: true,
    clientsClaim: true,
    navigationPreload: true,
    disableDevLogs: true,
    precacheOptions: {
        cleanupOutdatedCaches: true,
        ignoreURLParametersMatching: [/.*/],
    },
    fallbacks: {
      entries: [
        {
          url: "/offlinedoc",
          matcher({ request }) {
            const url = new URL(request.url);
            return request.destination === "document" && url.pathname.startsWith("/doc");
          },
        },
 
        {
          url: "/offline",
          matcher({ request }) {
           
            return request.destination === "document";
          },
        },
      ],
    },
    
    runtimeCaching: defaultCache,
})

const urlsToCache = ["/","/offlinedoc", "/~offline"] as const

self.addEventListener("install", (event) => {
    event.waitUntil(
        Promise.all(
            urlsToCache.map((entry) => {
                const request = serwist.handleRequest({
                    request: new Request(entry),
                    event,
                })
                return request
            }),
        ),
    )
})

serwist.addEventListeners()

I created an offlinedoc page to serve as a fallback when navigating offline to my doc page.
Note that my doc page is a dynamic route, so I cannot cache it offline.

Therefore, I repeated the logic of doc in offlinedoc. You can also create a single component and use it in both pages, but make it accept an ID as a parameter:

When online, get it from the URL.

When offline, extract it from the path.

My doc page is located at:

my doc page found in src\app\doc\[id]\page.tsx

'use client';

import { useEffect, useState } from 'react';
import { useRouter } from 'next/navigation';

export default function Doc() {
  const [id, setId] = useState('...');
  const router = useRouter();

  useEffect(() => {
    const parts = location.pathname.split('/').filter(Boolean);
    setId(parts[parts.length - 1] || '—');
  }, []);

  return (
    <div className="p-8">
      <div> رقم الوثيقة   DOC ID : {id}</div>
      <button
        onClick={() => router.push('/')}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 transition"
      >
       عودة للصفحة الرئيسية ( back to home)
      </button>
    </div>
  );
}

the offlinedoc code

'use client';

import { useEffect, useState } from 'react';
import { useRouter } from 'next/navigation';

export default function Doc() {
  const [id, setId] = useState('...');
  const router = useRouter();

  useEffect(() => {
    const parts = location.pathname.split('/').filter(Boolean);
    setId(parts[parts.length - 1] || '—');
  }, []);

  return (
    <div className="p-8">
      <div>   OFFLINE  DOC ID : {id}</div>
      <button
        onClick={() => router.push('/')}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 transition"
      >
        back to home
      </button>
    </div>
  );
}

and my home page is

'use client';

import { useRouter } from "next/navigation";
import { useState } from "react";

export default function Home() {
  const router = useRouter();
  const [docId, setDocId] = useState("");

  const handleGo = () => {
    if (docId.trim() !== "") {
      router.push(`/doc/${docId.trim()}`);
    }
  };

  return (
    <div className="font-sans grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20">
      <input
        type="text"
        placeholder="  رقم الوثيقه  DOC ID"
        value={docId}
        onChange={(e) => setDocId(e.target.value)}
        className="border border-gray-400 rounded px-4 py-2 text-center focus:outline-none focus:ring-2 focus:ring-blue-500"
      />
      <button
        onClick={handleGo}
        className="bg-blue-600 text-white px-6 py-2 rounded hover:bg-blue-700 transition"
      >
       اذهب لصفحة العرض ( Go To Document )
      </button>
    </div>
  );
}

[icyJoseph]

I'll try to come back to this one after I finish up other work I have, but if you have some feedback on things that should've been, or would have been nice to have in the PWA docs in Next.js, I'd appreciate if you could just sum up short some bullet points.