I have tried out Next.js to build my personal blog so you don't have to

Gatsby

Initially the idea of Gatsby was very promising: pick a starter, a theme, some plugins and supply the project with Markdown files representing your blog posts. I got it running pretty quickly which is always pleasant when trying out a new technology for the first time. However my experience when trying to customize certain elements of the page was really bad.

First, I wanted to slightly change the styling and adjust some typography variables. There were multiple of them spread across the starter, the theme and the generated boilerplate and I got lost where to configure those.

The next change request I had was to adjust the templates slightly - basically I wanted to replace some elements in the footer. Eventually I figured out, that in order to replace the footer originally located in node_modules/theme/dir/footer.mdx I had to create a duplicate file at theme/dir/footer.mdx with custom content to override the original content. This replaces the previous footer supplied by the theme, so I had to copy and paste the original content making it nigh impossible to keep my changed templates in sync with upstream changes.

On top of that the styles used throughout the template relied on some helper functions I was not familiar with to compute responsive values, presumable mapping to rem units - nevertheless it wasn’t really obvious where these come from. Furthermore there were inline styles all over the place rather than proper SCSS, not even CSS-in-JS, just plain inline styles.

Ultimately what really left me speechless is the required use of GraphQL to specify which data to query for pages and components causing a high cognitive load for even simple tasks such as computing the estimated reading time of a post. In my opinion another unnecessary layer of complexity that requires developers new to GraphQL to get acquainted with it, figure out which data is actually queryable and then to define their respective queries. More often than not I had issues figuring out which plugins do add further queryable data and where this data is actually stored.

It is highly likely that I made a severe mistake by trying to leverage the ecosystem rather than starting from scratch with much more control. Alas, this seemed like the most common way newcomers would approach a first project with Gatsby that I wanted to mimick.

Even though I am complaining a lot about my experience I have to point out that the Gatsby community has a rich ecosystem of plugins. For most common use cases there is a plugin that you can register in the configuration which will automatically do its job. This includes plugins for offline capabilities, responsive images, search engine optimization improvements, automated syntax-highlighting of code in posts etc. Albeit useful I personally prefer to have more control over plugins and how they operate. This is most likely one of the reasons starting out with an already running set of starters caused so many headaches.

Next.js

Unlike Gatsby the development with Next.js felt like a breeze and pretty much everything came together organically. I started from scratch with a boostrapped project using create-next-app and was quickly able to define my components. For styling it is possible to use CSS-in-JS or SCSS which are supported right out of the box. Alternatively you can just install any other solution such as Styled Components or anything else if you have other preferences. No particular styling approach has really impressed me thus I always stick to classic SCSS files using the BEM naming convention in all of my projects.

