{/* EXCERPT */} # Introduction Next.JS is a server-side rendering framework for React that allows you to build a complete, full-stack application with React and Server component. GatsbyJS first started as a static site generator but has evolved into a full-fledged framework for building web applications with React. Specific to blogs, both are trusted and used by many React developers to build their personal blogs. Since both frameworks are built on top of React, they share a huge ecosystem of libraries and tools that help you build your React apps, from styling, state management, UI blocks to testing. However, NextJS focuses on server-side rendering, which means you can use native NodeJS APIs and libraries to fetch data and render your posts. GatsbyJS, on the other hand, uses GraphQL and its plugin system to achieve the same thing. Based on those differences, this article will help you decide which one is the best fit for your needs. # Criteria To compare NextJS and GatsbyJS, we will use the following criteria: - **Setup**: How easy it is to set up a new project with both frameworks. - **TypeScript-friendly**: How easy it is to use TypeScript with both frameworks. - **UI and styling**: How easy both frameworks integrate with major UI tools such as TailwindCSS and ShadCN. - **Post rendering**: How both frameworks fetch data and render posts using MDX. - **Server-side features (minimal)**: How both frameworks support server-side features such as query strings, and pagination. - **SEO**: How SEO is supported in both frameworks. - **Third-party integration** How well both frameworks support and integrate with other plugins, libraries, and tools. - **Customization**: How you can deeply interfere and customize the behavior of both frameworks, such as dark mode, adding scripts, dynamic page generating, custom components in MDX files. What we don't cover in this article: - **Performance**: We are targeting blogs, which are mostly static content. Performance is not a big concern here. - **Testing**: While testing is important, it is beyond the scope of this article. Who tests their personal blog anyway? - **Databases and APIs**: We are focusing on static sites with MDX files. Everything must be generated at build time, so there will no APIs or database involved during runtime. # Layout of the applications To keep it simple, each project will have the following layout: - `/`: Home page with a list of posts. - `/posts/:slug`: Post page with the content of the post. - `/about`: About page with some information about the author. Each post will be written in MDX format and will have the following frontmatter: ```yaml --- title: string slug: string date: string published: boolean publishedAt: string author: string tags: string[] category: string thumbnail: string --- ``` # Server components A major feature in NextJS is the ability to use React Server Components by default. In a nutshell, server components are rendered on the server ahead of time, before bundling, in an environment separate from your client app or SSR server[^1]. While NextJS has an amazing support for server components, GatsbyJS does not fully support server components yet. First, the feature is still beta and not recommended for production. Second, RSC does not work in `gatsby develop` environment, which is a major drawback for developers who want to use it[^2]. More discussion in this [RFC](https://github.com/gatsbyjs/gatsby/discussions/36608). While server components are a great feature that reduces the complexity of data fetching and rendering, it is not a must-have feature for a blog since the majority of the content is static and can be pre-rendered at build time from MDX files. Therefore, I will not consider this feature in our comparison. # Setup Both frameworks provide a CLI tool to create a new project with a step-by-step configuration so you can tailor your project to your needs. ## NextJS In NextJS, you can create a new project with [`create-next-app`]( https://www.npmjs.com/package/create-next-app): including ```ansi $ [0;34mnpx[0;0m create-next-app@latest next-mdx-blog-template Need to install the following packages: create-next-app@15.1.6 Ok to proceed? (y) y [0;32m✔[0;0m Would you like to use [0;1;36mTypeScript[0;0m? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like to use [0;1;36mESLint[0;0m? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like to use [0;1;36mTailwind CSS[0;0m? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like your code inside a [0;1;36m`src/` directory[0;0m? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like to use [0;1;36mApp Router[0;0m? (recommended) … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like to use [0;1;36mTurbopack[0;0m for `next dev`? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m Would you like to customize the [0;1;36mimport alias[0;0m (`@/*` by default)? … No / [0;4;34mYes[0;0m [0;32m✔[0;0m What [0;1;36mimport alias[0;0m would you like configured? … [0;4;34m@/*[0;0m Creating a new Next.js app in [0;32m~/next-mdx-blog-template[0;0m. ... ``` NextJS CLI also allows you to choose an existing template to start. Those templates varies from a simple blog with small features such as TypeScript support to a full-fledged e-commerce site with a CMS integration. To clone a template, you can use the following command: ```sh npx create-next-app --example with-cloudinary with-cloudinary-app ``` More templates can be found at [NextJS starter templates and themes]( https://vercel.com/templates/next.js). ## GatsbyJS In GatsbyJS you can create a new project with [`create-gatsby`]( https://www.npmjs.com/package/create-gatsby): ```ansi $ [0;34mnpm[0;0m init gatsby > npx > create-gatsby [0;2;37mcreate-gatsby version 3.14.0[0;0m [0;4;34mWelcome to Gatsby![0;0m This command will generate a new Gatsby site for you in [0;1m~[0;0m with the setup you select. [0;1mLet's answer some questions[0;0m: What would you like to call your site? [0;32m✔[0;0m · gatsby-mdx-blog-template What would you like to name the folder where your site will be created? [0;32m✔[0;0m ~/ gatsby-mdx-blog-template [0;32m✔[0;0m Will you be using JavaScript or TypeScript? [0;34m· TypeScript[0;0m [0;32m✔[0;0m Will you be using a CMS? [0;34m· No (or I'll add it later)[0;0m [0;32m✔[0;0m Would you like to install a styling system? [0;34m· Tailwind CSS[0;0m [0;32m✔[0;0m Would you like to install additional features with other plugins? [0;34m· Add responsive images[0;0m [0;34m· Add an automatic sitemap[0;0m [0;34m· Generate a manifest file[0;0m [0;34m· Add Markdown and MDX support[0;0m Thanks! Here's what we'll now do: 🛠 Create a new Gatsby site in the folder [0;35mgatsby-mdx-blog-template[0;0m 🎨 Get you set up to use [0;35mTailwind CSS[0;0m for styling your site 🔌 Install [0;35mgatsby-plugin-image[0;0m, [0;35mgatsby-plugin-sitemap[0;0m, [0;35mgatsby-plugin-manifest[0;0m, [0;35mgatsby-plugin-mdx[0;0m ✔ Shall we do this? (Y/n) · Yes ... ``` Like NextJS, GatsbyJS also has a list of starters and templates, developed by either the Gatsby Team or the community. They also varies from a simple page with small features to a full-stack. production-ready website. To clone a starter, you can use the following command: ```sh npx gatsby new gatsby-starter-shopify https://github.com/gatsbyjs/gatsby-starter-shopify ``` More starters can be found on [Gatsby starter library]( https://www.gatsbyjs.com/starters/) ## Conclusion Both frameworks provide a great CLI tool to create or clone new projects that are tailored to your need. Both CLI tools offer a command-line prompt to help developers choose the right setup for their projects. For this criteria, **both frameworks are equal**. # TypeScript-friendly TypeScript is a big consideration when it comes to choosing which one to build your blog. At the core, TypeScript provides a type-checking system that prevents a majority of type errors from happening at runtime. From developer's perspective, it also provides a better intellisense and code completion when using a modern IDE, or a language server. So how easy it is to use and integrate TypeScript in both frameworks should be weighed carefully. ## NextJS Since both frameworks are built on top of React, writing React components and logic code in TypeScript is easy and straight forward, with the help of the `@types/react`, `@types/react-dom` packages and each framework's CLI tools. **However, the tricky parts are those configuration and plugin code that is deeply rooted in each framework.** For example, in NextJS, generating metadata for SEO or a sitemap requires you to define a custom object, or pages might have some props such as params and search queries. Luckily, NextJS has a great support for TypeScript for those specific types: ```tsx title="app/shop/page.tsx" import type { Metadata } from 'next' export const metadata: Metadata = { title: '...', description: '...', } export default async function Page({ params, }: { params: Promise<{ slug: string }> }) { const slug = (await params).slug } ``` ## GatsbyJS However, it's a lot more complex in GatsbyJS. First, GatsbyJS has its own API files `gatsby-node`, `gatsby-config`, `gatsby-ssr` and `gatsby-browser` to control the build process. Although Gatsby has a support to integrate TypeScript into these files natively, a better approach is to use JSDoc comments to define the types for the functions and objects: ```js title="gatsby-ssr.js" showLineNumbers /** * @type {import('gatsby').GatsbySSR['onRenderBody']} */ exports.onRenderBody = ({ setHtmlAttributes, setBodyProps, setBodyAttributes, }) => { setHtmlAttributes({ lang: `en` }); setBodyAttributes({ className: `bg-slate-950` }) } ``` More at [GatsbyJS TypeScript documentation](https://www.gatsbyjs.com/docs/how-to/custom-configuration/typescript/). Second, GatsbyJS uses GraphQL to fetch data and render pages. For small projects, you can define the query and result directly in your React code. However, it's redundant and not scalable for reusable components. A better approach is to turn on the option `graphqlTypegen: true` in your `gatsby-config` to generate types based on the GraphQL schema. This will generate a `src/gatsby-types.d.ts` file that contains all the types for your GraphQL queries on the first time you run your code. For example: ```tsx import * as React from "react"; import { graphql, useStaticQuery } from "gatsby"; const PostsTimeline: React.FC = () => { const { allMdx: { edges }, } = useStaticQuery(query); return (

); }; export default PostsTimeline; export const query = graphql` query ArticleTimeline { allMdx( sort: { frontmatter: { created: DESC } } filter: { frontmatter: { published: { eq: true } } } ) { edges { node { id tableOfContents(maxDepth: 2) timeToRead fields { excerpt slug } } } } } `; ``` This feature will scan the project for GraphQL queries and generate types that match with the query name. In this case, you first write the query `ArticleTimeline`, run it first and then use the generated type in your component. Finally, using TypeScript in GatsbyJS requires an additional package called [`gatsby-plugin-typescript`]( https://www.npmjs.com/package/gatsby-plugin-typescript) to transpile the code. However, the TypeScript compiler is not involved so many features supported by TypeScript natively. ## Conclusion NextJS and GatsbyJS have official guides and supports for TypeScript, from writing React code to deeply interfering with the build process. However, because GatsbyJS uses its own proprietary API files and GraphQL to fetch data, it's more complicated to config and use TypeScript. Meanwhile, TypeScript does not require to write NextJS-specific codes and configurations; you feel like you are just writing TypeScript code with React components. For this criteria, **using TypeScript in NextJS feels more natural and easier than in GatsbyJS**. # UI and styling To fairly compare both frameworks, `tailwindcss` and `shadcn` will be used as the main UI and styling tools. Both are popular and widely used in the React community. While `tailwindcss` provides utility-first CSS class names to style the components quickly, `shadcn` will provide headless UI components with complete functionality and customization. ## NextJS Both libraries have an official guide to integrate with NextJS. For `tailwindcss`, you can follow the [official guide]( https://tailwindcss.com/docs/guides/nextjs) to configure and set up your TailwindCSS. For `shadcn`, you can follow the [official guide]( https://shadcn.com/docs/getting-started/installation) to configure, install and use their UI components in your actual project. ## GatsbyJS Unlike NextJS, GatsbyJS does not have an official guide to install TailwindCSS, or at least an updated one. You might need to tweak [TailwindCSS's Using PostCSS guide](https://tailwindcss.com/docs/installation/using-postcss). Then, you need to install [`gatsby-plugin-postcss`]( https://www.gatsbyjs.com/docs/how-to/styling/post-css/) plugin for GatsbyJS to transpile the CSS code. A complete guide is found at [this gist]( https://gist.github.com/richardnguyen99/7939d6f7413bd87874264bbe942f2f3c). For `shadcn`, they have an official guide to configure, install and use their UI components in Gatsby projects. You follow [this guide]( https://ui.shadcn.com/docs/installation/gatsby) to achieve so. ## Conclusion While both libraries have official guides to integrate with NextJS, only `shadcn` has an official guide to integrate with GatsbyJS. For `tailwindcss`, you need to work around with PostCSS and GatsbyJS plugin system to make it work. The amount of work is practically the same since NextJS also requires you to set up PostCSS correctly. But, in all fairness, **NextJS has a better support for UI and styling libraries than GatsbyJS**. > At the time this article is being written, `shadcn` is struggling with the > release of `tailwindcss v4.0`. If you have a similar problem, please refer to > this [GitHub discussion]( > https://github.com/shadcn-ui/ui/discussions/2996#discussioncomment-11454000) > for more information. # Post rendering Post rendering is the process that fetches MDX posts from the file system and automatically generates pages for each post. This process is crucial for writing blogs since you don't want to manually create a new React page for each post. **Instead, you only want to write a template and let the automation handle the rest**. ## NextJS This is the controversial part of NextJS. NextJS does have an official support for generating pages from MDX files. More can be found [here]( https://nextjs.org/docs/pages/building-your-application/configuring/mdx). However, the official package, [`@next/mdx`]( https://www.npmjs.com/package/@next/mdx), has many limitations. For example, it does not support frontmatter, which is crucial for writing blogs. You need to manually parse the MDX files and extract the frontmatter, headings and content. Using this package also requires you to follow the folder pattern that NextJS expects, which is not flexible if you want to organize your posts in a different way. Another approach is to use [`next-mdx-remote`]( https://github.com/hashicorp/next-mdx-remote). This package initially solves the problem of remote MDX content. However, NextJS allows you to use Node file system APIs to read the MDX files and parse them. This approach is more flexible and allows you to organize your posts in any way you want. We also use [NextJS Dynamic Routes]( https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes) and [`generateStaticParams()`]( https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#generating-static-params) to statically generate routes at build time. To strictly enforce the static params, you can set [`dynamicParams=false`]( https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) to return a 404 page if the route is not found in the result array of `generateStaticParams()`. ```tsx title="src/app/blog/[slug]/page.tsx" showLineNumbers // Force NextJS to return 404 for unknown slugs export const dynamicParams = false; // NextJS options to enable to generate static // paths at build time. export const generateStaticParams = async () => { const posts = await fs.promises.readdir("posts"); return posts.map((post) => ({ params: { slug: post.replace(/\.mdx$/, "") }, })); // Return: ["blog-1", "blog-2", "blog-3", ...] }; export default async function BlogPost({ params }) { const { slug } = await params; const post = await getMdxBySlug(slug); return (

