Migrated my blog from Gatsby to Next.js

6 December 2022
A migration checklist

My blog were initially created with Gastsby and it has been easy to maintain and writing new blog posts from time to time. Until recently where I am no longer able to publish new blog post unless I upgrade my project due to dependencies issues. My choice was to migrate to Next.js because of my experience with other projects that I had set up, all using Next.js. Below are some of the issues I faced and I decided to make a checklist out for it.

Migration Checklist

  1. Add react, react-dom and next packages

  2. Add dev dependencies autoprefixer and postcss

  3. Update scripts

  "dev": "next dev -p 8000",
  "build": "next build",
  "start": "next start",
  1. Add next.config.js and postcss.config.js

  2. Rename directory /static to /public

  3. Move /templates/* to respective routes. Adapt to dynamic routes.

  4. Remove graphql query in template files

  5. Use getStaticProps to provide props previously provided by graphql.

  6. Use getStaticPaths to generate predefined blog post routes.

  7. Use next/head to replace react-helmet for header metadata.

  8. Add react-markdown, gray-matter and highlight.js for markdown content.

  9. For deployment, changes needed in next.config.js.

module.exports = {
  webpack: (config, { isServer }) => {
        test: /\.md$/,
        use: 'raw-loader'

    return config
  typescript: {
    ignoreBuildErrors: true,
  images: {
    unoptimized: true,
  trailingSlash: true,

trailingSlash is important for Next.js to redirect path without ending /. Otherwise, the page will be redirected to /404

unoptimized is set to true because the blog will be exported, and exported build will not enjoy the benefit of optimized image out of the box.

  1. For deployment to Github pages, add .nojekyll to the /out directory after build. So that Github pages will recognize _next directory and the content inside.
  "deploy": "next build && next export && touch out/.nojekyll && gh-pages -t -d out"

The -t flag is important to push the changes on .nojekyll.

That's it!