Replatforming my blog to NextJS

If you've been a user of my previous blog site, you would have seen a site built with Docusaurus, deployed and hosted via CloudFlare pages.

This stack definitely served a purpose: to allow me to setup once, and be able to simply write posts as Markdown. Docusaurus handled all of the SEO requirements, metadata, tagging, etc.

Going forward, I'd like to be able to have more control over the underlying site that drives the blog. I want to be able to build and try out React components in their own dedicated pages yet keep the simplicity of Markdown blog posts.

So I'm in the process of rebuilding this site using NextJS. This site is and will continue to be a static site, and will continue to be hosted via CloudFlare Pages, but I'll outline the new stack I'm running.

Why NextJS?

So why move to NextJS if the current Docusaurus stack worked fine? NextJS has a number of features that I am personally interested in.

First, Next has great static site support. Pages are stored following a file based system, so https://jordan.mace.au/blog is quite literally just a page.tsx file inside a folder called blog in my code repository. This makes it really easy for me to create any page that I want, by simply dropping in a page.tsx file in the directory of my choosing and exporting a Page() function.

These functions can also be async, allowing me to fetch data from an API or files to be used in generating the page output. This is all handled by Next at build time.

When handling pages like specific posts (i.e. https://jordan.mace.au/blog/locally-hosted-chat-gpt) this is simply done by creating a directory for the [slug], then adding a page.tsx within that directory, and then ensuring we export a generateStaticParams() function to provide Next with the slugs to be generated on build. In my case, I'm simply loading in all the blog posts from my content directory and then providing the file names as the slugs.

Secondly, because I'm already somewhat familiar with Next, setting up a blog to suit my needs has been pretty simple. Given that this is a tech blog, I've wanted code syntax highlighting to be available, and since blog posts are rendered as MDX files, I use the react-syntax-highlighter and render that within the blog post.

For example, check out this syntax highlighted example of how I render the YAML for my docker compose file over in my Chat GPT post.

import SyntaxHighlighter from 'react-syntax-highlighter';
import { a11yDark } from 'react-syntax-highlighter/dist/esm/styles/hljs';

export const dockerYml = "YOUR-YAML-HERE"

This is an example docker compose file for LibreChat copied from [GitHub](https://github.com/danny-avila/LibreChat/blob/main/deploy-compose.yml):


<SyntaxHighlighter language="yaml" wrapLongLines wrapLines style={a11yDark}>
{dockerYml}
</SyntaxHighlighter>

And lastly, Next does a lot of optimization, both minification of JS and CSS as well as image and font optimization.

The only thing I've personally done to optimize images is compress them to webp format. Next handles the rest.

Next also has easy to use metadata features. Exporting the metadata for a blog post for example is simply done as shown below.

export async function generateMetadata(
  { params }: { params: Promise<{ slug: string }> }
): Promise<Metadata> {
  const slug = (await params).slug
  const posts = await getPostsWithMetadata();
  const thisPost = posts.find(x => x.slug === slug);

  return {
    title: thisPost?.title ?? "Blog post",
    keywords: thisPost?.keywords ?? [],
  }
}

So in the above snippet, this is the generateMetadata function for the blog/[slug]/page.tsx file, so this function is called for each blog post page to be generated.

The returned object is used by Next to generate the <title> and <meta name="keywords"> tags. You can go further and handle the author, description and other tags but I handle them elsewhere in the codebase as they don't change between routes.

These optimizations lead to a great Core Web Vitals score.

Now, you may be wondering why the Best Practices section is only 81. This is due to one of CloudFlare's APIs, not something caused by Next.

With Performance, Accessability and SEO at 100 - Next handles everything I need for my use case of a static blog site.

Hopefully Cloudflare addresses the deprecated API usage soon 🙏

The current stack

Currently, blog posts are written in MDX files, using react-syntax-highlighter for code highlighting as outlined above.

I've recently added Material UI but am not 100% certain I will continue using it. I'm keeping an eye out for component libraries.

The site is still deployed to CF Pages because their network is ⚡ incredibly fast ⚡, and they can handle the caching, anti-DDoS, TLS, etc.

Interestingly, while CloudFlare Pages does have Web Analytics enabled for this site, I've added Google Analytics and have noticed inconsistencies between the two. Without looking too far into it, I am assuming Google Analytics is more accurate.

I've written page files to handle blog posts, so /blog being the directory, /blog/[slug] being specific pages, and I'm also adding tags to posts.

For example, you can go to https://jordan.mace.au/blog/tags/react to only see posts with that tag.

I'm intermittently using styled-components, mainly for the top navigation bar of the site.

The reason for this is you'll notice I currently display two variants of the nav bar based on whether or not the user is on the home page.

So I'm simply using a styled div that handles an isHome prop. I also use it to handle dark mode support.

const StyledDiv = styled.div<{ $isHome: boolean }>`
  background: e=>e.$isHome?"rgba(0, 0, 0, 0.5)":"none";

  @media (prefers-color-scheme: light) {
    color: e=>e.$isHome?"white":"black";
  }
`

Conclusion

Overall, I'm enjoying Next.

It does a great job at optimizing the static assets, it's easy to use, and they have fantastic docs available.

I have a great Core Web Vital score, I can extend the site as needed and I can use Client Rendering for specific components that need it.

For the use case of what is essentially a tech blog with a few custom pages thrown in, I don't see myself switching any time soon.