Next.js: Architecture of a simple tagging system

Published on: Sun Jan 22 2023




This site that I am using to host all my articles is using Next.js or specifically Vercel.

The approach that I took to hosting this site is to keep it as simple as possible.

This is because I rather not have the hassle to the infrastructure burden, so everything is to be as simple as possible.

I recently re-visited the usability of my site, and I realized a lot of my articles are hidden behind the “Writing” link.

It was difficult to know what articles were available or even find relevant articles.

So, this led me explore options, and one of the ways that many blogs (ie Wordpress sites) do this is via a tagging system.

This article will discuss the architecture behind how to build a simple one using Next.js (with Vercel).

The Existing Site

Before making any adjustments, let’s take a look at how my site generate the articles.

Like I said, my site is very simple with no external integrations, no CMS, no Database.

It’s just using Markdown.

How does the markdown get on the site ?

  1. The utility will read the markdown (*.md extension)

  2. Extract and transform the metadata from it

  3. Next.js will render all of that information (using getStaticProps )

Existing workflow for generating articles
Existing workflow for generating articles

Ideally, for simplicity, I wanted to keep this same workflow and layer on a tagging system.

(Because I am lazy 😂)

Let’s talk about how we can go about to doing that.

💡 Note:

My site uses Static Site Generation (SSG) because everything comes from the markdown, and I don’t deploy that often.

Occasionally, I do deploy for edits or release new articles.


Since this is my personal site, the aim is to optimize for simplicity.

This means one of key goals for me is to have the least amount of infrastructure burden.

The requirements:

  • Keep it as simple & minimal as possible

  • Maintain the existing flow (Pagination etc)

  • No external integration (ie no DB, no CMS)

  • No Infrastructure burden

Even though this may not be the “best practice”, it made sense for me given my constraints.

The Tagging System Design

Now comes the idea.

The idea that I had in mind was an API that returns articles based on the tag provided in the query string.

Let’s go through the components in more detail.

1. A Next.js API endpoint

This will return the data based on the tag query in the URL.

For Example:

  • /writing?tag=aws - This would return all articles that were tagged with "AWS"
Next.js: Tagging system with API server
Next.js: Tagging system with API server

Here is an example of the JSON response.

JSON response (sample):

  "entries": [],
  "pagination": {
    "total": 4

This api will read the JSON data directly from the filesystem.

Vercel actually supports this but you do need to configure it 👇.

💡 Note:

If you want to support reading from the filesystem, you need to turn on nftTracing on Next.js config.

This allows for “Output File Tracing”, and Next.js will put all the files that need to be read on the production server.

Now comes the question of: How do we get this data or where does it come from ?

2. Pre-generated data

In my website, I already have an existing utility for parsing these articles in markdown.

So, to get these new JSON data, I just needed to write another script to aggregate the articles into categories.

I would need to pre-generate the data because we need it available in production when our API reads a particular file.

The file convention: {name-of-the-tag}-tag.json

Pre-generating tagging data ahead of time
Pre-generating tagging data ahead of time

3. Manifest file

As part of the processing (using the script), it will also generate a manifest file which will contain the following:

  • The tags that are used

  • The number of articles in each tag


  "astro": 6,
  "frontend": 7,
  "aws": 35,
  "cloudfront": 11,
  "cdn": 16,
  "edge": 4,
  "aws-lambda": 8,
  "terraform": 11,
  "ci-cd": 5,
  "http-caching": 3,
  "build-system": 2,
  "dev-ops": 7,
  "open-id-connect": 3,
  "postgre-sql": 7,
  "aws-ecs": 7,
  "next-js": 2

On the UI, this is the file that I use to render the different tags available on the site.

The UI

Here is what the resulting UI for the tagging system looks like.

Tagging system UI
Tagging system UI


And... That’s it!

This is a simplified tagging system built with Next.js using Vercel.

Again, this may not be the “best practice” but given the requirements that I had, it worked for me.

There is value in adding constraints, it tends to lead to more creative solutions!

What do you think ? Got any ideas on a different way to build something like this ?

Reach out, and Let me know! I’d love to hear it!

Also, if you learned something new, please share this article with a friend or co-worker 🙏❤️! (Thanks!)

Enjoy the content ?

Then consider signing up to get notified when new content arrives!

Jerry Chang 2023. All rights reserved.