
## 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


This morning, I fully switched my personal site from Google Analytics to [Fathom](https://usefathom.com/) - something that I had been considering for a while, and finally decided to go all in on. Thanks to my colleagues [@andrewpmiller](https://twitter.com/andrewpmiller) and [@jeremias](https://twitter.com/jeremias) for planting this seed months ago - I'm glad I finally made the switch.

## What is Fathom?

In their words, Fathom is "simple analytics for website owners & businesses". Near as I can tell, that's a perfect distillation of what they've built. Fathom provides an easily digestible single page analytics view of your site's traffic.

It's a service that rids you of some of the heft of having Google watch you and your users' every move. They're open and transparent about being [Privacy First](https://usefathom.com/privacy) - something which has long since melted away from Google's ethos.

In addition to giving you information about the traffic coming and going from your web property, fathom also lets you set goals for your site traffic - so that you can keep an eye on performance of what matters to you. Maybe you want to see how many people are visiting your "about me" page, or track newsletter subscriptions -- with Fathom, it's a straightforward javascript call to make that happen.

## Why Fathom?

For me, the functionality it provides is perfect - [my personal site](https://mikebifulco.com) is slowly growing in traffic, which is great! I had been using Google Analytics to keep an eye on my site's traffic, but honestly - I spent a disproportionate amount of time getting lost in all of the bells and whistles of GA. That time wasn't giving me more usable insight... I was just getting lost in the tool.

I also love the idea of Privacy First tooling, which Fathom hits out of the park. When you visit my site, I'm not keeping any of your PII, or doing anything creepy with your browsing behavior. I just want to know how various articles perform, so that I can make better decisions about what to write in the future.

Another benefit was the install process - getting Fathom set up was a breeze. You may know that my site is built on [Gatsby](https://gatsbyjs.org/) - it turns out there's a reasonably well-featured [plugin for gatsby](https://github.com/lgraubner/gatsby-plugin-fathom) created by a member of the community. In addition to that, they're reportedly shipping their own plugin in the next few weeks.

<Tweet tweetLink="usefathom/status/1256954976238055424" align="center" />

<Aside>
  Note: it looks like in the coming weeks, Fathom will be providing their own
  Gatsby plugin!
</Aside>

## Looking for a free option?

**Fathom also has a self-hosted product** called "[fathom lite](https://github.com/usefathom/fathom)" which you can run yourself if you want to use their service for free. It isn't as full-featured as full blown fathom, but it will give you a good idea of what you're in for. I set it up on Heroku (using [these instructions](https://gist.github.com/gmolveau/78f88af3f5951ba6e093f93a07caa302)) for a few weeks before deciding to take the plunge and pay for Fathom's SaaS service.

## Try it yourself!

Thinking about giving it a whirl? One of the perks of being a Fathom customer is their affiliate program - you can use my link to [sign up for Fathom](https://usefathom.com/ref/DPSSYB) for a $10 discount on your first invoice. Sweet!


Why I switched to Fathom for web analytics


**Note:** This post came from my work on [Surviving Other People's APIs](https://leanpub.com/surviving-other-peoples-web-apis). I've been working on a chapter on **Async** - the content below came from that writing, but doesn't quite make sense in the context of the book. I didn't want to scrap it entirely, so it's found its way into a blog post. I'd love to know what you think!

## Plan for things to go wrong

Setting up an interface to pull data from an API asynchronously is a clear upgrade over the alternative; we're now able to update the content on a given page without reloading all of the markup and assets (images, css, etc) on the page. For better or worse, your asynchronous upgrades will also introduce some potential for things to go wrong for the people using your app. Once again, this is an opportunity to anticipate the things which might go wrong, and build fallbacks for when they do.

### Dealing with dropped connectivity

Even if you've used a hyper-modern, robust websocket-enabled API-calling technology, at some point or another, the folks using your app will lose their internet connectivity. This isn't just the canonical example of someone on a train going through a tunnel, either. Often times connectivity will go down briefly for mobile users when they switch from a cellular connection to wifi, or when they go between wifi networks, or when they lose wifi and go back to cellular.

You should test your software to make sure it will continue to work in these cases. It turns out this can be pretty easy to simulate, too - if you're on a phone, turn airplane mode on, wait a moment, and then switch it off again. On a laptop or desktop developer environment, you can switch wifi off, or disable your LAN connection. Even better, if you're using Chrome devtools, you can use their responsive tools to shut off connectivity on a single tab:

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/chrome-devtools"
  alt="Screenshot of the throttling interface in Chrome Devtools' responsive mode"
  caption="Chrome DevTools has a simple switch to shut off connectivity"
/>

Once you're able to simulate this kind of trouble, you can build out fallbacks for when things go wrong. A typical approach to this is to keep track of the result of your API call locally. If a drop in connectivity is detected, you should let the user know that it looks like they're offline. From there, you can give them the opportunity to retry the API call, and automatically retry your call when you can tell things are working correctly again.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/recover-from-offline"
  alt="Mockup of a mobile app showing a modal popup notification for when internet connectivity goes down, which takes over the entire screen."
  caption="Recovering from a dropped connection during an async save operation"
/>

Certain technologies will do the bulk of this work for you. For example, if a connectivity drop is detected, Firebase will save any API operations to a queue in the client browser's local storage, and will execute offline changes as soon as connectivity comes back. Even still, as when creating interfaces which take advantage of features like this, you should let your users know when they're offline. It's best to fully communicate what will happen when the connection comes back, too - in clear, human-friendly language.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/working-offline"
  alt="Mockup of a mobile app which informs the user they're working offline, and that changes will be sync'd when the connection comes back."
  caption="Explain clearly what will happen when the connection comes back"
/>

Note that in this case, we have the opportunity to create an interface which is a whole lot less shouty than in the last example. There's no need for the offline notice to be put in a modal window which takes up the whole screen. Colors are dialed back a bit, too - yellow is used in the example, which is much less anxiety-inducing than the-sky-is-falling-red.

As a follow-up to this, when the connection comes back, it's good practice to fire off a notification when the offline requests are completed successfully.

### Dealing with changing APIs

At some point, the APIs you're calling will change. In an ideal world, these sorts of changes are well-documented, and deprecation notices are made available months in advance of permanent changes which will break your application. It is part of your team's job to keep an eye on any services you use for breaking changes coming your way. This can be as simple as assigning a task every sprint to check for API and dependency updates.

This is a perfectly functional approach to watching out for version changes -- until it isn't. For larger applications, you may find that as you build more features which depend on a growing number of external services and dependencies, this task becomes an untenable time sink. Luckily, in many cases, there are ways to automate the process. One such tool is called [Dependabot](https://mikebifulco.com/posts/i-have-to-tell-you-about-dependabot), which is owned by the folks at GitHub.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/dependabot"
  alt="Screenshot from dependabot's marketing page"
  caption="Dependabot can be found at https://dependabot.com"
/>

Dependabot (and services like it) will keep an eye on dependency lists in your project (like `package.json` in Node projects, and `Gemfile` in Ruby projects). Once initialized, it will regularly check your dependency lists against the published versions of each library. When new versions are published, it'll open a simple pull request for each updated library, which you can review, test, and merge when ready.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/github-dependabot"
  alt="Screenshot from github.com showing a repo with automated Pull Requests, created by dependabot"
  caption="Lots of small pull requests - one for each library which has been updated!"
/>

Generally speaking, this makes the task of keeping dependencies up to date much simpler. The majority of the work can now be done by your test suites via CI - and changes can be verified by reading changelogs for each updated package.

As this becomes more common, maintainers of various libraries are getting better at posting easy-to-understand changelogs, which reduces the chances that you'll merge a catastrophic change into your project. These kinds of proactive measures should help you sleep more soundly at night.

Even still, sometimes things go wrong for one reason or another.

Maybe you merged and released a dependency update which has a breaking change to a mission critical API. Maybe one of your web page uses an API with a version set to `@latest` (!), and you wake up one day to find hundreds of help tickets from people who used to love your application. If you had been keeping an eye on server logs for your application, you may have noticed that overnight you received a spike in 4xx or 5xx errors from API calls. Be honest with yourself - how often do you proactively check server logs for errors? Don't fault yourself if the answer is less than often - most of us never check.

Once again, this is a place where automation can save the day. There is no shortage of tooling available to help you detect problems reactively just as they start, and with a nimble enough release strategy, you can minimize application downtime.

### Use error reporting to turn reactive situations into proactive messaging

Imagine this: you're in charge of an application which uses an external service to check the weather for [whatever purpose]. You've got thousands of happy users who regularly use your app to check the weather before going about their day. One day, without warning, the weather API begins sending back data in a completely different format than you'd expect - a change big enough to render your app useless.

In the old world, you wouldn't find out about this problem until help tickets and angry tweets started rolling in. At that point, it's past too-late - your beloved customers are upset, and you're the fireman who showed up after the roof collapses on your house.

We can do better than that.

There are a plethora of services available which will detect and report application crashes to you the instant they happen, so your support team can spring into action at a moment's notice. Some of these services include [Raygun](https://raygun.com/platform/crash-reporting), [Sentry](https://sentry.io/), [LogRocket](https://logrocket.com/), [Rollbar](https://rollbar.com/), and [Data Dog](https://www.datadoghq.com/). With a few lines of code, these will plug into your app, and keep an eye on network requests. When a page crashes, they'll fire off all manner of notifications - SMS, email, webhooks, Slack messages, you name it.

If you can't afford to use one of these services, or otherwise prefer not to, you can scrap together a simple one yourself. This generally looks like a wrapper function which you can use to call APIs. It should contain the logic to detect failures, and fire off whatever calls are necessary to alert your team to the problem. For teams with a small budget, the easiest approach may be using Slack's incoming webhooks feature to send a message to a channel dedicated to an application crash:

```javascript
const callApi = async ({ url, options }) => {
  try {
    // send off the API call
    const response = fetch(url, options);
    return response;
  } catch (e) {
    //something went wrong, let's notify the team!

    /* helper function to gather as much information as possible about this session, possibly including:
      - user name and contact information
      - URL or page they were visiting
      - which action caused this error
      - browser metadata ("IE7" or "Firefox 58", etc)
      - anything else that might help your support team send a thoughtful, personal response!
    */
    const metadata = getUserMetadata();

    // just what it sounds like - send a message to your team's slack channel via incoming webhook
    sendSlackWebhook({
      error: e,
      metadata: metadata,
    });

    // send the response back to the interface so you can let the user know something went wrong
    return e;
  }
};
```

These can greatly decrease your effective response time. If you're able to detect these problems and set your dev team off on a solution before users start complaining, the people using your app will feel loved. Think about how rare it is to use software and feel like the people who are making it care about you directly! If you're a small, scrappy start-up, this can really help you hang on to early customers. If you're a larger company, it means lower attrition rates, and better support ratings.

Error reporting can also help you detect crashes with user-by-user granularity. You may see crash reports coming in from a single user over and over. Reaching out to that individual to see how you can help them before they message you can honestly feel like magic. I've even had users thank me for dropping them a line and telling them I see that they're having trouble, and that I'm on the case. It's a great feeling - particularly when the alternative is a red-hot support email or a scathing tweet.

### Build a global status indicator... before you need it!

In all of the projects I work on, it's become common practice to include a global status indicator into the fundamental roots of the application. In its simplest form, this amounts to a content container that lives somewhere near the very top of every page off the application. The vast majority of the time, it sits invisible and dormant. On page load, and once every few minutes it checks our CMS for content - if something goes wrong, we use that field in our CMS to alert users to the issue, and update it regularly with easily understandable messages about resolution of the issue.

If you don't use a CMS, never fear - you can use something like GitHub Pages to host a json file which you can use for these kinds of warnings. Have your interface check the public URL of your GitHub Pages site, and if there's anything more than a blank file or object, that content can be parsed and displayed in your status indicator.

### And then?

For now, that's it! Like I mentioned, this was just an excerpt from a chapter that didn't quite fit with what I'm writing. What do you think? Is there anything you do to harden your site against failures that are out of your control?

## More reading

If you found this article useful, here's some related work I've published:

- [I have to tell you about Dependabot](https://mikebifulco.com/posts/i-have-to-tell-you-about-dependabot)
- [Run Dependabot locally](https://mikebifulco.com/posts/run-dependabot-locally)


#webdev: 3 posts tagged

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

Why I switched to Fathom for web analytics

Help your users when your web app crashes

.css-1fb0br2{color:#A0AEC0;}#webdev: 3 posts tagged

#webdev: 3 posts tagged