{post.frontmatter.title}

); } ``` NextJS leaves the rest to you to handle the fetching and rendering posts, depending on how you implement functions like `getMdxBySlug()`. This approach is more flexible and allows you to customize the behavior of the post rendering. You can add more fields that are not available in the frontmatter such as `timeToRead`, and `tableOfContents` by extending your `getMdxBySlug()` function. ## GatsbyJS Unlike NextJS, GatsbyJS provides an official support for generating pages from MDX files. GatsbyJS utilizes the Gatsby Config API, and the [`createPages`]( https://www.gatsbyjs.com/docs/creating-and-modifying-pages/) of the Gatsby Node API to create pages. At the core, GatsbyJS uses the `gatsby-source-filesystem` plugin to read the MDX files from the file system and the `gatsby-plugin-mdx` to parse the MDX files, including the frontmatter, headings and the content. These are done by the Gatsby Config API automatically. Then, you can use the `createPages` API to generate pages for each post. For example: ```ts title="gatsby-node.ts" showLineNumbers export const createPages: GatsbyNode["createPages"] = async ({ graphql, actions, reporter, }) => { const { createPage } = actions; const result = await graphql(`#graphql query MdxNode { allMdx { nodes { id frontmatter { slug } internal { contentFilePath } } } } `); if (result.errors) { reporter.panicOnBuild("Error loading MDX result", result.errors); return; } if (typeof result.data === "undefined") { reporter.panicOnBuild("No data returned from MDX query"); return; } // Create blog post pages. const posts = result.data.allMdx.nodes; const postTemplate = path.resolve(__dirname, "src", "templates", "post.tsx"); posts.forEach((post) => { createPage({ path: `/blog/${post.frontmatter.slug}`, component: `${postTemplate}?__contentFilePath=${post.internal.contentFilePath}`, context: { id: post.id, }, }) }); }; ``` This code will generate a new page for each MDX files from the GraphQL query result. The `postTemplate` is a React component that will be treated as a page as those in `src/pages` directory. You can use the `context` object to pass additional data to the page. For example, passing the `id` of the post to the page so it can query the post content for rendering: ```tsx import React from "react"; import { MDXProvider } from "@mdx-js/react"; import { graphql } from "gatsby"; // Custom components to use directly in MDX files const shortCodes = {}; const PostLayout: React.FC> = ({ mdx, children }) => { return (

{mdx?.frontmatter?.title}

{children};

); }; export default PostLayout; export const query = graphql` query PostLayout($id: String!) { mdx(id: { eq: $id }) { frontmatter { title # More information if needed such as tags, thumbnail, etc. } } } `; ``` GatsbyJS also provides some ways to customized your MDX files that are not available in the frontmatter such as `timeToRead`. For example, [`onCreateNode`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-node/#onCreateNode) API can be used to extend the node object with more fields: ```ts title="gatsby-node.ts" showLineNumbers // Other APIs export const onCreateNode: GatsbyNode["onCreateNode"] = ({ node, actions, reporter, }) => { const { createNodeField } = actions; if (node.internal.type === "Mdx") { try { createNodeField({ name: "timeToRead", node, value: readingTime(node.body as string), }); } catch (e) { reporter.panicOnBuild( "Error creating node field (Node ID: " + node.id + "):\n" + (e as Error).message ); } } }; ``` ## Conclusion This is a tough one. NextJS allows you to control and handle the post rendering process as you do so in a normal TypeScript code: fetch from file system, parse the raw content, extract the frontmatter and pass the content to MDX renderer. This requires a lot of manual work, including handling installing the right packages, extracting the right parts, and defining the right types. But it will give you the flexibility to customize the behavior of the post rendering. GatsbyJS, on the other hand, automates the process for you but it feels like you are writing GatsbyJS code, with GraphQL and its proprietary APIs. However, by having a strict convention and a set of APIs, GatsbyJS provides a more bullet-proof way to fetch and render posts. Especially with the help of the GraphiQL playground in development, you can easily test and debug your queries. GatsbyJS also infers the types for you based on the GraphQL schema, which is a huge advantage for TypeScript users. ```graphql query MdxNode { allMdx { nodes { id fields { timeToRead { minutes time } } frontmatter { slug } } } } ``` For this criteria, **GatsbyJS is the winner**. # Minimal Server-side Features Both frameworks are capable of handling render on demand with query strings and search params. This allows you to build features such as pagination, searching and filtering. ## NextJS NextJS provides server-side rendering (SSR) pages with the help of [Dynamic Rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering). This feature allows users to request for page information in runtime. By simply using search params in URLs, you can trigger the SSR process and render the page with the requested data. NextJS also has a great documentation for search params and query strings. These are built-in features for page components (`page.tsx`). For example: ```tsx title="app/blog/page.tsx" showLineNumbers type Props = { searchParams: Promise<{ filter?: string; sort?: string; page?: string; }>; }; export default async function Blog({ searchParams }: Props) { const { filter, page = "1", sort } = await searchParams; // ... } ``` By using `searchParams`, NextJS will automatically opt in [dynamic rendering]( https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering) at the request time. More information can be found [here]( https://nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional). ## GatsbyJS Modern GatsbyJS also supports SSR. Unlike NextJS, GatsbyJS requires users to specifically export [`getServerData`](https://www.gatsbyjs.com/docs/reference/rendering-options/server-side-rendering/) function to handle the SSR process. This function allows users to preprocess the requests and pass appropriate data into page components under prop `serverData`. ```tsx title="src/pages/index.tsx" showLineNumbers import { GetServerData, PageProps } from "gatsby"; type ServerDataType = { filter?: string; sort?: string; page?: number; }; type Props = PageProps; function Blog(props: Props) { const { serverData } = props; const { filter, page, sort } = serverData; // ... } export const getServerData: GetServerData = async (context) => { const { query } = context; const { filter, page = "1", sort } = query; // ... return { status: 200, // The HTTP status code that should be returned props: { filter, sort, page, }, // Will be passed to the page component as "serverData" prop headers: {}, // HTTP response headers for this page }; }; export default Blog; ``` However, the workflow is more complicated than expected when you try incorporating GraphQL. Gatsby uses GraphQL to fetch data at build time, whether your pages are rendered statically or on server-side. GatsbyJS does not support runtime GraphQL queries yet [^3]. This means you will need to handle the search params in `getServerData` and the requested blog data in the page components. ```tsx title="src/pages/index.tsx" {10-35} import { GetServerData, PageProps, graphql } from "gatsby"; // [!code ++] function Blog(props: Props) { const { data, serverData } = props; // [!code ++] const { filter, page, sort } = serverData; // ... } export const query = graphql` query BlogPage { allMdx { nodes fields { timeToRead { text time } } frontmatter { slug title date author description tags category published publishedAt } } } } `; ``` The GraphQL result will be passed to the page components under prop `data`. You can combine `data` and `serverData` to handle the rendering logic such as paginating, sorting and filtering your posts. ## Conclusion Both frameworks provide a way to handle server-side rendering with basic runtime requests. However, NextJS has a more straightforward approach to handle search params and query strings. You can simply use the `searchParams` prop in your React component without any boilerplate. GatsbyJS, on the other hand, requires you to export a specific function to handle the SSR process. The process is also more complicated when you try to incorporate GraphQL. For this criteria, **NextJS slightly wins over GatsbyJS**. # SEO SEO is a crucial part of building a blog. It helps your blog be easier to be indexed by search engines and be more accessible to readers. Both frameworks provide a way to handle SEO with metadata and sitemap. ## NextJS NextJS provides a way to handle SEO with the help of exported [`metadata`]( https://nextjs.org/docs/app/building-your-application/optimizing/metadata) object. This object allows you to define the metadata for your pages, such as `opengraph` and `twitter` cards, and NextJS will transform it into the appropriate HTML `` tags: ```tsx title="app/blog/(layout|page).tsx" showLineNumbers import { type Metadata } from "next"; export const metadata: Metadata = { title: "Home | Next MDX Blog Template", description: "A blog template built with Next.js and MDX.", referrer: "origin", keywords: [ "framework", "blog", "news", "technology", ], metadataBase: new URL( process.env.NODE_ENV === "production" ? "https://mydomain.com" : "http://localhost:8080" ), openGraph: { type: "website", description: "Generated by create next app", title: "Home | Create Next App", siteName: "Create Next App", url: "https://nextjs.org", locale: "en_US", images: [ { url: "/twitter-card.png", width: 1200, height: 630, alt: "Create Next App", }, ], }, twitter: { card: "summary_large_image", title: "Home | Create Next App", description: "Generated by create next app", images: [{ url: "/twitter-card.png", width: 1200, height: 630, alt: "Create Next App", }], } }; export function Page(props) { return (

...

); } ``` This `metadata` object provides basic needs for your site metadata and SEO needs. With the help of TypeScript and good documentation, you can easily infer the types and customize the metadata for your pages. NextJS will use these metadata fields to construct the appropriate HTML `` tags during runtime. ![NextJS Generated SEO metadata](/generated-seo-tags-illustration.png "NextJS Generated SEO metadata") NextJS also allows you to generate metadata dynamically with [`generateMetadata()`](https://nextjs.org/docs/app/api-reference/functions/generate-metadata). This function uses the same props as your page components, `params` and `searchParams`. This allows you to generate metadata based on the requested data. ```tsx title="app/blog/[slug]/(page|layout).tsx" showLineNumbers import type { Metadata } from 'next' // either Static metadata export const metadata: Metadata = { title: '...', } // or Dynamic metadata export async function generateMetadata({ params }) { return { title: '...', } } ``` ## GatsbyJS GatsbyJS uses a different approach to handle SEO. Instead of using a single metadata object, GatsbyJS uses a combination of configurations and components to handle SEO. At the core, Gatsby provides the [` API`]( https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-head/) to add elements to the `` of your HTML document, which is useful to add `` tags for SEO. ```tsx title="src/pages/index.tsx" showLineNumbers import * as React from "react"; const Page = () =>

Hello World

; export default Page; export function Head() { return ( Hello World ); } ``` Since `` is a normal React component, you can write a reusable component to handle common metadata for all pages and specific metadata for each page. ```tsx title="src/components/seo.tsx" showLineNumbers import React from "react"; import { useSiteMetadata } from "@/hooks/use-site-metadata"; type Props = Partial< NonNullable["siteMetadata"] > & { children?: React.ReactNode | React.ReactNode[]; keywords?: string[] }; const SEO: React.FC = ({ title, description, image, siteUrl, xUsername, children, keywords = ["blog", "gatsby", "mdx", "typescript"], }) => { const siteMetadata = useSiteMetadata(); const { titleTemplate, title: defaultTitle, description: defaultDescription, image: defaultImage, siteUrl: defaultSiteUrl, xUsername: defaultXUsername, } = siteMetadata || {}; const seo = { title: title || defaultTitle, description: description || defaultDescription, siteUrl: `${siteUrl || defaultSiteUrl}`, xUsername: xUsername || defaultXUsername, image: { src: image?.src || defaultImage?.src, width: image?.width || defaultImage?.width, height: image?.height || defaultImage?.height, alt: image?.alt || defaultImage?.alt, } }; return ( <> {`${seo.title} | ${titleTemplate}`} {/* More metadata tags */} {/* Specific SEO tags such as JSON+LD */} {children} ); }; export default SEO; ``` GatsbyJS also **recommends** defining `siteMetadata` in your `gatsby-config` file. This field acts as a global, reusable configuration for your site, but mainly used for SEO purposes: ```ts title="gatsby-config.ts" import type { GatsbyConfig } from "gatsby"; const config: GatsbyConfig = { siteMetadata: { title: `Home`, titleTemplate: `Gatsby MDX Blog Starter`, siteUrl: `https://gatsby-mdx-blog-starter.netlify.app/`, description: `A Gatsby blog template using MDX`, xUsername: `@RichardNgu65749`, image: { src: `/og-image.png`, width: 1600, height: 836, alt: `OG Gatsby MDX Blog Starter Image`, } }, plugins: [ // ... ], } ``` Then, you can define a custom hook to access the `siteMetadata` in your your SEO component: ```ts title="src/hooks/use-site-metadata.ts" import { graphql, useStaticQuery } from "gatsby"; export const useSiteMetadata = () => { const data = useStaticQuery(graphql` query SiteMetadata { site { siteMetadata { title titleTemplate description xUsername siteUrl image { src width height alt } } } } `) return data.site?.siteMetadata; } ``` Similar to NextJS, GatsbyJS also allows you to generate add metadata tags dynamically based on the requested data. For example, you can expose the GraphQL result to the `` component and use that to generate the metadata tags: ```tsx title="src/template/post.tsx" showLineNumbers // Template to generate blog post pages in gatsby-node.ts // See post-rendering section for more information import React from "react"; import { MDXProvider } from "@mdx-js/react"; import { graphql, HeadFC } from "gatsby"; import SEO from "@/components/seo"; type PostLayoutData = { data: Queries.PostLayoutQuery; }; const PostLayout: React.FC> = ({ data, children, }) => { return (

{/* ... */}

); }; export default PostLayout; export const query = graphql` query PostLayout($id: String!) { mdx(id: { eq: $id }) { fields { timeToRead { minutes time text } } frontmatter { # Other fields } } } `; export const Head: HeadFC = ({ data }) => { // From GraphQL result const { mdx } = data; return }; ``` ## Conclusion Both frameworks are initially designed to solve the SEO problems existing in normal React applications. These methods are native and official supported from the frameworks with great documentation. However, NextJS has a more easy way to handle SEO metadata. It's simply that NextJS provides a well-structured, type-safe metadata object that tells you exactly how you can use each field. GatsbyJS does not provide a good documentation on what fields, or how you should use it. If you want to enforce type safety, you need to involve `gatsby-node` to explicitly define the types for it. For those reasons, **NextJS is the winner**. # Third-party integration Third-party solutions are crucial for building a blog. They provide additional features such as analytics, image hosting and searching. Both frameworks have a list of official and community plugins to integrate with third-party tools. Since we are building a blog, we will focus on those features that are mentioned above: _analytics_, _image hosting_ and _searching_. For analytics, [Google Analytics](https://developers.google.com/analytics) will help us track the page views, user interactions and other metrics. For image hosting, [Cloudinary](https://cloudinary.com/) is a popular choice for hosting images and optimize delivery via programmatic configurations. For searching, we are going to use [Algolia](https://www.algolia.com/) to index and search our posts. ## Analytics Google Analytics is a popular, free choice to monitor website traffic and user behavior. Although setting up Google Analytics is fairly easy in React projects, both frameworks have their own official plugins to integrate with Google Analytics without a hassle. This will eliminate the need to manually configure the tracking code and reduce the risk of errors. ### NextJS NextJS provides [`@next/third-parties/google`]( https://nextjs.org/docs/app/building-your-application/optimizing/third-party-libraries#server-side-tagging) to integrate with Google Analytics. This package provides a set of components and hooks to integrate with Google SDK, including Google Analytics. To use it, simply import the `` component and wrap your application with it: ```tsx title="app/layout.tsx" showLineNumbers import { GoogleTagManager } from "@next/third-parties/google" export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( {children} ) } ``` ### GatsbyJS [`gatsby-plugin-google-gtag`](https://www.gatsbyjs.com/plugins/gatsby-plugin-google-gtag/) is the official plugin from Gatsby to integrate with Google Analytics. Unlike `@next/third-parties/google` which uses a React component, you need to put the plugin in your `gatsby-config` file and pass the configuration options to it. ```ts title="gatsby-config.ts" showLineNumbers const config: GatsbyConfig = { plugins: [ { resolve: `gatsby-plugin-google-gtag`, options: { trackingIds: [ `G-RW65TSLLP4`, ], pluginConfig: { head: true, }, }, }, // ... ], }; ``` ## Image hosting For image hosting, I decided to go with [Cloudinary](https://cloudinary.com/). Cloudinary is a popular choice for hosting images and video because it provides a programmatic way to upload, transform and deliver images. It also supports a variety of languages and frameworks, including React. ### NextJS Cloudinary has an official package, [`next-cloudinary`](https://next.cloudinary.dev/) just for NextJS. The package lets you set up Cloudinary environment variables and use the React component immediately. ```txt NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="" NEXT_PUBLIC_CLOUDINARY_API_KEY="" CLOUDINARY_API_SECRET="" ``` ```tsx import { CldImage } from 'next-cloudinary'; ``` ### GatsbyJS GatsbyJS does provide community plugins to integrate with Cloudinary. [`gatsby-source-cloudinary`](https://www.gatsbyjs.com/plugins/gatsby-source-cloudinary/) allows you to add your Cloudinary resources into Gatsby's GraphQL data layer. Then, you can use [`gatsby-transformer-cloudinary`](https://www.gatsbyjs.com/plugins/gatsby-transformer-cloudinary/) to transform the Cloudinary resources into Gatsby's image format. This allows you to use the `` component to render the images. ```ts title="gatsby-config.ts" showLineNumbers module.exports = { plugins: [ { resolve: `gatsby-source-cloudinary`, options: { cloudName: process.env.CLOUDINARY_CLOUD_NAME, apiKey: process.env.CLOUDINARY_API_KEY, apiSecret: process.env.CLOUDINARY_API_SECRET, // resourceType: `image`, // type: `twitter`, // maxResults: 22, // tags: true, // context: true, // prefix: `demo/animals` }, }, { resolve: `gatsby-transformer-cloudinary`, options: { // Add the `gatsbyImageData` resolver to `CloudinaryMedia` transformTypes: [`CloudinaryMedia`], }, }, `gatsby-plugin-image`, ], }; ``` However, the setup and configuration is not as straightforward. You will need To create a GraphQL type or configure an existing one in order for the plugin to recognize the resources and transform accordingly. An easy way is to use their React package: ```tsx import React from "react"; import { Cloudinary } from "@cloudinary/url-gen"; import { AdvancedImage } from "@cloudinary/react"; import { auto } from "@cloudinary/url-gen/actions/resize"; import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity"; import { cn } from "@/lib/utils"; type Props = { src: string; alt: string; className?: string; }; const ImageCard: React.FC = ({ src, alt, className }) => { const cld = new Cloudinary({ cloud: { cloudName: process.env.GATSBY_CLOUDINARY_CLOUD_NAME, }, }); const img = cld .image(src) .format("auto") .quality("auto") .resize(auto().gravity(autoGravity())); return (

img]:object-cover [&>img]:w-full [&>img]:h-40", className) } >

); }; ``` ## Searching Searching, or indexing, or autocomplete, is a crucial part of building a blog. It helps our readers to easily search and find the posts they are looking for in a fast, accurate way. Algolia is considered the best choice for indexing technical content. You can upload your content to Algolia using their write APIs. Algolia provides from a complete UI tools, [`react-instantsearch`]( https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/), a mix-match between UI and logic, [`autocomplete`]( https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/), to a fully-customizable React renderer, [`autocomplete-core`]( https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-core/) so you can build your search features however you want. In this criterion, we care about how easy to upload the content to Algolia and to use the indices. > Algolia also has a free plan for open-source, non-commercial projects such as > technical writings and documentations, [docsearch](https://docsearch.algolia.com/). > Algolia team will take a look at your project and provide snippets on how to > integrate the free plan into your website. ### NextJS For uploading the content to Algolia, unfortunately, you need to write your own standalone script to do so. An upside is that you can use NodeJS and control the process on your own. However, this requires you to manually configure, and upload the content to Algolia. ```ts title="scripts/upload-algolia.ts" showLineNumbers import { algoliasearch } from "algoliasearch"; const client = algoliasearch( process.env.ALGOLIA_APP_ID as string, process.env.ALGOLIA_ADMIN_API_KEY as string ); const processRecords = async () => { const posts = await getMdxPosts() const postIndices = await Promise.all( posts.map(async (file) => { const { frontmatter, headings } = await getMdxBySlug(file); return { objectID: file.replace(".mdx", ""), title: frontmatter.data.title, description: frontmatter.data.description, // other attributes for searching }; }) ); return await client.saveObjects({ indexName: process.env.ALGOLIA_INDEX_NAME as string, objects: posts, }); }; processRecords() .then(() => { console.log("Successfully indexed records"); }) .catch((err) => { console.error(err); }); ``` After successfully uploading the indexing data to Algolia, you can use Algolia's searching UI packages to integrate with your website. `react-instantsearch` provides a complete UI out-of-the-box solution with many widgets to choose from. They also provide hooks for each UI widgets so that you can write your own components. > `react-instantsearch` provides a package, `react-instantsearch-nextjs`, that > exclusively supports NextJS an React Server Components. This package enables > SSR to generate HTML from `react-instantsearch` components on the server. `autocomplete-js` provides a pre-defined UI logic such as functionalities, accessibility and keyboard navigation. However, you are in control of writing your own UI components and integrating them with `autocomplete-js` props. Finally, `autocomplete-core` lets you define your own logic on how Algolia should return the results. From writing queries, defining the result objects to customizing collections such as recent and favorite results. ### GatsbyJS GatsbyJS provides a good documentation on how to integrate with Algolia. It also includes [`gatsby-plugin-algolia`]( https://github.com/algolia/gatsby-plugin-algolia) to help you upload the indexing data to Algolia. The beauty of this plugin is that it automatically send the data to Algolia when you run `gatsby build` command, even in local environment. With the help of Gatsby Cache, it will only upload the data that has been changed the last build. ```ts title="gatsby-config.ts const pageQuery = `#graphql query AlgoliaQuery { pages: allMdx { nodes { id internal { contentDigest } tableOfContents(maxDepth: 3) frontmatter { slug title description tags publishedAt thumbnail { cloudName alt publicId } } } } }`; function pageToAlgoliaRecord(props) { return { objectID: props.frontmatter.slug, title: props.frontmatter.title, description: props.frontmatter.description, // other attributes for searching }; } const queries = [ { query: pageQuery, transformer: ({ data }: { data: Data }) => data.pages.nodes.map(pageToAlgoliaRecord), indexName: process.env.GATSBY_ALGOLIA_INDEX_NAME as string, }, ]; const config: GatsbyConfig = { plugins: [ { resolve: `gatsby-plugin-algolia`, options: { appId: process.env.GATSBY_ALGOLIA_APP_ID, apiKey: process.env.ALGOLIA_WRITE_KEY, queries, settings: { // optional, any index settings // Note: by supplying settings, you will // overwrite all existing settings on the index }, }, }, // ... ], }; export default config; ``` After successfully uploading the indexing data to Algolia, you can use Algolia's searching UI packages to integrate with your website as mentioned above. ## Conclusion Both frameworks provide a way to integrate with third-party services such as Google Analytics, Cloudinary and Algolia. However, NextJS has a more straightforward approach to integrate with Google Analytics and Cloudinary. Integration with Algolia is an interesting one. NextJS does not have an automatic process to upload the indexing data to Algolia. Meanwhile, the configuration and setup in GatsbyJS is more complicated due to GraphQL queries. However, I'm still inclined to say that **NextJS is the winner** here. An important part of integrating with third-party plugins is how well the docs are. Finding documentation in NextJS is fairly easy because the docs are well supported in many cases andd well maintained to resolve many issues. I cannot say the same thing to GatsbyJS. The documentation is either lacking or outdated. Searching for solutions in GatsbyJS is also painful since there are not many active community members to help you out. # Customization Customization is how easy you can customize the framework to fit your needs. This is a broad and subjective aspect because you might customize your app based on your needs. However, I focus on the most commonly implemented feature in a blog: _dark mode_. To keep the comparison fair, I won't use any third-party libraries or packages to implement the dark mode. Instead, I will write my own implementation to demonstrate how easy it is to customize the frameworks. There are three main parts to implement dark mode: - Detect and persist the user's preference with `localStorage` API. - Have a theme switch to toggle between light and dark mode. - Prevent the flash of unstyled content (FOUC) when the page is loading. ## NextJS To be compatible with TailwindCSS, which uses HTML classes to toggle the light and dark theme, we need to add a custom client script that retrieves the user's preference from `localStorage` and applies the theme to the HTML element. ```js void function () { /** * Callback fired when window.__theme was set or updated */ window.__onThemeChange = function () {}; /** * Sets the theme on the element * @param {string} newTheme - The new theme to set */ let preferredTheme; try { preferredTheme = localStorage.getItem("theme"); } catch (err) { } function setTheme(newTheme) { const oldTheme = window.__theme; const darkOrLight = newTheme === "system" ? ( window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light" ) : newTheme; if (preferredTheme && document.documentElement.classList.contains(preferredTheme) && preferredTheme !== darkOrLight) { document .documentElement .classList .replace(preferredTheme, darkOrLight); } else { document.documentElement.classList.add(darkOrLight); } window.__theme = newTheme; preferredTheme = darkOrLight; window.__onThemeChange(darkOrLight); } window.__setPreferredTheme = function (newTheme) { setTheme(newTheme); try { localStorage.setItem("theme", newTheme); } catch (err) {} } var darkQuery = window.matchMedia("(prefers-color-scheme: dark)"); darkQuery.addListener(function (e) { window.__setPreferredTheme(e.matches ? "dark" : "light"); }); setTheme(preferredTheme || (darkQuery.matches ? "dark" : "light")) }(); ``` The purpose of the script is to detect the user's preference and apply the theme to the HTML element. It's also suggested to include the script at the top of the page to reduce potential flash of unstyled content (FOUC). ```tsx title="app/layout.tsx" showLineNumbers import type { Metadata } from "next"; const script = /*js*/ ` // The script above `; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return (

{children}

1 articles

Latest Blog

Categories

Tags

Others

Latest Blog

1 articles

Latest Blog