A hands-on SSG implementation using the Nextjs App router

Today, I attempted to implement the generation of static pages using Next.js App Router for my site. I encountered some notable challenges that are important to document.

First implementation

My site uses create-t3-app for development. Here's the code for the article details page that supports static generation:

typescript
Copy code
// src/app/articles/[slug]/page.tsx
// Generates static parameters for all articles at build time.
export async function generateStaticParams() { 
  const posts = await api.article.getAllArticlesWithoutContent();
  return posts.map((post) => ({
    slug: post.slug,
  }));
}
const Page = async ({ params }: { params: { slug: string } }) => {
  const article = await api.article.getArticleBySlug({
    slug: params.slug,
    admin: false,
  });
  if (!article) return notFound();
  return (
     <ArticlePage article={article!} />
  );
};
export default Page;

and the the outline of ArticlePage component looks like this:

typescript
Copy code
"use client";
// 📌 A component to render article markdown content
const MarkdownContent:FC<{ content:string }> = ({ content }:{ content:string }) => {
   // render markdown content
}
// 📌 A component to display current viewed number
const ArticleViewCounter:FC<{ articleSlug:string }> = () => {
  const [count, query] = api.article.getArticleViewCount.useSuspenseQuery({
    slug: articleSlug,
  });
  return (
      <span className="ml-3 text-sm">Views: {count}</span>
  );
}
const ArticlePage:FC<{article:Article}>= ({ article }) => {
   return (
      <main>
        <Suspense
           fallback={
            <span className="ml-3 flex items-center text-sm">
                Views:
                 <Skeleton className=" ml-1 inline-block h-4 w-12" />
            </span>
            }
         >
           <ArticleViewCounter articleSlug={article.slug} />
         </Suspense>
         <MarkdownContent content={article.content}/>
      </main>
   )
}

From the above code, the concept is simple: the markdown content of the article can be statically generated, while the view counter for the article should be dynamically updated

Issue 1 - useSuspenseQuery

One of the issues I bumped into was using React Query‘ s `useSuspenseQuery` api here:

typescript
Copy code
// 📌 A component to display current viewed number
const ArticleViewCounter:FC<{ articleSlug:string }> = () => {
  // 📌📌📌 
  const [count, query] = api.article.getArticleViewCount.useSuspenseQuery({
    slug: articleSlug,
  });
  return (
      <span className="ml-3 text-sm">Views: {count}</span>
  );
}

The reason why I'm using this API is that I like the concept of 'Render-as-you-fetch.' This feature allows you to utilize the suspense feature to render your components while data is being fetched. However, the task was not simple for me. When I tried to generate the article page after running next build, an error was raised.

The benefits of using this API are that it allows you to utilize the suspense feature to render your components while data is being fetched. However, the task was not simple for me. When I tried to generate the article page after running next build, an error was raised.

text
Copy code
 article.getArticleViewCount  { input: { slug: 'test-slug' },
 result: [TRPCClientError]: fetch failed

It's clear from this error that Next.js tries to perform a data fetch with useSuspenseQuery during the static page build. However, our data backend isn't ready at this stage since this is a full-stack project, not separated into front end and back end. This is the reason the error occurs.

Solution: unstable_noStore()

The solution to this challenge is clear-cut: configure Next.js to opt out of fetching data in this component during the static page build stage.

I experimented with unstable_noStore, which declaratively opts out of static rendering and indicates that a particular component should not be cached.

typescript
Copy code
// A component to display the current viewed number
const ArticleViewCounter: FC<{ articleSlug: string }> = () => {
  // 📌
  unstable_noStore();
  const [count, query] = api.article.getArticleViewCount.useSuspenseQuery({
    slug: articleSlug,
  });
  return (
    <span className="ml-3 text-sm">Views: {count}</span>
  );
}

Now, the article page can be successfully statically generated at build time!

Issue 2 - Vercel CDN cache miss

One reason I implemented SSG for my article pages is that I prefer super fast, CDN-delivered static pages. However, when I checked the response header of my page, the cache headers always came back as x-vercel-cache: MISS.

After conducting some code research, I found the following implementation to utilize Vercel's CDN cache functionality after performing Static Site Generation (SSG):

typescript
Copy code
// force static pages
// 📌 for more info: https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic
export const dynamic = "force-static";
// CDN cache currently only works on nodejs runtime
// This is also a default config
export const runtime = "nodejs";
export async function generateStaticParams() {
  return (await getPostSlugs()).map((slug) => ({ slug: slug }));
}
interface PageProps {
  params: { slug: string };
}
export default async function Page({ params }: PageProps) {
  const data = await getArticle(params.slug);
  return <div>{JSON.stringify({data})}</div>;
}

The key change is export const dynamic = "force-static", but after adding this to my code, the same error occurred:

text
Copy code
 article.getArticleViewCount  { input: { slug: 'test-slug' },
 result: [TRPCClientError]: fetch failed

Since 'force-static' forces static rendering and attempts to cache the page's data, it also causes unstable_noStore to opt out. This can be quite frustrating. 😞

The challenge continues...

For a moment, I suddenly remembered a quote from the Nextjs documentation:

Use Static Generation with Client-side data fetching: You can skip pre-rendering some parts of a page and then use client-side JavaScript to populate them.

A change is required to replace useSuspenseQuery to skip the pre-rendering of the ArticleViewCounter component.

typescript
Copy code
// A component to display the current viewed number
const ArticleViewCounter: FC<{ articleSlug: string }> = () => {
  // unstable_noStore(); not needed here, since this is a client-side code running
  // useQuery is fetching data on the client side
  const count = api.article.getArticleViewCount.useQuery({
    slug: articleSlug,
  });
  return (
    <span className="ml-3 text-sm">Views: {count.data}</span>
  );
}

Finally, the Vercel CDN is cached with x-vercel-cache: HIT.

Recap

In this post, I recorded a few issues I encountered when using the Nextjs App Router SSG. Here are the main takeaways:

1. Static page generation: I described how to use the generateStaticParams function to generate static parameters for articles at build time, thus allowing Next.js to create static pages for each article.

2. Handling Dynamic Data Fetching: When I use useSuspenseQuery, an issue arose where data fetching during the static page build led to errors. To resolve this, I used the unstable_noStore() function to opt out of fetching data during the static page build.

3. Client-Side Data Fetching: Finally, I chose client-side data fetching for dynamic parts of the page and enforced static generation for the entire article page. This allowed for successful static generation at build time, while ensuring dynamic data could still be fetched and displayed correctly on the client side. What's more, I can also benefit from the power of CDN.

By choosing between static generation and client-side data acquisition in different component scenarios. I achieved a balance between the performance benefits of SSG and the need for up-to-date dynamic data. This also made effective use of Vercel's CDN caching, resulting in faster page loads with x-vercel-cache: HIT.