Introduction

The source code of this site can be accessed here.

This site is built with Next js and mainly serves to act as an extension to my resume. A friend of mine was building his own blog site which inspires me to build my own portfolio site with a blog as well.

This blog will briefly talk about why I choose the Next js framework. Then goes through how I build and update content, for example this blog. After that, I will discuss how to build and deploy the site built with Next js.

Next js

I choose to use Next js for this project because Next js can be used as a static site generator (SSG), which basically indicates a tool that can generate static files instead of serving contents dynamically with a server. In other words, no servers are needed if there is a way to retrieve the static files generated by Next js. Consequently, I can host the genarated static html, javascript and other assets on a static hosting service.

Perfomance

Next provides a very smooth experience for user. SSG provides a blazing fast speed when user is accessing because the files are generated at build time, the file services can simply serve the requested files. Comparing to some frameworks that run on servers that collect data and generate file after user's request, this is a great performance improvement.

Crawable text and link

Another advantage of static site is to maximize Search engine optimization (SEO). Search engines like Google use web crawlers, which are some robot script that come to visit your site can gain some understanding about what key words, images, topics, etc. that your site contains. The search engines can later utilize the information that the web crawler gained and provide search results for their users when they are searching for certain key word.

In order for crawler to do that, the information should already be on the html file to optimize for the crawler. This is not viable for some single page applications (SPAs) because the contents are rendered in the client's side. Therefore comparing pure SPA and Next js, Next js can be optimized much better for search engines which is much more preferable.

Static site and SPA

SPA is a javascript application that although switching to many different routes and pages in the application, the browser never actually fetch new html document from server. This can provide a much better user experience that it usually has faster respond like you are using a native application on browsers.

Although I compared Next js and SPA in the last section, Next js is actually a SPA. During the initial load, the file service will respond with the static html file. After the browser received the essential files, Next js will rehydrate in client side, which means that Next js will bind the javascript React objects with the DOM in your html.

The result is that the application can benefit from both the SEO optimization and the enchanced user experience from SPA.

Content and maintainance

For most site with content, there is usually a content management system (CMS), out of which WordPress is probably the most well known. However, setting up a CMS and keeping a server is not ideal for me because I want to minimize thie cost and maintaining a system on a server will certainly add to it. Therefore I choose to use mdx with next-mdx-remote. Using this, I am able to update content on *.mdx file, and they will be later compiled into html by the library.

This provides great flexibility and good maintainability as well because we are able to modify content without directly modifying the code, while being able to comfortably update content using markdown syntax, reuse the styling and reuse some React component as well.

As an example, in my about page, I can write syntax like this:

### Contact

contact me at [pangkwunming@gmail.com](mailto:pangkwunming@gmail.com), or the following options as well.

<FollowMe col={false}/>

We can see that a combination of markdown language and React component is being used. The resulting syntax is fairly easy to modify, and the functions and component can be reused as well.

Building and serving the site

To build static site, simply by adding output: "export" in the next config file.

const nextConfig = {
    output: "export",
    distDir: "/docs",
    ...rest
}

Then simply run npx next build, Next js will handle the building of static assets.

We can see form the figure that the output directory contains all the .html files and assets. We can test serving this directory by using npx http-server "./docs" by using http-server package in local. Now the website should be available in port 8080 in your local machine. If everything works well, we can now simply serve the directory in a file server. In this case, I choose to use Github pages. Now my site is available in my github homepage at https://kwunmingpang.github.io/.

Summary

In summary, I choose to use Next js for my project because of SSG provided by Next js, in addition to the SEO optimization and enhanced user experience from SPA. I manage the content on my site using markdown files because of the maintainability and the flexibility provided by markdown templates. When the contents are updated, I build using npx next build and serve the static directory on github pages.

I hope this can be an insipration to your project as well. I plan to post more blogs about more technical details of what is not included in this page. Hope that will help other people with their projects.