Out-of-the-box a Next.js application, even though it has no classic entrypoint like create-react-app, behaves just like any other React-powered application. Features like server-side rendering or static site generation are strictly opt-in and enabled by the existance of methods with special names in corresponding files. Therefore my workflow when developing the blog was initially pretty much the same as with any classic React-powered application. The only significant difference was that files located under pages/* are mapped to routes and these files can have special names to make Next.js aware that they are dynamic based on query parameters or the URL itself such as [slug].tsx indicating the page expects one query parameter which is called slug. A page file located in pages/foo/bar.tsx would be automatically mapped to /foo/bar without the need to configure any routing options at all.

After having finished all components with mocked data it was about time to introduce static site generation capabilities. I was completely free to choose how to supply the static data - be it from the file system, via API calls during build-time or by connecting to a database. For the blog I decided to store the blog posts in Markdown files that are read and parsed during build-time to produce proper HTML output.

Index page

My index page is located under pages/index.tsx which is mapped automatically to the route /. Each page component has to be a default export in one of the files located under pages/*.

In order to enable such a page to be statically generated, there must be a co-located named export of an async method called getStaticProps. During build-time this method is invoked locally in a Node.js environment to supply the page with props, hence you can access the modules fs or path to read local files, something that wouldn’t be possible in a browser environment.

This is the first time Next.js introduces us to mixing code that is only available and used during build-time and code that is only available during runtime in the very same file - therefore the boundaries between a browser environment and a Node environment vanish to increase the developer experience.

At the time of writing this post the index page of my blog looks as follows:

import { Page } from 'components/page';
import { Post } from 'components/post';
import { Seo } from 'components/seo';
import { getAllPosts } from 'lib/posts';
import type { InferGetStaticPropsType } from 'next';

const Index = ({ posts }: InferGetStaticPropsType<typeof getStaticProps>) => (
  <Page index>
    <Seo />
    {posts.map(({ date, slug, title, description, category, readingTime }) => (
      <Post
        key={slug}
        date={date}
        title={title}
        description={description}
        slug={slug}
        readingTime={readingTime}
        category={category}
      />
    ))}
  </Page>
);

export default Index;

export const getStaticProps = async () => ({
  props: {
    posts: await getAllPosts(),
  },
});

As you can see the page does nothing else than render a bunch of post previews based on the supplied posts via the props. The type InferGetStaticPropsType is Typescript sugar to infer the prop types via the return value of the getStaticProps method without the need to define them explicitly. However this approach is just my personal nuance as I prefer to let Typescript infer types whenever reasonable and helpful.

Finally getStaticProps itself allows us to define which props are used to pre-render the index page. In this case it is just a custom method getAllPosts which internally parses all Markdown files in my posts folder and returns their contents and metadata defined in their front matter. However the implementation details of this method aren’t specific to Next.js as they are classic Node.js function calls.

Post page

Now that we have an index page listing all available posts, we need another page to render single posts. For my blog I decided to route them directly as /:slug without any prefix in the URL to improve search engine optimization. This route is achieved by having the file located under pages/[slug].tsx, a unique name that Next.js needs to deduce it has a dynamic parameter we refer to as slug.

Pages that have multiple variants based on the URL or query parameters require a second special async method to be exported called getStaticPaths. This method is invoked during build-time and it has to return all paths that will be available during runtime. For each of those paths a variant of the page is pre-rendered using the getStaticProps method with the current path as an argument.

A shortened version of this page located under pages/[slug].tsx is this:

import { getAllPosts } from 'lib/posts';
import type {
  GetStaticPaths,
  GetStaticProps,
  InferGetStaticPropsType,
} from 'next';

const Article = ({
  currentPost,
  previousLink,
  nextLink,
}: InferGetStaticPropsType<typeof getStaticProps>) => (
  {/* ... */}
);

export default Article;

export const getStaticPaths: GetStaticPaths = async () => ({
  paths: (await getAllPosts()).map(({ slug }) => ({ params: { slug } })),
  fallback: false,
});

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const allPosts = await getAllPosts();
  const currentPostId = allPosts.findIndex(({ slug }) => slug === params?.slug);
  // ... previousLink and nextLink are deduced here
  return {
    props: {
      currentPost: allPosts[currentPostId],
      // ... previousLink and nextLink
    },
  };
};

As described previously getStaticPaths is invoked during build-time and will return slugs for all available posts to define all possible paths that are valid for /:slug. All other paths that are requested during runtime will yield a 404 error and are routed to a 404 page that is created by default.

Another unique feature is a hybrid mode using the special fallback option returned by getStaticPaths. It is possible to pre-render some paths during build-time and paths for which fallback equals true during runtime on the server when it is requested for the very first time. This feature is especially useful if you end up having many thousands of pages and pre-rendering them all during build-time is no longer a feasible option which can happen in e-commerce for instance.

Finally, getStaticProps has access during build-time (or even during runtime if fallback equals true) to the respective params.slug variable that takes on the value of each returned path by getStaticPaths. Using this you can fetch the necessary props for pre-rendering a specific variant of the page based on the parameter.

Server-side rendering

Should you need to update certain pages so regularly that pre-rendering them during build-time is not a viable option the async method getServerSideProps instead of the getStaticProps is a drop-in replacement to enable server-side rendering for a particular page. This way the HTML content is re-rendered for every single request.

Lambdas

A feature that really surprised me is the possibility to define custom lambdas co-located with pages. By doing so the application will be a hybrid and expose those endpoints via /api/* for each lambda defined in the pages/api folder. Assume you have the following lambda located as pages/api/user/name.ts:

import type { NextApiRequest, NextApiResponse } from 'next';

export default (req: NextApiRequest, res: NextApiResponse) => {
  res.status(200).json({ name: 'John Doe' });
};

Requesting /api/user/name from within the frontend, for instance in a getServerSideProps method or as the handler of an event, will invoke the lambda and return the object { name: 'John Doe' } with status code 200. A possible use case is the registration for a newsletter or an authentication for users.

This feature is awesome as it allows you to write some backend code without having to create an entire backend yourself. Basically you’re able to build a true fullstack application that can leverage being co-located with the actual frontend code as they can share code, types and many more.