Site Rebuild

2025: The NextJS iteration

5^th August 2025

2 min read

With the sense of inevitability 2025 marks time for a rebuild. As is tradition, its an opportunity to learn a new framework and to keep on-top of technical debt. My Gatsby site had grown a bit unloved and outdated (v3), when I lifted the lid it turned out to be a major re-work to upgrade from v3 to v5, so figured; let's try something different!

Core principles

Retain static generated site approach - as it lends well to my blog content
Keep hosting as-is on AWS as its cheap as chips
Ensure all the meta and OG data capability is maintained for SEO
Shift from JS/ES6 to Typescript
Lift and shift of content, structure and functionality, with minor tweaks. Specifically;Content authored as markdown and use of MDX

Key Observations

1 : Page router vs App router

2x different ways to implement pages and content. I selected the app router as:

Concensus that app is the more enduring router with page router likely to be deprecated
Better templating options and extensions

2 : App router

App router works on a folder + key file basis where the folder represents the path eg /stuff and the key files are a minimum of a page.js|jsx|md|mdx|ts|tsx file - typically where the page content resides, and an optional layout.js|jsx|md|mdx|ts|tsx file which is used to handle formatting and scaffolding. Typically at least one page and layout file needs to exist in the /app root folder (essentially the /index.html).

However, you can include layout files in each path as well as the route to help build up global page scaffolding vs more sectional.

In my content I've used the page.mdx to contain pure markdown and a couple of MDX components. The layout.tsx file in each page handles the metaData.

Example of this is the /hardware page, which comprises of the markdown content page.mdx:

# Hardware
Hardware hobbyist and noodler, I like designing and building stuff, sometimes useful, sometimes not. Sometimes working, sometimes not.

- Modular synth components and audio processing
- Arduino / ATTiny / ATMega
- RPi
- IoT
- 4000 series / TTL stuff
- Custom PCB design

/app/hardware/page.mdx

.. and the layout.tsx file to provide scaffolding and related list of 'hardware' blogs:

import { BlogList } from "components/Blog/BlogList";
import { Container, Main, SideBar } from "components/Layout/Container";
import { metaData } from "components/metaData";

export const metadata = metaData({
	title: "Hardware",
	description: "Hardware",
	url: "/hardware",
});

export default function Layout({ children }) {
	return (
		<Container>
			<Main>{children}</Main>
			<SideBar>
				<BlogList title="Blogs" category="hardware" limit={5} />
			</SideBar>
		</Container>
	);
}

/app/hardware/layout.tsx

The root level layout.tsx handles the overall, global page structure (head, header and footer)

3 : Gotchas?

Nothing serious, just a few approaches that were 'different':

Gatsby does a nice job of presenting frontmatter and data into pages via its graph interface. With nextjs, it was a bit more 'hand-rolled' - building helper classes to enumerate blog markdown files, read the front-matter and present as a JSON object to build up blog lists. Plus leveraging the generateStaticParams to build up the range of parameter calls to the pages (ie passing in the slug for each blog to retrieve it by).
Image optimisation - more involved than gatsby. Not worked out (yet) how to do this easily. Gatsby was pretty effortless.

Core principles

Key Observations

1 : Page router vs App router

2 : App router

3 : Gotchas?

References

More posts in this series: