
## Adding custom fonts to your website is a typical requirement for most web projects

By default, Next.js sites will add small set of fonts that you can use for your sites (in addition to the default fonts for a given browser). That can be useful to get started quickly, but for most custom site designs, you'll need to add custom fonts and typefaces that fit your site's brand and design guidelines.

In this tutorial, you'll learn how to **add custom fonts to your Next.js site using the `next/font` package and Tailwind CSS**. There's a few configuration steps needed to load fonts from Google Fonts using `next/font`, generate CSS variables for each font, and then use those variables to create custom font families in your Tailwind config.

With this setup, you'll be able to easily use your custom fonts throughout your Next.js app using Tailwind's utility classes.

### SEO Benefits of using custom fonts correctly on your Next.js site

In addition to improving the user experience, implementing custom fonts on your website can also have a [positive impact on your Lighthouse scores](https://web.dev/patterns/web-vitals-patterns/fonts/) and SEO. However, it's important to implement custom fonts carefully to avoid performance issues. Using too many or too large font files can slow down your site's loading time and hurt your Lighthouse performance score. Additionally, using custom fonts in a way that affects the visual stability of the page can result in lower scores for Core Web Vitals, which can impact your SEO. So, it's important to strike a balance between using custom fonts to enhance the design and ensuring that they don't negatively impact performance or user experience.

### About next/font

[`next/font` is an npm package](https://nextjs.org/docs/api-reference/next/font) developed by Vercel, which provides an easy way to load fonts in your Next.js app, while maintaing performance, and minimizing [Cumulative Layout Shift (CLS)](https://web.dev/optimize-cls/). It uses the Font Loading API to asynchronously load local font files stored in your repo, or from popular font providers such as Google Fonts, Typekit, and Fonts.com. The package also generates optimized font subsets to reduce the amount of data transferred over the network, and it provides a convenient way to generate CSS variables for each font, which can be used to create custom font families in your [Tailwind config](https://tailwindcss.com/docs/configuration). This makes it easy to use custom fonts throughout your Next.js app with minimal configuration.

## How to: Add multiple custom fonts to your Next.js site with Tailwind CSS

There are several ways to load custom fonts into your next.js app. If you're using a Google Fonts as your custom font provider, you can use the `next/font/google` package to load fonts from Google Fonts. The process is slightly different for loading font files that are stored locally in your repo, but the basic steps are the same:

### Load custom fonts from Google Fonts

In `_app.jsx/tsx`, load your the fonts you need from `next/font/google`, but use the `variable` configuration prop, which you will use to generate a definition for a CSS `--var` for each font:

```tsx
import { Barlow_Condensed, Inter } from 'next/font/google';
const barlowCondensed = Barlow_Condensed({
  weight: '700',
  subsets: ['latin'],
  variable: '--font-barlow-condensed',
});
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
});
```

### Load custom fonts from a local file

This next example shows how you would load a font from a local file. It also showcases another feature of the `next/fonts` library - you can map font weights to different files as needed. This also applies for font _styles_ (italic, bold, etc).

In `_app.jsx/tsx`, load your the fonts you need from `next/font/local` using the syntax below. Note that in this case, font files in my repo are also being hosted in `/public/fonts` directory. Again, make sure to use the `variable` configuration prop, which you will use to generate a definition for a CSS `--var` for each font:

```tsx
import localFont from 'next/font/local';

const grosa = localFont({
  src: [
    {
      path: '../../public/fonts/Grosa/Grosa-Regular.woff2',
      weight: '500',
      style: 'normal',
    },
    {
      path: '../../public/fonts/Grosa/Grosa-Medium.woff2',
      weight: '600',
      style: 'normal',
    },
    {
      path: '../../public/fonts/Grosa/Grosa-Bold.woff2',
      weight: '700',
      style: 'normal',
    },
  ],
  variable: '--font-grosa',
});
```

### After loading custom fonts, generate CSS variables for each font

Then, in that same `_app.tsx` component - pass the generated variables into the wrapper class. This will make that variable available to any child of that element in the DOM (in other words, your whole app):

```tsx
export default function MyApp({ Component, pageProps }) {
  return (
    <main
      className={`${inter.variable} ${barlowCondensed.variable} ${grosa.variable}`}
    >
      <Component {...pageProps} />
    </main>
  );
}
```

Behind the scenes, next is generates unique css classes for each font permutation. These classes do one thing: they define a [css custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) (sometimes called a css variable) for each font.

By adding the resulting CSS classes to the root of your Next.js app, these variables are made available to any child of the `App` component - essentially all pages and components on your site.

<Image
  publicId="posts/custom-fonts-with-next-font-and-tailwind/classes"
  caption="is a screenshot from Chrome Browser tools for Craftwork.com, which is built using this setup"
  alt="screenshot of chrome browser tools showing the resulting CSS classes"
/>

### Use these variables your Tailwind config to create font families

Up to this point, we've loaded our custom fonts into our Next.js app, and we've made those fonts available to our entire app using CSS variables. Now, we need to tell Tailwind how to use these variables, by assigning them to specific font-family classes.

In your Tailwind config, add an entry to your `theme.extend`, to create a new font family that uses the google fonts you just imported - that will look something like this:

```tsx
// tailwind.config.js
export default {
  theme: {
    extend: {
      fontFamily: {
        "barlow-condensed": "var(--font-barlow-condensed)", // note: you can call the left side of this whatever you want - barlow-bold or title-font or foo-bar, this is what you'll use in your Tailwind css classes to use this font
        "inter-medium": "var(--font-inter)", // note: the bit that goes inside the var() function is the same variable name we defined in app.tsx
      }
    }
  }
```

Then, whenever you want to use the fonts you've added, ask for that font-family in your tailwind classnames by prefixing the font-family with "font-", like this:

```tsx
const myComponent: React.FC = () => (
  <p className="font-barlow-condensed">
    This should be rendered with the Barlow font family
  </p>
);

export default myComponent;
```

That should do the trick!

If you're wondering where these steps came from, it is essentially a combination of the instructions provided in [Next's docs for Font Optimization](https://nextjs.org/docs/basic-features/font-optimization). My team is using this very configuration setup for our Next.js site on [Craftwork.com](https://craftwork.com) to load custom fonts both locally and from Google Fonts, and it's been working great.


Add custom fonts to Next.js sites with Tailwind using next/font


## I'm new to TypeScript.

I've been using TypeScript to build software for my new company, [Craftwork](https://craftwork.com). I've been pretty open about the fact that I'm new to TypeScript, and have been blissfully writing non-type-safe javascript code since somewhere around 2005.

Of course, that's all changing.

This new project is built with [create-t3-app](https://create.t3.gg), a framework for building TypeSafe apps with Next.js and TRPC. Out of the box, t3 is configured with some sensible (and fairly strict) settings for both eslint and TypeScript's tsconfig.

If you're familiar with TypeScript, Eslint, and tsconfig you may want to skip ahead to [My last resort to fix TypeScript errors in VS Code](#my-last-resort-to-fix-typescript-errors-in-vs-code).

### ESLint in a nutshell

If you're not familiar, _eslint is a **linter**_ - a tool that will help you identify and fix code quality and formatting issues in your code.

ESLint is a popular linter for JavaScript, and it can also be used with TypeScript. It provides a wide range of configurable rules that you can use to enforce consistent code style and identify potential bugs. ESLint is highly extensible, which means you can customize it to fit your specific needs. For example, you can use it to enforce your team's coding standards, or to catch common mistakes that TypeScript can't detect on its own.

### tsconfig in a nutshell

When you're working on a TypeScript project, `tsconfig.json` is a configuration file that allows you to specify how the TypeScript compiler should behave when it compiles your code.

The purpose of `tsconfig.json` is to provide a single source of truth for your TypeScript project's configuration. It allows you to specify options such as the target version of JavaScript you want to generate, the module system you want to use, the paths to your project's source files, and many other settings.

One of the main benefits of using `tsconfig.json` is that it allows you to enforce a consistent set of rules across your project. You can use it to enforce specific compiler options, which helps to ensure that your code is consistent and that everyone on your team is using the same settings. `tsconfig.json` also allows you to configure your project's build pipeline, so you can easily automate the process of compiling and bundling your TypeScript code.

Additionally, `tsconfig.json` allows you to take advantage of features like incremental compilation, which can significantly improve the speed of your builds by only compiling the parts of your project that have changed since the last build.

## How TypeScript works in VS Code

There are a few steps required to set up TypeScript to work with VS Code. If you haven't done this yet, you should follow the instructions on VisualStudio.com to get started: [TypeScript in Visual Studio Code](https://code.visualstudio.com/Docs/languages/typescript).

When you open a TypeScript file in VS Code, the TypeScript language server will start in the background. The language server is a separate process that provides language features like IntelliSense, code navigation, and code refactoring. It also provides the ability to run TypeScript code in the editor. Because TypeScript has _many_ options and plugins, the language server uses the `tsconfig.json` file in your project to determine the rules it should use to compile your code.

VS Code needs to determine which version of TypeScript to use, so it will look for a `package.json` file in your project. If it finds one, it will use the version of TypeScript specified in the `devDependencies` section. If it doesn't find a `package.json` file, it will use the version of TypeScript that is bundled with VS Code.

---

## My last resort to fix TypeScript errors in VS Code

Sometimes, when I'm working on a TypeScript project, I'll get an error in VS Code that I can't figure out. I'll check and double-check against articles and tutorials online, or ask my hyper-smart TypeScript friends ([Sean Rogers, everyone](https://seanrogers.dev/)), and despite doing everything I can think of to address the problem, sometimes I just can't get the error to go away.

Here's what I do when I find myself in this situation:

### Make sure VS Code is using the correct version of TypeScript

Sometimes VS Code's TypeScript process doesn't use the right version of TypeScript for the project I'm working on. For me, this seems to happen after updating TypeScript versions, or when switching between projects that use different versions of TypeScript.

To check which version of TypeScript VS Code is using, open the Command Palette (Ctrl+Shift+P on Windows, or &#8984; on a Mac) and type `TypeScript: Select TypeScript Version`.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/select-typescript-version"
  alt="Select TypeScript Version in the command palette in VS Code"
/>

If the version of TypeScript that is selected is not the one you expect, select the correct version from the list. Generally speaking, you'll want to select the version of TypeScript that is specified in your project's `package.json` file, by selecting `Use Workspace Version` option.

### Restart the TS server process

If that doesn't fix the problem, or VS Code was already running my workspace's version of TypeScript, the next thing I'll do is restart the TS server process. This is the background process being run by VS Code to actually analyze and compile your TypeScript code into JavaScript. Sometimes this process malfunctions, and restarting it can fix the problem.

To restart the TS server process, open the Command Palette (Ctrl+Shift+P on Windows, or &#8984; on a Mac) and type `TypeScript: Restart TS Server`.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/select-typescript-version"
  alt="Select TypeScript Version in the command palette in VS Code"
/>

### Restart the ESLint server process

On occasion I'll also need to restart the ESLint server process. Just like it sounds, this is the process that analyzes your code for linting errors, according to the rules specified in your project's `.eslintrc` file and the version of ESLint that is specified in your project's `package.json` file.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/restart-eslint-server"
  alt="Restart ESLint Server in the command palette in VS Code"
/>

## If that doesn't work, I'm out of ideas

..and by that, I mean I'm still learning. There's loads to learn about TypeScript, and I've found quite a few great resources online from devs like me who have shared their experiences and knowledge. I hope this article helps you - and if you're looking for more, check these out:

- Kent C. Dodds has a great article called [Using fetch with TypeScript](https://kentcdodds.com/blog/using-fetch-with-type-script) which I nearly have memorized at this point. This is the problem I was trying work through when I discovered that I needed to restart the TS server process in VS Code.
- [James Q. Quick](https://www.youtube.com/@JamesQQuick) has a great YouTube channel where he shares tips and tutorials for building web apps with a wide variety of frameworks and technologies.
- I've got some more articles on working with TypeScript in VS Code, including [Refactoring TypeScript React components in VS Code](https://mikebifulco.com/posts/refactoring-typescript-react-components-vscode#resources-for-learning-typescript)


Steps I take to fix stubborn TypeScript errors in VS Code


## Extracting types from a JavaScript object

I am brand new to TypeScript, and far from an expert. So far, I really enjoy using it to build React apps with Next.js. As I'm growing the skills I'll need to be a better TypeScript developer, I'm finding that a fairly typical chore for me is to refactor my code to extract types from a JavaScript object. For example, I often find myself writing code in react components that looks a lot like this:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};

export default PageLayout;
```

There is no type-checking going on in this code as it is written. I've been writing react with good ol' plain JavaScript for so long that creating components like this is reflexive for me. I'm not even thinking about it.

Eventually during implementation I get to the point where adding some complexity to the component requires me to add some type-checking. At that point, I usually refactor the component to lambda syntax, and add a type annotation to the component:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};

export default PageLayout;
```

Next, I'll add a type annotation to the `children` prop:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }: { children: React.ReactNode }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Taking it a step further, I'll give the function a return type signature, using `React.FC` and generics to define the props:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Up to this point, I don't really mind the way this component was written in any of the previous refactors. It's clearly getting more complex, but I can still understand what's going on. But what if I wanted to add a `variant` prop to the component? I'd have to add another type annotation to the function signature:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout: React.FC<{
  children: React.ReactNode;
  variant: 'dark' | 'light' | 'black' | 'tan';
}> = ({ children, variant }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header variant={variant} />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Even with a little prettier formatting, this is getting a little hard to read. This is where I usually extract the props into a type, and then use that type in the function signature:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

type PageLayoutProps = {
  children: React.ReactNode;
  variant: 'dark' | 'light' | 'black' | 'tan';
};

type PageLayout = React.FC<PageLayoutProps>;

const PageLayout: PageLayout = ({ children, variant }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header variant={variant} />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Now _this_ I like! The props for this page are defined in a single place, and the function signature is much easier to read.

## Using VS Code's refactor menu to extract types

As it works out, VS Code has loads of functionality to make this sort of work quicker. The refactor menu can be accessed by highlighting some code, right clicking on it, and selecting `Refactor...`. There are a number of TypeScript-specific functions provided which can help you refactor your code.

In this case, we can extract types from our component's signature in a few steps:

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-1"
  alt="VS Code Screenshot: Select the entire `React.FC<` return type and right clicking on it"
  caption='Select the entire `React.FC<` return type and right click on it, and Choose "Refactor..." from the context menu.'
/>

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-2"
  alt="VS Code Screenshot: Choose 'extract type to type alias' from the refactor menu"
  caption='Select "Extract type to type alias" to extract the type into a type alias'
/>

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-3"
  alt="VS Code Screenshot: Give the extracted type a name, and hit enter."
  caption="Give the extracted type a name, and hit enter."
/>

## Bonus: Add JSDoc comments to your types for better intellisense

If you want to take it further, you can add a JSDoc comment to the type definition to add some documentation. This is a good way to document your code, and it's also a good way to get better intellisense for your code if it's supported in your editor:

```tsx
import Footer from "@components/Footer";
import Header from "@components/Header";

type PageLayoutProps = {
  children: React.ReactNode;
  variant: "dark" | "light" | "black" | "tan";
};

/**
 * The PageLayout component is used to wrap all pages in the application.
 * It provides a consistent header and footer, and a consistent layout for
 * the page content.
 * @param {object} props
 *   @param {React.ReactNode} props.children - The page content
 *   @param {"dark" | "light" | "black" | "tan"} props.variant - The color variant for the page
 * @returns {JSX.Element}
 **/
const PageLayout: PageLayout = ({ children, title }) => {

  /* etc */
```

## Don't learn TypeScript, just use it

...and by that I mean that TypeScript is a _great_ enhancement to building things with JavaScript, but you do not need to be an expert on TypeScript to use it by any means. I've been starting to use TypeScript more and more in my projects, and I've found that I can get a lot of mileage out of it without having to learn every single detail about it.

Theo from [t3.gg](https://t3.gg) has a great video that sums up my learning strategy for TypeScript pretty well, called Don't Learn TypeScript. I highly recommend watching it, or putting it in your queue for your next coffee break:

<YouTube youTubeId="kRiD6ZpAN_o" />

## Resources for learning TypeScript

As I mentioned, I'm fairly new to TypeScript - I only just started using it in the past few months. If you're learning TypeScript and are looking for some great places to learn, check these out:

- [Matt Pocock's YouTube channel](https://www.youtube.com/@mattpocockuk) is a library of really interesting videos about TypeScript. He shares tutorials as well as experience-driven, nuanced opinions about TypeScript (_when should I use an interface instead of a type?_ etc). IMO he's the defacto expert on TypeScript in real life.
- [TypeScript Course](https://www.typescriptcourse.com/) is a fantastic _free_ email course from [Joe Previte](https://jsjoe.io) [(@jsjoeio)](https://twitter.com/jsjoeio). It's a to learn TypeScript a little bit at a time.
- [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/) is just what it sounds like - a thorough deep dive into TypeScript. It's a free book, with an available paid course on Udemy for those who want more .
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) is the official TypeScript documentation. For better or worse, I don't think it's a great place to start, but it contains every detail you might possibly need. I've found myself coming back to it from time to time to look up specific features and to help debug this-and-that.


Refactoring TypeScript React components in VS Code


## Your about page tells the world who you are, and what matters to you

For many developers, the about page is one of the most important pages on your website. It tends to be one of the most highly-visited pages on many devs' sites. It serves as the page that will tell the world who you are, and what matters to you. It's also the page that will help you stand out from the crowd, and help you connect with your audience.

Similarly, your [GitHub profile README](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) is the first thing that people will see when they visit your profile on GitHub. I've seen many creative uses for personal GitHub profile pages, but they are most commonly used as a place to share a bio, and to connect with your audience.

They Sounds awfully similar, no?

This week, I decided that for me at least, they _should_ be one in the same. [My personal about page](https://mikebifulco.com/about) and my [GitHub Profile](https://github.com/mbifulco) contained a lot of overlapping information, but weren't _quite_ the same. My site is built with Next.js, and I use an extension of Markdown called MDX to write my content. My GitHub profile README is written in Markdown. Because of this, keeping them in sync turned out to be pretty easy.

## Setup and background

Making this setup work requires some modifications to your Next.js site, and it's important to understand how things work before you dive in. Here's a quick overview of how this setup works:

### Content flows from GitHub -> your Next.js site

In this setup, the source of truth for content on the about page will be GitHub Profile README. From the next.js site, we fetch the README and render it on the About page using a library called [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote).

So, to update our bio in _both places_, we'll edit the README file on GitHub. This will update the content on our About page, as well as our GitHub profile README.

### About next-mdx-remote

[`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote) is an npm library that provides an API for loading remote MDX files into Next.js. It allows developers to write their pages in [MDX](https://mdxjs.com/docs/), an extension of [Markdown](https://daringfireball.net/projects/markdown/) that supports embedded React components. It also provides an API for loading the MDX files from a remote URL, allowing developers to use an external CMS or content storage system to manage their page content. This is exactly what we need to sync our About page and our GitHub profile README, which is written in Markdown.

## How to sync your Next.js site About page to your GitHub README

Here's how you can set this up:

1. First, create an About page on your Next.js site. Typically, this means creating a file in the `/pages/` directory of your source code called `about.jsx` (or `about.tsx` if you're using TypeScript).

```jsx
// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

export default function About({ source }) {
  return <Layout>{/* content from GitHub will go here */}</Layout>;
}
```

2. Next, create a GitHub profile README. If you haven't done this before, Monica Powell ([@indigitalcolor](https://twitter.com/indigitalcolor)) has a great tutorial - [How to create a GitHub profile README](https://aboutmonica.com/blog/how-to-create-a-github-profile-readme). This is where you'll write your bio - and this is the file that will be synced to your About page.

3. Now you'll need to set up next-mdx-remote on your Next.js site. Once your readme is fetched from GitHub, we will use this library to serialize it as MDX -- in other words, to transform it from Markdown to renderable react components for Next.js.

If you don't already have it installed, you can install it with npm, yarn, or pnpm.

```bash {1,3-5}
npm install next-mdx-remote
# or
yarn add next-mdx-remote
# or
pnpm add next-mdx-remote
```

4. Next, we need to grab the raw Markdown from our GitHub README, and feed it into next-mdx-remote. I chose to do this in getStaticProps, which means it will be fetched and rendered once when my site is built, and then cached. This is fine for my use case, but if you're updating your about page frequently, you may want to use getStaticProps instead, to fetch your README on every page render.

So, back in `pages/about.jsx`:

```jsx {1,3-5}
import { serialize } from 'next-mdx-remote/serialize';

// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

// fetch personal README from github and return it as mdx in getserversideprops
export async function getStaticProps() {
  const res = await fetch(
    // replace this with your own README's raw URL (see below)
    'https://raw.githubusercontent.com/mbifulco/mbifulco/main/README.md'
  );
  const content = await res.text();

  // include mdxOptions as needed on your site
  const mdxSource = await serialize(content /*, mdxOptions */);

  return {
    props: {
      mdxSource,
    },
  };
}

export default function About({ source }) {
  return <Layout>{/* content from GitHub will go here */}</Layout>;
}
```

To get the raw URL for your README, go to your GitHub profile, and click on the README file. Then, click the "Raw" button in the top right corner of the file. Copy the URL from the address bar, and replace the URL in the code above with your own.

5. Finally, you can render your README in your About page using MDX Remote.

```jsx
import { MDXRemote } from 'next-mdx-remote';
import { serialize } from 'next-mdx-remote/serialize';

// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

// If you want to have MDX render custom components, you can import them here
import { components } from '~/utils/mdx-components';

export async function getStaticProps() {
  // fetch personal README from github
  const res = await fetch(
    // replace this with your own README's raw URL
    'https://raw.githubusercontent.com/[YOUR_USERNAME]/[YOUR_USERNAME]/[YOUR_DEFAULT_BRANCH]/README.md'
  );
  const content = await res.text();

  // include mdxOptions as needed on your site
  const mdxSource = await serialize(content /*, mdxOptions */);

  // pass the mdxSource to the page component in props
  return {
    props: {
      mdxSource,
    },
  };
}

export default function About({ mdxSource }) {
  return (
    <Layout>
      {/* note: passing in components is optional */}
      <MDXRemote {...mdxSource} components={components} />
    </Layout>
  );
}
```

Bingo bango, we're there! Now, whenever you update your README, your About page will reflect those changes the next time your site is built. If you'd like to see how [the about page for my site](https://mikebifulco.com/about) is implemented, you can check out the [source code on GitHub](https://github.com/mbifulco/blog/blob/main/src/pages/about/index.js), since it's all Open Source!

## More Next.js goodness

If you enjoyed this post, you might want to check out some of my other [articles on next.js](https://mikebifulco.com/tags/nextjs) :

- [Publish newsletters to your Next.js site with ConvertKit API](https://mikebifulco.com/posts/publish-your-newsletter-with-convertkit-api-next-js)
- [What it's like to migrate a high-traffic website from Gatsby to Next.js](https://mikebifulco.com/posts/migrate-gatsby-to-nextjs-apisyouwonthate-com)
- [https://mikebifulco.com/posts/mdx-auto-link-headings-with-rehype-slug](https://mikebifulco.com/posts/mdx-auto-link-headings-with-rehype-slug)


Sync your About page and your GitHub bio on your Next.js site


## I publish a newsletter called Tiny Improvements

[My little newsletter](https://mikebifulco.com/newsletter) is all about making small, incremental improvements to your work and home life, especially if you're building a product or company. I've been publishing it for a while now, and I've been using ConvertKit to manage my subscribers and send out the newsletter.

<Aside>

Note: This is a follow-up to my [previous post on using ConvertKit with Remix](https://mikebifulco.com/posts/publish-your-newsletter-with-convertkit-api-remix). If your site is built using [**Remix.run**](https://remix.run), you'll probably want to head over there.

</Aside>

In this post, we'll go over how I use the ConvertKit API to publish a newsletter page for a site built with [Next.js](https://nextjs.org).

## Publish past issues to grow your newsletter

I recently started publishing back-issues of my [newsletter](https://mikebifulco.com/newsletter) to my site, so that I can share them as evidence of the type of writing I do. In addition to being SEO-indexable, it allows me to share the newsletter with people who aren't subscribed to it, with a link to subscribe at the bottom of each issue.

I wanted to explore a way to make _my_ process incrementally better, by using the [ConvertKit API](https://developers.convertkit.com/) to automate the publishing process with the same workflow that I use to send newsletters to subscribers.

## Using the ConvertKit API to publish newsletters to a Next.js site

Setting up an automated newsletter page is fairly simple, at least in theory:

1. Write newsletters and send them, using ConvertKit's broadcast features (for the sake of this post, we'll use the term "newsletter" and "broadcast" somewhat interchangeably).
2. Use the ConvertKit API's list-broadcasts endpoint to query for every published broadcast, to populate a newsletter index page
3. For each published broadcast, use the ConvertKit API to get the details of that broadcast, and then render the content of that broadcast on a page.
4. For SEO purposes, add each published newsletter page to `sitemap.xml`, with all the appropriate metadata.

To get newsletters from the ConvertKit API, I set up 2 helper functions in `/src/utils/convertKit.js`. First is `getNewsletter()`, which takes a broadcast ID and returns the details of that broadcast.

```js
export const getNewsletter = async (broadcastId) => {
  const res = await fetch(
    `https://api.convertkit.com/v3/broadcasts/${broadcastId}?api_secret=${CONVERTKIT_API_SECRET}`
  );

  // rename "broadcast" to "newsletter" for consistency
  const { broadcast: newsletter } = await res.json();

  return newsletter;
};
```

The second is `getAllNewsletters()`, which returns a list of all published broadcasts. In its simplest form, this function looks like this:

```js
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();

  // rename "broadcasts" to "newsletters" for consistency
  const { broadcasts: newsletters } = data;

  return newsletters;
};
```

<Aside type="warning">

We are using an environment variable to supply the variable `CONVERTKIT_API_SECRET` - it is **super important** to keep this value secret, and not share it on the client-side of your app.

</Aside>

### Keeping your ConvertKit API Secret key safe on Next.js sites

For this example, we're using `CONVERTKIT_API_SECRET` environment variable only on the server-rendered parts of our site, because we _do not want it to be exposed to the client_. To make this value accessible only server-side, add it to a file called `.env` or `.env.local`, according to [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#loading-environment-variables). **Make sure you add `.env` and `.env.local` to your [`.gitignore` file](https://mikebifulco.com/posts/gitignore-io-is-great), so you don't accidentally commit it to your repository.**

Importantly, this environment variable should only be exposed server-side, because we _didn't_ name it with a `NEXT_PUBLIC_` prefix - to read more about using environment variables to web clients, check out [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser).

### Rendering the newsletter index page

Now that we have a way to get a list of all published newsletters, we can use that to render a page with a preview of each past issue. I created a new file called `/src/pages/newsletter/index.js` to render the newsletter index page.

On this page, we use `getStaticProps` to fetch our list of newsletters on the server, and then pass them to render function, to display a list of links to each newsletter page.

<small>

_note: I stripped out the styling/presentation code from this example to keep
it focused on data loading logic._

</small>

```jsx
import { Link } from 'next/link';
import { getAllNewsletters } from '../../utils/convertKit';

import slugify from '../../utils/slugify';

export const getStaticProps = async () => {
  const newsletters = await getAllNewsletters();

  return {
    props: {
      newsletters,
    },
  };
};

const NewsletterIndexPage = ({ newsletters }) => {
  return (
    <>
      <h1>All Newsletters</h1>
      <ul>
        {newsletters?.map((newsletter) => (
          <li key={newsletter.id}>
            <Link href={`/newsletter/${slugify(newsletter.subject)}`}>
              {newsletter.subject} - {formatDate(newsletter.published_at)}
            </Link>
          </li>
        ))}
      </ul>
    </>
  );
};

export default NewsletterIndexPage;
```

You may have noticed that I'm also using a helper function called `slugify`, which uses the npm package `slugify`. This function takes a string and returns a skewer-case-version-of-it, which is useful for creating browser-friendly URLs from strings.

```js
import makeSlug from 'slugify';

export const slugify = (string) => {
  return makeSlug(string, {
    replacement: '-',
    remove: /[\[\],?*+~.()'"!:@]/g,
    strict: true,
    lower: true,
  });
};

export default slugify;
```

This is an optional step that caused me a fair bit of heartache - the easiest way to link to individual newsletter pages is to use the broadcast ID, but I wanted to use a more human-readable URL, so I used `slugify` to create a URL-friendly version of the newsletter subject.

The downsides of this approach are:

- each newsletter _must_ have a unique URL
- there's not a way to efficiently map a URL to a broadcast ID, so we have to iterate over all broadcasts to find the one that matches the URL (which you'll see in the next section)

For now, I can live with this approach, since this computation is done once during build time, and until I have hundreds of newsletters, it shouldn't be too big of a performance hit.

### Rendering a single newsletter page

Now that we have a page listing all published newsletters, we need to create a page template to render a single newsletter. I created a new file called `/src/pages/newsletter/[subject].js` to render the newsletter index page (note, once again, that presentation and styling code is removed here for simplicify):

```jsx
import { useEffect } from 'react';
import {
  broadcastTemplateParse,
  getAllNewsletters,
} from '../../utils/convertKit';
import slugify from '../../utils/slugify';

export const getStaticPaths = async () => {
  const newsletters = await getAllNewsletters();

  return {
    paths: newsletters.map((newsletter) => ({
      params: {
        subject: slugify(newsletter.subject),
      },
    })),
    fallback: false,
  };
};

export const getStaticProps = async (context) => {
  const newsletters = await getAllNewsletters();

  const { subject } = context.params;
  const slug = slugify(subject);

  const newsletter = newsletters.find(
    (newsletter) => slugify(newsletter.subject) == slug
  );

  return {
    props: {
      newsletter,
    },
  };
};

const SingleNewsletterPage = ({ newsletter }) => {
  const { subject } = newsletter;

  return (
    <>
      <h1>{subject}</h1>
      <div
        dangerouslySetInnerHTML={{
          __html: broadcastTemplateParse({ template: newsletter.content }),
        }}
      />
    </>
  );
};

export default SingleNewsletterPage;
```

The `getStaticPaths` function is used to generate a list of all possible URLs that should be pre-rendered. In this case, we're using the `getAllNewsletters` function to fetch a list of all published newsletters, and then using the `slugify` function to create a URL based on the newsletter's subject.

The `getStaticProps` function is used to fetch the data for a single newsletter, based on the URL. We use the `getAllNewsletters` function to fetch a list of all published newsletters, and then use `newsletters.find()` to look for the newsletter whose subject line matches the URL for the current page when run through `slugify`. This uses a JavaScript API called [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), which is used to find single item in an array that matches a condition.

#### Render the body using dangersoulySetInnerHTML

To render the contents of the newsletter, we are using a scary-looking React API pattern - `dangerouslySetInnerHTML`. This is a [React API](https://reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml) that allows you to render HTML that you have received from an API, and is generally considered a security risk. However, in this case, we are using it to render HTML that we have generated ourselves, and we are at least somewhat confident that it is safe to render. Generally speaking, this is a technique that shouldn't be used unless you are confident that the HTML you are rendering is safe.

#### Helper functions for displaying ConvertKit newsletter content

We're also using 2 helper functions, which are defined in `/src/utils/convertKit.js`:

```js
import { Liquid } from 'liquidjs';
const engine = new Liquid();

export const broadcastTemplateParse = ({ template, data }) => {
  const t = template.replaceAll('&quot;', '"');
  const res = engine.parseAndRenderSync(t, data);
  return res;
};

export const newsletterHasValidThumbnail = (newsletter) => {
  const { thumbnail_url: thumbnailUrl } = newsletter;
  if (!thumbnailUrl) return false;
  if (thumbnailUrl.startsWith('https://functions-js.convertkit.com/icons'))
    return false;
  return true;
};
```

The `newsletterHasValidThumbnail` function is a helper function that checks if the newsletter has a valid thumbnail image. ConvertKit provides a default thumbnail image for all newsletters, but you can also upload your own, by adding an image to your newsletter's body. This function checks if the thumbnail is the default image, and if so, returns `false` so we can skip rendering it.

The `broadcastTemplateParse` function is a helper function that takes a newsletter template and parses it with the [Liquid](https://shopify.github.io/liquid/) templating language. This is how ConvertKit allows you to customize the HTML of your newsletter, and use dynamic data like the subscriber's name, or the date the newsletter was sent.

**An important caveat:** There are _lots_ of little cases where this might not work perfectly, due to all of the amazing things you can do with Liquid in ConvertKit. At the moment, my newsletter uses fairly basic liquid customization - this may not do the trick for you if you're using more advanced features. Please test your implementation thoroughly!

### Adding more detail to the index page

At the time of writing this post, ConvertKit's v3 API is in "active development" - and as such, it's likely not feature complete. For example, the [current API for list-broadcasts](https://developers.convertkit.com/#list-broadcasts) provides a minimal amount of data about each broadcast:

```bash
curl https://api.convertkit.com/v3/broadcasts?api_secret=<your_secret_api_key>
```

```json
{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
```

Since we want to create an index page that shows a thumbnail for each newsletter, we need to query the API for more information about each newsletter. At the moment, the best way to do this is to query the API for each newsletter individually. It's not ideal, since we need to send an API call for each newsletter shown on the index page, but I'm hoping that with a bit of feedback, ConvertKit will add more data to the list-broadcasts API endpoint.

We already have a function to query the API for a single newsletter (remember `getNewsletter` from earlier?), so we can use that to query the API for each newsletter on the index page.

#### Filter out un-published newsletters

The list-broadcasts endpoint also doesn't currently return whether or not a given broadcast was _published_ yet - which means that if you draft a future broadcast on your ConvertKit dashboard, it will still be returned by the list API. I don't want to share these yet-to-be-sent newsletters on any of my sites, so we'll add some logic to `getAllNewsletters` to filter out any newsletters that haven't been published yet.

#### Don't render newsletters with duplicate subject lines

There are some cases where I send the same newsletter multiple times, with the same subject line, to different audiences - usually because I've forgotten to include some details in the original broadcast. This results in multiple broadcasts with essentially the same content. I don't want to show these on my site, so I added some logic to deduple any newsletters that have the same subject line, displaying only the most recent one (which should be the most correct, in theory).

This is the updated code for `getAllNewsletters` in `convertKit.js`:

```jsx
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();
  const { broadcasts } = data;

  // get details for each individual newsletter
  const newsletters = await Promise.all(
    broadcasts.map((broadcast) => getNewsletter(broadcast.id))
  );

  // hackish dedupe here - sometimes we publish a newsletter a _second_ time as a correction, or to a different audience.
  // In those cases, they should always have the same subject. We're using subject as a way to deduplicate newsletters in that case
  const dedupedBySubject = {};

  // return only newsletters that have been published, and sort by most recent to oldest
  newsletters
    .filter((newsletter) => !!newsletter.published_at)
    .sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
    .forEach((newsletter) => {
      // the first one we encounter in this order will be the newest, so if there's one already we don't make any changes to the object map
      if (!dedupedBySubject[newsletter.subject])
        dedupedBySubject[newsletter.subject] = newsletter;
    });

  let nls = [];
  // iterate over the map we have of subject->newsletter, and push into a fresh array, which we'll return
  for (let subject in dedupedBySubject) {
    nls.push(dedupedBySubject[subject]);
  }

  return nls;
};
```

And with that, our basic implementation is complete - we've created a `/newsletter` page that shows a list of all of our newsletters, with a thumbnail image for each one. We've also added a `/newsletter/[subject]` page that shows the full content of a given newsletter.

## Next steps

There are a few things I'd like to add to this implementation in the future:

- I'm unhappy with the bottleneck I've created for myself using `slugify` on the subject line to create the URL slug. I'd like to find a more efficient way to do this. A reasonable fallback for now might be to use the `BroadcastId` as the slug instead of the subject line, but those aren't human-readable.
- This implementation presents some challenges for SEO - getting newsletter entries to show up in my site's `sitemap.xml` is currently done at build time, which means that new newsletters won't show up in the sitemap until I rebuild the site. In the future, I'll either need to generate the sitemap dynamically, or implement [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration) so that new newsletters are added to the sitemap as soon as they're published.
- I'm pretty diligent about [embedding opengraph metadata](https://mikebifulco.com/posts/reset-your-open-graph-embeds-on-linkedin-twitter-facebook) on the pages on my site, including images and excerpts from the article to use as previews on sites like twitter and LinkedIn. This implementation makes that tricky, as determining _which_ image to use as the cover for a given newsletter is a bit of a challenge. Right now I'm using the first image within a newsletter. I'm not sure what the best solution is here, but I'm open to suggestions!

## Wrap-up

I hope this post has been helpful to you, and that you've learned something new about how to use ConvertKit's API to create a custom newsletter index page for your Next.js site. I'd also love it if you checked out Tiny Improvements, my little newsletter about making better products and a better life - [mikebifulco.com/newsletter](https://mikebifulco.com/newsletter).

If you have any questions, or if you've found a bug in my code, please feel free to reach out to me on Twitter [@irreverentmike](https://twitter.com/irreverentmike)!


Growth hack: Publish newsletters to your Next.js site with ConvertKit API


[APIs You Won't Hate](https://apisyouwonthate.com) is a resource for developers who want to learn how to build APIs that are secure, performant, and easy to use. I've been helping to run and maintain the site since roughly the beginning of 2018, when I rebuilt it from a [Jekyll](https://jekyllrb.com/) site to a static site with [Gatsby](https://www.gatsbyjs.com/). This was a huge leap forward for the site - as we were growing the community and adding resources for API developers regularly, it became apparent that we were going to need to support some features that I wasn't really interested in building on top of Jekyll - support for multiple authors, an image optimzation solution.

## Why we chose to move away from Gatsby

So, I built the site with Gatsby, as a visual clone of the Jekyll site. It worked fantastically for us, but as we added more and more articles and authors to the site, it became challenging to maintain, for a variety of reasons.

1.  **Building the site was slow**

    From a clean cache, it could take from 11-15 minutes to build, which meant that regular deployments to our hosting provider were starting to get expensive. It also meant that any debug tasks which required a production build were _intolerably_ slow, and very frustrating.

2.  **Dealing with images was challenging**

    Gatsby has an _amazingly_ clever [strategy for image optimization](https://www.gatsbyjs.com/plugins/gatsby-image/), which involves sending all images used on the site through a pre-build pipeline that makes them accessible via Gatsby's graphql API. This is a foundational part of how Gatsby sites are meant to run, and it gives plenty of options for image loading strategies and optimization approaches.

    What we never quite got right with our implementation was a strategy that would allow authors to upload images to the [apisyouwonthate.com repo](https://github.com/apisyouwonthate/apisyouwonthate.com) with a naming strategy that was sensible.

    Essentially, due to a quirk in our chosen implementation, each image _on the site_ had to have a unique name, and if two images with the same name were uploaded, it caused all kinds of problems. You can imagine that in the course of writing dozens of articles about APIs, there's more than one occasion to create an image called `devtools-network-tab.png`, or `cover.png`, etc.

3.  **Updating the site required too much understanding of Gatsby's underlying platform**

    This basically meant that of the three of us who maintain the site, I was the only one equipped to make significant changes, because I had spent a good deal of time in my day-to-day job building prototypes with Gatsby for [Gymnasium](https://thegymnasium.com). When either of my teammates wanted to make changes to the site, they had a choice: spend hours and hours trying to figure out how the site was configured, struggle to make changes, and submit a PR, _or_ create an issue on GitHub and assign it to me to fix. You can probably guess which happened more often - and looking back, it makes total sense.

4.  **Some lugnut\* had used boostrap to design the layout for the site.**

    <small>

    (\*It was me.)

    </small>

    I used bootstrap out of convenience, and hamfisted it into working with our React site using a couple of libraries and band-aids to get it all "working" properly. This resulted in a near-infinite supply of teeny tiny little layout bugs. These would be fantastic if I needed them for job security... but in practice they were relentless headaches.

## So, what did we gain from moving to Next.js?

Let me be the first to tell you that it's _highly_ likely that everything I accomplished in the site rebuild with Next.js is _possible_ with Gatsby (or your favorite framework). This rebuild sets the stage for a number of features to come, and should make it easier for us to collaborate with new authors, iterate on site designs, and add small features without having to suffer a 10+ minute CI process.

This rebuild gave me a chance to add features, and add some meaningful updates which had been on my plate for quite a long time. Here's a quick summary of some of my favorite features of the new site:

### SEO features

For the first time ever, **Open Graph Images** are embedded correctly across the site - the site uses a fairly simple strategy, grabbing a predetermined cover image of just-the-right-size and embedding that in the header of each page using [Open Graph metadata](https://mikebifulco.com/posts/reset-your-open-graph-embeds-on-linkedin-twitter-facebook).

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/og-embeds-work"
  alt="An APIs You Won't Hate article shared on twitter now includes the cover image for the post"
  caption="Rich Open Graph embeds get much more traffic from twitter than the alternative."
/>

We've also got fairly fine-grained control of other SEO metadata, including author names, article titles, and descriptions. Our new implementation will allow us to set Canonical URLs for articles crossposted to APIs You Won't Hate from other sources as well, which makes for better SEO all around. This may also help down the line if we want to add sponsored posts to the site which point to another origin as the canonical home for the information we share.

Want to see how it works? Dive into the [SEO component in the site's source code](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/components/SEO/SEO.js).

### Contact form & Newsletter signup

We had previously been using [Netlify Forms](https://www.netlify.com/products/forms/) for the site's contact form, but since the new site is hosted on Vercel, that is no longer possible. We're now using [Airtable's API](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/pages/api/contact/index.js) for the form, which lets us collate all submissions into one place. New entries to this form trigger a routine which notifies site owners that we got a message. We then use Airtable to track responses, and make sure that nothing gets lost in the mail.

This is all made possible by Next.js API routes. These are serverless functions that are magically deployed to the cloud for any route at `/pages/api/[slug]`. We use a similar approach for our Newsletter signup form, which adds contacts to a list on mailjet. You can check out the [API code here](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/pages/api/newsletter/index.js), and the [newsletter form code here](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/components/NewsletterForm/NewsletterForm.js).

### Lighthouse scores

Our Lighthouse scores _shot up_ with this reimplementation - and while they're a moving target for a variety of reasons, performance on the site is generally really great. This is helped immensely by [Next.js's Image component](https://nextjs.org/docs/basic-features/image-optimization), which uses a variety of web standards and recommended practices to load the right-size image depending on readers' given device and browser.

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/lighthouse-scores"
  alt="Lighthouse scores for APIs You Won't Hate: 95 Performance, 100 Accessibility, 100 Best Practies, 100 SEO"
  caption="Near-perfect lighthouse scores were far easier to land thanks to our use of Next.js Image Optimization"
/>

### Search Performance

One of the most important litmus tests available for our site's general performance comes from Google's Search Console. Thankfully, since the site was deployed, we've seen consistent traffic on across all of our pages, with a slight-but-steady increase week to week:

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/search-results"
  alt="Search Console traffic for APIs You Won't Hate"
  caption="Search Console traffic for APIs You Won't Hate"
/>

Next also made it _far_ easier to generate a `sitemap.xml` for APIs You Won't Hate. In Gatsbyland, we needed to use [`gatsby-plugin-sitemap`](https://www.gatsbyjs.com/docs/how-to/adding-common-features/creating-a-sitemap/), which _is_ configurable, but is generated at _build time._ This meant that debugging sitemap changes took a full 10min+ for _each change_ - which was completely untenable for us.

By contrast, our [sitemap implementation with Next.js](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/next-sitemap.js) uses a library called [next-sitemap](https://github.com/iamvishnusankar/next-sitemap). It is _also_ generated at build time, but in a local dev environment builds take only a few seconds, allowing me to nail our sitemap much more quickly.

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/sitemap"
  alt="Google Search Contole's Sitemap ingestion for APIs You Won't Hate"
  caption="Once everything was right, we pointed Google Search Console to the new sitemap, and verified that everything was working correctly."
/>

### Visual redesign

Because this implementation work gave me an opportunity to rip out the old site's visual design, I was able to make some sorely changes to the site's overall look and feel. I removed Bootstrap and `react-bootstrap`, and used [Chakra UI](https://chakra-ui.com/) for layout building instead. There's a bit of a learning curve with Chakra (like any other UI library), but now that I'm familiar with it, I can build new responsive site pages efficiently and reliably.

Here's some side-by-side comparisons of the old and new site:

**Home Page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/home-before"
    alt="Old home page design for apisyouwonthate.com"
    caption="Home page: before"
  />
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/home-after"
    alt="New home page design for apisyouwonthate.com"
    caption="After"
  />
</SimpleGrid>

**Book feature page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/book-before"
    alt="Old Book feature page for apisyouwonthate.com"
    caption="Book feature page: before"
  />

  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/book-after"
    alt="New book feature page for apisyouwonthate.com"
    caption="After"
  />
</SimpleGrid>

**Blog landing page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/blog-before"
  caption="Old blog landing page for apisyouwonthate.com"
  alt="Blog landing page: before"
/>

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/blog-after"
  caption="New blog landing page for apisyouwonthate.com"
  alt="After"
/>
</SimpleGrid>

## Summary

We've been up and running on Next for a few months now, and everything has been working smoothly. I'm really happy with how this implementation work went, and am really lucky to be able to have a wealth of choices in amazing developer communities that surround JAMstack and SSG tools. Having now built sites and companies with create-react-app, Gatsby, next.js, and Remix Run (keep an eye out for this one!) -- I can say with a high degree of confidence that they are _all_ super tools. You can get your work done in any one of these libraries - often the challenge we face as developers is sticking with our bets long enough to see them through.

Keeping [APIs You Won't Hate](https://apisyouwonthate.com) running and growing has been a forcing function to build a site that is performant and dependable, and affects a large-scale audience... for me, that's more than enough to motivate the work it takes to keep the site running. The community we've built and the knowledge we're sharing are truly fantastic, and it's my privilege to build real sites that people (hopefully) don't hate.


What it's like to migrate a high-traffic website from Gatsby to Next.js


## Why you should link to headings in your articles

You may have come across this pattern in articles and posts on sites you frequent - article headings (think `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, and `<h6>` in html) will be be wrapped in links that point to themselves. This allows readers to link to _specific_ headings in your articles, jumping to relevant bits of content without forcing someone to read through an entire article. Generally speaking, it will look something like this:

```html
<a href="#some-unique-id">
  <h1 id="some-unique-id">My first blog post</h1>
</a>
```

The `<a>` tag here has an `href` value of `#some-unique-id` - this is the id of the heading tag. This is based on an HTML [standard defined by the W3C](https://www.w3.org/TR/html401/struct/links.html#h-12.2.3). In short, you can link to any element on an HTML page which has a unique `id` attribute defined, by appending `#[id]` to the end of the URL, like `www.example.com#id-of-the-element`.

## This is tricky with Markdown and MDX

In most static site generators and JAMStack frameworks which allow you to use Markdown and MDX to generate content, the goal is simple: give authors a _very_ simple way to author content using Markdown syntax. The unfortunate side effect in this case is that there's not a way to specify IDs for the headings in Markdown posts (at least, not one that I'm aware of).

A sample markdown post might look like this:

```md
---
title: Hello, world
---

# A fish called wanda

In this essay, I will explain the difference between...
```

This results in the following output:

```html
<h1>A fish called wanda</h1>
<p>In this essay, I will explain the difference between...</p>
```

Fantastic! That's a nice, easy way to write, but there's not a way to add an id to the heading tag. At least, not out of the box. This is where MDX's plugins come in handy.

## Automatically linking to headings in your mdx posts with rehype plugins

> _Note: This tutorial assumes you're using MDX with NextJS, althought it may be applicable to other systems. Feel free to [send me](https://twitter.com/irreverentmike) any hurdles you encounter with other frameworks, and I'll try to document them here._

### Step 1: Generate IDs for all headings automatically with rehype-slug

[`rehype-slug`](https://github.com/rehypejs/rehype-slug) is a plugin that works with MDX, and will automatically generate IDs for your headings by generating a slug based on the text they contain.

1. Install `rehype-slug` in your project by running `npm install --save rehype-slug` or `yarn add rehype-slug`

2. Add `rehype-slug` to the list of rehype plugins MDX uses. In the case of next.js sites, it is likely wherever you call `serialize()` from `next-mdx-remote`.

```jsx
import rehypeSlug from 'rehype-slug';

// ...

const options = {
  mdxOptions: {
    rehypePlugins: [
      rehypeSlug, // add IDs to any h1-h6 tag that doesn't have one, using a slug made from its text
    ],
  },
};

const mdxSource = await serialize(post.content, options);

// ...
```

**Note:** My site uses `serialize()` in several places, so I extracted `options` to its own file. This avoids repeated code, and allows me to manage my plugins for MDX from one place.

At this point, if you fire up your dev environment, and use your browser devtools to inspect any of the headings generated from markdown for your site, they should all have an `id` property added. For the example above, you'd see:

```html
<h1 id="a-fish-called-wanda">A fish called wanda</h1>
```

We're halfway there - you can now link to `www.example.com#a-fish-called-wanda`, and the browser will automatically scroll to the heading.

### Step 2: use MDXProvider to customize the way heading tags render

[MDXProvider](https://mdxjs.com/docs/using-mdx/#mdx-provider) is a wrapper component which allows you to customize the way your MDX renders by providing a list of `components`.

This step will depend heavily on the UI frameworks you've chosen for your site - I use [Chakra UI](https://chakra-ui.com/) for my nextjs site, but you can use whatever you like - [tailwindcss](https://tailwindcss.com/), [Material UI](https://mui.com/), etc will all have similar parallels.

Here's a simplified version of the code, which I'll show just for `<h1>` - you'd want to extend this for all title tags, i.e. `<h1>` through `<h6>`:

```jsx
import Link from 'next/link';

const CustomH1 = ({ id, ...rest }) => {
  if (id) {
    return (
      <Link href={`#${id}`}>
        <h1 {...rest} />
      </Link>
    );
  }
  return <h1 {...rest} />;
};

const components = {
  h1: CustomH1,
};

// this would also work in pages/_app.js
const Layout = ({ children }) => {
  return <MDXProvider components={components}>{children}</MDXProvider>;
};
```

### Doing it with Chakra UI

Like I mentioned above, my site uses Chakra UI to compose page layouts. I've added a bit of customization to links on my site - including a hover behavior which adds a nice `#` character before headings when they're hovered over. If you're curious about [my implementation](https://github.com/mbifulco/blog/pull/577) with Chakra UI, it looks a bit like this:

```jsx
import NextLink from 'next/link';
import { Link, Heading } from '@chakra-ui/react';

const CustomHeading = ({ as, id, ...props }) => {
  if (id) {
    return (
      <Link href={`#${id}`}>
        <NextLink href={`#${id}`}>
          <Heading
            as={as}
            display="inline"
            id={id}
            lineHeight={'1em'}
            {...props}
            _hover={{
              _before: {
                content: '"#"',
                position: 'relative',
                marginLeft: '-1.2ch',
                paddingRight: '0.2ch',
              },
            }}
          />
        </NextLink>
      </Link>
    );
  }
  return <Heading as={as} {...props} />;
};

const H1 = (props) => <CustomHeading as="h1" {...props} />;
const H2 = (props) => <CustomHeading as="h2" {...props} />;
const H3 = (props) => <CustomHeading as="h3" {...props} />;
const H4 = (props) => <CustomHeading as="h4" {...props} />;
const H5 = (props) => <CustomHeading as="h5" {...props} />;
const H6 = (props) => <CustomHeading as="h6" {...props} />;

const components = {
  h1: H1,
  h2: H2,
  h3: H3,
  h4: H4,
  h5: H5,
  h6: H6,
};

// ...etc - components is passed to MDXProvider in my Layout component
```

## The Result

The result is what you see on [this page](/posts/mdx-auto-link-headings-with-rehype-slug#automatically-linking-to-headings-in-your-mdx-posts), and any of the other posts on my site! Every heading on my markdown pages contains an ID, and is wrapped in a link to itself. This makes it easy for readers to tap on the link to send it to their URL bar, or to right-click/long-press and copy a link to the part of the article they want to link to.

The final markup looks a bit like this:

```html
<a href="#a-fish-called-wanda">
  <h1 id="a-fish-called-wanda">A fish called wanda</h1>
</a>
```

I hope you found this helpful! If you run into any trouble, feel free to [drop me a line on twitter](https://twitter.com/irreverentmike). Beyond that, I'd love it if you shared this post with someone who you think could benefit from it.

## Auto-linking headings with other frameworks

- Generic **HTML and JavaScript** - if you're looking for a platform-agnostic solution, you may want to check out this CSS Tricks Article, [On Adding IDs to Headings](https://css-tricks.com/on-adding-ids-to-headers/)
- **Jekyll** - a reader was kind enough to send me a tutorial for the same functionality in [Jekyll](https://jekyllrb.com/). Check it out on [David Darnes](https://twitter.com/DavidDarnes)' site here: [Adding heading links to your Jekyll blog](https://darn.es/adding-heading-links-to-your-jekyll-blog/)
- **11ty** - There doesn't seem to be a standard practice for this pattern with [11ty](https://11ty.dev/), but there was a great discussion on ways this might be implemented with plugins and shortcodes in this GitHub Issue: [Support generating IDs for headings, for section direct links ](https://github.com/11ty/eleventy/issues/1593)
- **Gatsby** - [Gatsby](https://www.gatsbyjs.org/) has a plugin which supports this behavior, called [gatsby-remark-autolink-headers](https://www.gatsbyjs.com/plugins/gatsby-remark-autolink-headers/)

## More reading

If you found this helpful, you may also be interested in:

- [JavaScript Tips: Nullish Coalescing (??)](https://mikebifulco.com/posts/nullish-coalescing-javascript)
- [JavaScript Tips: Using Array.filter(Boolean)](https://mikebifulco.com/posts/javascript-filter-boolean)
- [MDX: I should have done this sooner](https://mikebifulco.com/posts/moving-to-mdx)


#nextjs: 7 posts tagged