
## The Big Idea

When providing accurate context is make-or-break for your workflow, everyone needs to become a better writer.

We convinced ourselves that moving fast was the same as being smart. Shipping first. Reacting faster than anyone else. What we did not notice is that this trained an entire generation of builders to think only in the moment, never on the record.

That mindset worked when everything stayed in your own head. It breaks completely when your collaborators are machines. And it is the same thing your teammates have quietly been begging you to fix for years.

### Why this suddenly matters

- With LLMs and agents, context is not just helpful, it is _everything_.
- Developers are historically allergic to context. We want to skip the ticket and jump to the code.
- That habit is now actively expensive.
- Clear writing is fast implementation. Fuzzy writing creates hallucinations, bugs, and rework, and wastes time.
- If you get good at writing for agents, you automatically get better at writing for humans. Your teammates have been asking for this for years anyway - they're gonna love you for it.



## A simple framework for writing to agents (and humans, and future-you)

1. State the problem or goal. What is happening? What outcome matters?
2. Provide history. What have you already tried, seen, or ruled out?
3. List constraints. What absolutely must not break?
4. Point to the code. If you were starting, where would you look first? Any past examples or similar patterns?

Go back and re-read your instructions, and imagine this is the first time you're hearing about the bug or feature you're describing. Is there enough information for you to get the job done?

Iterate as needed. That's really all there is to it.

## A real example

I was getting spam signups to the Tiny Improvements mailing list. Dozens a day. Instead of stewing on it internally like I used to, I wrote up this description from my phone while on a plane:

```
I have been getting spam signups on my newsletter form for the past couple weeks - can you read through `SubscriptionForm.tsx` and help me come up with a plan to deter spam signups?

Here are some sample subscriptions from the past few weeks that are all spam:
(list of ~50 spam signups, including the addresses, first and last names used)

Based on what I'm seeing here, I think we can probably do a few things to deter spam signups:
1. make sure the honeypot field on the form is working as expected
2. Automatically reject signups where the first name is mixed case has >3 capital letters: i.e. XavcASkiox
3. Automatically reject signups where the first name has >4 consecutive consonants: i.e. mtpDQVeZaqb

For signups that _fail_ any of our spam checks, we should make it look like the subscription was a success, but don't actually subscribe the email address, and instead log the spam signup attempt to Posthog analytics for further analysis.
```

That 90 seconds of writing turned into a working fix with minimal edits, and thankfully, spam fell off a cliff.

And bonus: writing it down cleared background mental noise I did not realize I was carrying.

## Conclusion

If context is now make-or-break, writing is no longer optional - it's the difference between wasting your time and speeding up your workflow.

Write down what you're thinking about. It frees your brain, helps your team, and makes agents actually useful.

_And if you're the one sending automated spam signups to my newsletter: c'mon, dude._

---

### For more Context on Context

- [Matt Pocock's video on LLM Context](https://youtu.be/-uW5-TaVXu4) is a superb explainer on the topic, with a really helpful series of diagrams to help you visualize the concept.
- Michael Reeves shows what happens when you [corrupt the back-context](https://www.youtube.com/shorts/WP5_XJY_P0Q) of an LLM conversation. It's chaotic - and convincing.


The next great engineering skill is not coding

A simple framework for writing to agents (and humans, and future-you)

## Canonically Speaking: Own Your Work

You've gone through the trouble of planning, outlining, and writing an article - the product of hours (or sometimes days) of work. After publishing your work on your own site, you take the time to cross-post it on Hashnode, Medium, Dev.to, and Reddit, to get more eyes on it.

Great news: your work is a success! You're racking up likes and upvotes, and people are leaving thoughtful comments.

Some time later, you open up an incognito window, and do a Google search for your article, and it pops up!

...but wait, why is the top result Medium, and not `yourgreatwebsite.com`?

It sounds like it's time you learned about the `canonical` tag, its value for SEO, and why it matters if you're trying to build a brand for yourself, or for a product you're working on.

## What is a Canonical Tag?

The **canonical tag** is a specially formatted `<link />` tag in HTML which lets you specify the "canonical" or original version of the content on a given page. The Google crawler and other search engines use these in combination with a few other signals to determine which domain "owns" the content being shown.

In other words: **canonical tags tell search engines which URL should be considered the official home of whatever is on that page**.

### Syntax for the Canonical tag

Canonical tags go in the `<head>` section of an html page, and they look like this:

```html
<head>
  
  <link rel="canonical" href="https://www.yoursite.com/some-article" />
</head>
```

**Important:** Your page should have _only one_ canonical tag. Adding more than one can have negative or unintended effects on your search rankings!

### Some great reasons to use Canonical Tags

When your work is posted in multiple places online, canonical tags tells search crawlers which version should be considered the authoritative source.

If you cross post and don't use a canonical tag, it can lead to your poor search rankings _everywhere_ for your work. This means that even if you get a boost initially from sharing on Hashnode, Medium, or Dev.to, it can actually _hurt_ your chances to rank well in the long run.

In theory, this means that the signals search crawlers use to rank your articles (like backlinks and traffic statistics) should be attributed to the original source on your site. That's great news, because more backlinks and clicks through to your work _should_ increase visibility on search engine results pages (SERPs).

### Another benefit: Protection Against Content Theft

Eventually, your high-traffic articles will copied and republished without your permission by spammy content aggregator sites looking to build traffic for themselves.

By having a canonical tag _on your site_ from the start, and having it indexed by search engines, you ensure that these spam sites don't win by stealing your content. The canonical tag helps search engines recognize your original work and prioritize it in search results.

---

## Implementing Canonical Tags on your site

Thankfully, it's not particularly complicated to add canonical tags to your site. The long and short of it is that you need to add a `<link>` tag to the `<head>` section of your HTML pages, specifying the canonical URL of the content.

As an example here's a simple, step-by-step guide to implementing canonical tags in a Next.js site using the pages router:

### Create a New Next.js project

If you haven't already, you can create a new Next.js project by running the following commands in your terminal:

```bash
npx create-next-app@latest my-nextjs-site
cd my-nextjs-site
```

### Install the Next.js Head Component

Next.js provides a built-in `<Head />` component to help you manage the `<head>` section of your HTML. You don't need to install anything additional for this; it's already included with Next.js.

_A word of caution:_ Using a `<Head />` tag on any page in your site gives you a way to add content to the `<head />` section rendered on the final page. This is super convenient, but that also makes it easy to unintentionally include more than one of these puppies per page -- and you don't want to do that.

### Add the Canonical Tag to Your Pages

Adding the tag to a single page is straightforward - toss it between `<Head>` tags, and make sure the `href` attribute has the _exact_ same URL as this page will. **If your site pages have a trailing slash `example.com/hello/`, make sure to include it!**

```jsx
import Head from 'next/head';

export default function Home() {
  return (
    <div>
      <Head>
        <title>My Next.js Site</title>
        <link rel="canonical" href="https://www.yoursite.com/" />
      </Head>
      <h1>Welcome to My Next.js Site</h1>
    </div>
  );
}
```

You can add the canonical tag to other pages in the same way - just make sure to replace the href value with the correct, specifc URL for each page.

### Set the Canonical URL for article pages

For more complex sites, especially those with pages generated from Markdown or a CMS, you'll likely want to set the canonical URL dynamically. Here's a simplified example of how you might accomplish this using `next/navigation`:

```jsx
import Head from 'next/head';
import { useRouter } from 'next/navigation';

export default function BlogPost() {
  const router = useRouter();

  // ƒor https://example.com/articles/my-good-article,
  // this will contain something like "/articles/my-good-article"
  const path = router.asPath;

  /*
    Dynamically set the canonical URL - this needs to be an absolute URL
    so make sure to include the domain
    For example, if your site is https://www.yoursite.com
    and the path is /blog/my-post, the canonical URL would be
    https://www.yoursite.com/blog/my-post
  */
  const canonicalUrl = `https://www.yoursite.com${path}`;

  return (
    <div>
      <Head>
        <title>Blog Post Title</title>
        <link rel="canonical" href={canonicalUrl} />
      </Head>
      <h1>Blog Post Content</h1>
    </div>
  );
}
```

### Verify the Implementation

After adding canonical tags, it's essential to verify their implementation. You can use tools like [Google's URL Inspection Tool](https://support.google.com/webmasters/answer/9012289?hl=en) in Search Console to check if your pages are being indexed correctly with the canonical tag.

<Image
  publicId="posts/own-your-work-with-canonical-tags/google-search-console"
  alt="Google Search Console showing the URL Inspection Tool"
  caption="Use Google's URL Inspection Tool to verify that your pages are being indexed correctly with the canonical tag"
/>

By following these steps, you'll ensure that search engines recognize your original content, helping you build your personal brand and protect your work from content theft.

## Bonus points: set canonical URLs in places where you crosspost

Many community blogging platforms contain tools that will let you set a canonical URL on your posts. This is a step you should absolutely take when it is available - it's a way to explicitly tell crawlers that if they're crawling your article on some other site, they should consider your original site the owner.

In other words, when you post on Dev.to, you should add metadata to your post _there_ to indicate that it was _originally_ posted on `yoursite.com`.

<Image
  publicId="posts/own-your-work-with-canonical-tags/canonical-dev-to"
  alt="A recent post of mine on Dev.to showing that it is a crosspost"
  caption="If you do it right, dev.to will point right back to your original article"
/>

### FWIW: Adding canonical tags with Next.js App router

If your Next.js app is built using the App Router, implementation is slightly different, but also pretty straightforward. Next provides an API called [Dynamic Metadata](https://nextjs.org/docs/app/building-your-application/optimizing/metadata) on each page, which slurps up the output of a function called `generateMetadata` on your pages, and sticks the result in nicely formatted tags in the `<head />` of your document.

To add a canonical tag with this method, you'll do something like this:

```tsx
import type { Metadata, ResolvingMetadata } from 'next';

type Props = {
  params: { id: string };
  searchParams: { [key: string]: string | string[] | undefined };
};

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  // read route params
  const slug = params.slug;

  return {
    metadataBase: new Url('https://yoursite.com'), // Next will use this to make complete URLs from relative paths
    alternates: {
      canonical: `/articles/${slug}`,
    },
  };
}

export default function Page({ params, searchParams }: Props) {
  /* etc */
}
```

### Setting a canonical URL on Dev.to

To [set the canonical URL of a post on Dev.to](https://dev.to/p/editor_guide#front-matter), add `canonical_url` to the frontmatter of your post:

```md
---
title: Hello this is a post
canonical_url: https://yoursite.com/article/some-article`
---
```

### Setting a canonical URL on Medium

To [set the canonical URL of a post on Medium](https://help.medium.com/hc/en-us/articles/360033930293-Set-a-canonical-link), you'll use the three dot button `...` on your post and select "This story was originally published elsewhere" from the menu

### Setting a canonical URL on Hashnode

In the Hashnode editor, there's a helpful menu under _Draft Settings_ for "Are you republishing?", where you can [specify your post's canonical URL](https://support.hashnode.com/en/articles/6556971-how-to-set-a-canonical-link).

### Setting a canonical URL on LinkedIn

LinkedIn _desperately_ wants you to use their "write an article" feature to share long form content on their site. In my opinion, this is a bad idea - **LinkedIn articles do not support canonical tags** -- and IMO, this means they're trying to take credit for your work.

Instead, just share a link to your article in a regular post - it may not do as well in their feed algorithm, but at least there they'll honor your canonicals.

## Protect your work and boost your SEO with canonical tags

All told, this is a tiny amount of work to protect your IP, send search traffic your way, and build your brand. It's one of those things that many devs overlook. Building SEO traffic for your site has compounding value over time - and learning the fundamentals goes a long way.

Now get out there and add `<link rel="canonical">` to your articles, before I claim them as my own 😘

## More reading on SEO

I have [written _gobs_ about SEO for developers](https://mikebifulco.com/tags/seo) - if you liked this article, you may want to out these as well:

- [How to set up self-healing URLs in Next.js for better SEO](https://mikebifulco.com/posts/self-healing-urls-nextjs-seo)
- [3 Tiny Tips for better SEO](https://mikebifulco.com/newsletter/tiny-tips-for-better-seo)
- [SEO tools I used to grow my sites to 20k+ visitors/month](https://mikebifulco.com/posts/seo-tools-for-new-web-projects)
- [The correct semantic HTML for adding subtitles to h1 tags](https://mikebifulco.com/posts/semantic-html-heading-subtitle)

SEO for Devs: Own your work with canonical tags

Another benefit: Protection Against Content Theft

Bonus points: set canonical URLs in places where you crosspost

FWIW: Adding canonical tags with Next.js App router

Protect your work and boost your SEO with canonical tags


<small>

_note: This post is inspired by an article that my pal Josh Finnie wrote, showing [how he added JSON-LD to his Astro.js site](https://www.joshfinnie.com/blog/adding-json-ld-to-my-blog/): If you're an Astro-naut - give that a read. It's great!_

</small>

## SEO is the growth hack you're overlooking

Many devs overlook the value of SEO for their work.

I've long contended that learning a little bit about SEO can go a long way. It's in your best interest to configure your site so that Google, Duck Duck Go, and Bing know what your site is about, and what you're expert on.

In this brief tutorial, I'll share some information about Structured Data and JSON-LD, and how you can add it to your Next.js site to improve your site's SERP (Search Engine Results Page) presentation, with just a little bit of code and configuration.

## What is JSON-LD?

**JSON-LD (JSON Lightweight Linked Data format) is a metadata format** which can be added to your site to tell Google and other search engines what type of content is on each page. This can help search engines understand your content better, and can lead to better search results for your site. In reality, JSON-LD is _just_ a specific format for JSON which is human readable, and is meant to describe the content on a page in a way that search engines can understand. You can read more about it here: [https://json-ld.org/](https://json-ld.org/)

JSON-LD looks like this:

```json
{
  "@context": "https://json-ld.org/contexts/person.jsonld",
  "@id": "http://dbpedia.org/resource/John_Lennon",
  "name": "John Lennon",
  "born": "1940-10-09",
  "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}
```

### What is Structured Data?

**Structured Data is a set of search-engine specific JSON-LD templates** that search crawlers look for to understand more about the information you're sharing online. It is _optional_ for your site, but can help bring more traffic to your site by increasing the chances that your site will show up in search results.

Adding the _right_ type of Structured data to your site means that when your pages come up in someone's search results, the search engine can display more information about your site, like reviews, ratings, and other rich snippets. Ever seen a recipe or a product review in a search result? That's because of structured data.

<Image
  publicId="posts/structured-data-json-ld-for-next-js-sites/apple-cobbler"
  alt="A search result featuring apple cobbler recipes, with a star rating, time to complete, a short ingredients list, and a photo"
  caption="Structured Data can help your site show up in search results with rich snippets like this one"
/>
<br />

### Types of Structured Data

There are many types of Structured Data you can embed on your site - [Google Search Central has a list of structured data features](https://developers.google.com/search/docs/appearance/structured-data/search-gallery) which that is worth a good look. Some examples of Structured Data include:

- **Article**: For news, blog, and other article pages
- **Events**: Showcases events like concerts, festivals, and other happenings
- **FAQ**: Make your FAQ page more discoverable
- **Product**: Details and information about a product you're selling
- **Recipe**: Ingredients, cook time, and other details about a recipe
- **Review Snippet**: A review of a product, service, or other item
- **Video**: For pages that showcase video content

Each of these formats are slightly different in content, but they use JSON-LD to describe the content in a way that search engines can understand. By way of example, this is the Structured Data for a post on my site about a livestream I did demonstrating [how to build a site with Astro, TypeScript, and React](https://mikebifulco.com/posts/live-astro-content-driven-website-rebuild):

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "VideoObject",
    "name": "Rebuilding an open source content-rich site with Astro, TypeScript, and React",
    "description": "A YouTube live coding stream, learning to build content-driven sites with the Astro Web Framework.",
    "thumbnailUrl": "https://i.ytimg.com/vi/wyJYInvZya8/hqdefault.jpg",
    "uploadDate": "2024-03-23T00:00:00.000Z",
    "contentUrl": "https://www.youtube.com/watch?v=wyJYInvZya8",
    "embedUrl": "https://www.youtube.com/embed/wyJYInvZya8",
    "duration": "PT1M33S"
  }
</script>
```

Not too bad, right? This JSON-LD tells Google that this page is a video, and gives Google some information about the video, like the title, description, and thumbnail. In theory, if someone searches for the title of the video, Google might show this video in the search results, with a thumbnail and a link to the video.

Once you've got Structured Data embedded on your site, you can verify that it's working using [Schema.org's Structured Data Testing Tool](https://validator.schema.org/):

<Image
  publicId="posts/structured-data-json-ld-for-next-js-sites/schema-org-validator"
  alt="Schema.org's Structured Data Testing Tool showing that my video structured data is valid"
/>

Similarly, you can use [Google's Rich Results Test](https://search.google.com/test/rich-results):

<Image
  publicId="posts/structured-data-json-ld-for-next-js-sites/rich-results-test"
  alt="Google's Rich Results Test showing that my video structured data is valid"
/>

If you want to poke around yourself, check out the [results for the video example above](https://search.google.com/test/rich-results/result?id=K92cqPpaYa6TcdmYuVrIzQ).

Pretty cool! So - now let's talk about how it's done.

## Adding Structured data to your Next.js site with JSON-LD

My site is built with Next.js - the articles you read here are written in an extension of Markdown called [MDX](https://nextjs.org/docs/pages/building-your-application/configuring/mdx), and the site is statically generated.

When I publish an article that features a YouTube video, I add frontmatter to the MDX file for the article that contains the ID of the video, and then I use that ID to generate the JSON-LD for the video.

Again, for the page above, that looks like this:

```mdx
---
title: 'Rebuilding an open source content-rich site with Astro, TypeScript, and React'
excerpt: A YouTube live coding stream, learning to build content-driven sites with the Astro Web Framework.
date: 2024-03-23
tags: [video, nextjs, typescript, astro]
coverImagePublicId: posts/live-astro-content-driven-website-rebuild/cover
slug: live-astro-content-driven-website-rebuild
youTubeId: wyJYInvZya8
---

OpenApi.tools is an Open Source yada yada yada
```

Google provides an npm package called [schema-dts](https://www.npmjs.com/package/schema-dts) which contains types and helpers for generating JSON-LD. Start by installing this package:

```sh
npm install schema-dts
# or with pnpm
pnpm install schema-dts
# or with yarn
yarn add schema-dts
# or with bun
bun add schema-dts
```

Then, import the package and use it to generate a typed variable to contain a VideoObject's schema:

```tsx
import type { VideoObject, WithContext } from 'schema-dts';

let videoStructuredData: WithContext<VideoObject> | undefined = undefined;
```

<small className="text-xs">

**Shout out** to redditor [/u/AdrnF](https://www.reddit.com/r/nextjs/comments/1ccr79j/comment/l172n31/) for the tip. I didn't know this npm package existed!

</small>

Next, we'll need to populate this variable with the appropriate data for the schema. In my case, I'm using the `youTubeId` from the frontmatter to generate the JSON-LD for the video, like this:

```tsx
let videoStructuredData: VideoStructuredData | undefined = undefined;

if (youTubeId) {
  videoStructuredData = {
    '@context': 'https://schema.org',
    '@type': 'VideoObject',
    name: title,
    description: excerpt,
    thumbnailUrl: `https://i.ytimg.com/vi/${youTubeId}/hqdefault.jpg`, // this is the thumbnail for the video straight from youtube
    uploadDate: new Date(date).toISOString(),
    contentUrl: `https://www.youtube.com/watch?v=${youTubeId}`, // this is the URL for the video on youtube
    embedUrl: `https://www.youtube.com/embed/${youTubeId}`, // this is the URL for the video embed on youtube
    duration: 'PT1M33S', // this is the duration of the video

    /*
        note that I'm not using the entire VideoObject schema here, but
        you could add more fields if you wanted to, like interactionStatistic
        and regionsAllowed:
      */

    // interactionStatistic: {
    //   '@type': 'InteractionCounter',
    //   interactionType: { '@type': 'http://schema.org/WatchAction' },
    //   userInteractionCount: 0,
    // },
    // regionsAllowed: ['US'],
  };
}
```

Once this object is created, I serialize it to a string and add it to a `<script>` tag on the page - depending on when and where you generate it, you can stick this in the `<head>` of your page, or right in the body of the document, like I do:

```tsx
// snip -

return (
  <>
    {videoStructuredData && (
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(videoStructuredData),
        }}
      />
    )}
    <article>{/* page content goes here */}</article>
  </>
);
```

When the page is generated, you can inspect the source and see the JSON-LD embedded in the page - as in the example above.

You can double-check that your Structured data is valid using one the [Schema.org Structured Data Testing Tool](https://validator.schema.org/) before publishing by copy/pasting the generated HTML for your pages into the "code snippet" tab. Once you're happy with it, you can publish your article and you're good to go!

Job done. Google's crawler will see this JSON-LD and use it to understand the content on your page better, and you'll be on your way to better search results.

## Embed your Structured data server-side for best results

Embedding this information on in your articles in Next.js only takes a few steps, but it's critical that you do this _server-side_ to give google the best chances of seeing it. I'm using the Next.js `/pages` directory for my site -- articles are generated statically using `getStaticPaths` and `getStaticProps`, which means that the JSON-LD is generated at build time.

If you use the _App Router,_ you'll want to make sure that you embed your JSON-LD using a React Server Component (RSC), not using a client-side script.

If you're using a CMS, you'll want to make sure that the JSON-LD is generated when the page is statically rendered, and not when the page is loaded in the browser.

## Challenges with structured data

It's worth mentioning here that even if the schema validators can read your JSON-LD, it doesn't guarantee that Google will use it in search results. Google's search algorithms are complex, and they use many signals to determine what to show in search results.

I've been tweaking the implementation of Video structured data on posts like the one above, because the Google Search Console has been showing me that the structured data is valid, but it's not showing up in search results as a video:

<Image
  publicId="posts/structured-data-json-ld-for-next-js-sites/search-console-hates-me"
  alt="Google Search Console showing that my video structured data is valid, but not showing up in search results"
  caption="Google's crawler thinks my video isn't the main content of the page."
/>

There's still some work to do here, but I'm confident that with some more tweaking, I'll be able to get this working. If you know more about this, I'd love to hear from you! Drop me a line on [Threads @irreverentmike](https://threads.net/@irreverentmike) or email me <a href="mailto:hello@mikebifulco.com">hello@mikebifulco.com</a>.

These rules are always changing, and keeping up with them is a fulltime job in itself. Nonetheless, adding structured data to your site is a good practice, and can help your site show up in more search results -- even if you can't control exactly how it shows up.

## Keep adding Structured Data to your site

Now's your turn - go give it a shot. You may want to start with something like the [Profile Page](https://developers.google.com/search/docs/appearance/structured-data/profile-page) structured data format, or by adding one for [Articles](https://developers.google.com/search/docs/appearance/structured-data/article) to your posts.

For the amount of effort required, the payoff is worth it. Every little SEO boost you build into your site pays off in the long run. Think of it as an investment in the passive value of your content - the more you can do to make your content discoverable, the more likely it is to be found.

## Resources on SEO and Structured Data

As I mentioned above, this tutorial was inspired by [Josh Finnie's article on adding JSON-LD to his Astro.js site](https://www.joshfinnie.com/blog/adding-json-ld-to-my-blog/). Josh is a great developer and a good friend, and I recommend you check out his work.

I've written a few articles on SEO that you may find helpful:

- [3 Tiny tips for better SEO](https://mikebifulco.com/newsletter/tiny-tips-for-better-seo)
- [How to set up self-healing URLs in Next.js for better SEO](https://mikebifulco.com/posts/self-healing-urls-nextjs-seo)
- [SEO tools I used to grow my sites to 20k+ visitors/month](https://mikebifulco.com/posts/seo-tools-for-new-web-projects)
- [How to reset your Open Graph embed on LinkedIn, Twitter, and Facebook](https://mikebifulco.com/posts/reset-your-open-graph-embeds-on-linkedin-twitter-facebook)

And here are some tools that can help you get started with Structured Data:

- [Google's Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool)
- [Google's Rich Results Test](https://search.google.com/test/rich-results)
- [Schema.org's Structured Data Testing Tool](https://validator.schema.org/)

If you found this helpful I'd love it if you shared the article with a friend.

I'm also keen to hear from you. Drop me a line on [Threads @irreverentmike](https://threads.net/@irreverentmike) or email me <a href="mailto:hello@mikebifulco.com">hello@mikebifulco.com</a> if you think I missed anything, or if you have any questions!


Add Structured Data to your Next.js site with JSON-LD for better SEO

SEO is the growth hack you're overlooking

Adding Structured data to your Next.js site with JSON-LD

Embed your Structured data server-side for best results


OpenApi.tools is an Open Source and community-driven list of high-quality, modern tools for OpenAPI that we've been maintaining over at APIs You Won't Hate for the past few years, and it's overdue for a rebuild.

🔧 In this session, I'll be using Astro.build to recreate the openapi.tools site, with a focus on building a highly performant, maintainable, and SEO-driven experience for the next version. If i'm lucky, we'll even get into building some fun new features to help our community find the right tools for their use case with OpenAPI

I'll be building with:

- Astro: https://astro.build
- Hosting through @VercelHQ
- Visual Studio Code
- TypeScript
- React.js
- Markdown
- Fathom analytics @FathomAnalytics
- PostHog @PostHog
- Tailwind CSS @TailwindLabs

📅 Mark your calendars and join me at 10am EST for an insightful journey through the intersection of design and development. If you dig SEO and markdown, or you're a React developer, JavaScript enthusiast or TypeScript pro, or you've been curious about what Atsro brings to the table, you'll enjoy this one!

Don't miss out on this opportunity to learn, create, and connect. Be sure to subscribe and click the notification bell to stay updated on this and more exciting content from Craftwork.

For additional resources like my newsletter for founders and product builders, 💌Tiny Improvements, visit my website at https://mikebifulco.com/newsletter


Rebuilding an open source content-rich site with Astro, TypeScript, and React


Join me for an exciting live stream where we dive into the world of design and development at Craftwork! 🎨💻

🔧 In this session, we'll explore how we use a variety of image templates to elevate our software's appearance. From stylized portraits of our talented team members to vibrant paint swatches and eye-catching Open Graph (OG) preview images for our website, we'll unveil the secrets behind our visual magic.

🖌️ We'll kick things off by using the power of Figma, our design tool of choice, to craft stunning templates. Then, we'll dive deep into the development side, where we'll transform these designs into dynamically generated images. How? With the incredible Satori library and the magic of Edge Functions on Next.js, brought to you by the team at @VercelHQ .

I'll be building with:

- Satori & Next.js from @VercelHQ
- Figma
- Visual Studio Code
- TypeScript
- Tailwind CSS @TailwindLabs

📅 Mark your calendars and join us on Jan 27th at noon EST for an insightful journey through the intersection of design and development. Whether you're a React developer, JavaScript enthusiast, TypeScript pro, designer, or simply curious about UX and tech, this livestream is for you!

Don't miss out on this opportunity to learn, create, and connect. Be sure to subscribe and click the notification bell to stay updated on this and more exciting content from Craftwork.

See you there! 🚀🎉


Using Satori and Next.js to generate dynamic images


## Notes about today's Livecoding stream

This is a YouTube Livestream, where I'll be working on integrating Resend Broadcasts into my next.js site to use for sending newsletters. Resend released a new set of features this week that makes it easier to send mail to large audiences.

I'll be building with:

- Resend
- Next.js
- TypeScript
- Vercel
- Tailwind CSS

With Substack recently catching headlines for their boneheaded content moderation policies, lots of creators and developers have been looking at other tools for managing their mailing lists. Between Beehiiv, ConvertKit, Ghost, Mailchimp, and some of the other usual suspects, there are many options to choose from.

Let's take a look at Resend's new API to see how it works, and if it's a good fit for my workflow!

## Don't forget to subscribe

If you're interested in more content like this, please subscribe to my **[YouTube channel - @mikebifulco](https://www.youtube.com/@mikebifulco?sub_confirmation=1)!**


Configuring Resend Broadcasts for newsletters on my Next.js website


<small>

_note: This post is inspired by a great video from YouTuber Aaron Francis: [Make self-healing URLs with Laravel](https://www.youtube.com/watch?v=a6lnfyES-LA). For all my PHP homies - go check that video out. It's great!_

</small>

<Image
  publicId="posts/self-healing-urls-nextjs-seo/demo"
  alt="A demo of a self-healing URL made in Next.js"
  caption="Ever wonder how Amazon and Medium create self-healing URLs?"
/>

Building sites with human-readable URLs is helpful for a few reasons: it gives users a better understanding of what they're getting when they click on a link to your site, it's better for SEO, and it's more accessible (screen readers can read out the URL to the user and they can understand where they are on the site). It's also just a nice thing to do for your users... by way of example, these two URLs _feel_ dramatically different:

`https://example.com/posts/c61sca0`

vs

`https://example.com/posts/how-to-set-up-self-healing-urls-in-nextjs-for-better-seo`

The first one is a bit of a mystery box. You have no idea what you're going to get when you click on it. The second one is much more descriptive, and _hopefully_ the contents of the page match the URL.

...but, what happens if you change the title of the post? The human-readable URL is now misleading. If you're using a static site generator like Next.js, you can use the file system to create self-healing URLs that will always point to the correct page, even if the title changes.

Or, what if you're managing a larger site, where it's possible that two posts may have the same title?

These are both issues that self-healing URLs are attempting to solve.

## What are self-healing URLs?

**Self-healing URLs are URLs that allow for human-readable text, but also include a unique identifier that will always point to the correct page**, even if the human-readable text changes, or gets removed entirely.

In this post, we'll learn **how to set up self-healing URLs in Next.js.** This is something used on sites like Amazon and Medium to make sharing links a little more robust. These are URLs that allow for human-readable text, but also include a unique identifier that will always point to the correct page, even if the human-readable text changes, or gets removed entirely.

Here's the URL-pattern we're to build: `https://example.com/posts/${POST_TITLE}-${POST_ID}`.

Ultimately, we'll use the `id` of a post to identify which content to render on a page, and we'll use the `title` of the post to create a human-readable portion in the URL. As long as the URL ends with a hyphen followed by the `id`, we will redirect to the correct page, with a nicely formatted, human-readable URL.

## Self-healing URLs in Next.js with the App router

To create self-healing URLs for blog posts with the [Next.js App router](https://nextjs.org/docs/api-reference/next/router), we'll start with a fresh react app from the cli:

```bash
# with npm
npx create-next-app

# or, with yarn
yarn create next-app

# or, with pnpm
pnpm create next-app
```

Give your project a name, and select the options you want to use. I used all the defaults for this example:

```
✔ What is your project named? … next-self-healing-urls-app-router
✔ Would you like to use TypeScript? Yes
✔ Would you like to use ESLint? Yes
✔ Would you like to use Tailwind CSS? Yes
✔ Would you like to use `src/` directory? Yes
✔ Would you like to use App Router? (recommended) Yes
✔ Would you like to customize the default import alias (@/*)? No
```

You'll also need to install the `slugify` package, which we'll use to create a URL-safe slug from the post's title:

```bash
npm install slugify

# or, with yarn
yarn add slugify

# or, with pnpm
pnpm add slugify
```

### Set up dynamic routing

We'll need to add a few files to the default setup. Using the App directory, create the following directories and files:

```
app
├── posts
│   └── [slug]         // note that this is a _folder_ called [slug]. This is how dynamic routes are set up in the app router
│        └── page.tsx  // render one post
├── not-found.tsx      // this will render if someone tries to visit a post page with an id that doesn't exist in the url
├── sitemap.ts         // generate a dynamic sitemap with the _correct_ canonical URL for each post
└── utils
    └── post.ts        // types and helper functions to load posts and format URLs
```

Let's start with `post.ts`. This file contains a type definition and helper functions to load posts and format URLs.

```ts
import slugify from 'slugify';

export type Post = {
  userId: number;
  id: number;
  title: string;
  content: string;
};

export const getAllPosts = async () => {
  // fetch all posts from an example API.
  // this is just a placeholder, replace with your own data
  // shout out to https://jsonplaceholder.typicode.com/ - what a great service!
  const postsResponse = await fetch(
    'https://jsonplaceholder.typicode.com/posts'
  );
  const posts = (await postsResponse.json()) as Post[];

  return posts;
};

export const getPostById = async (id?: string | number) => {
  if (!id) {
    throw new Error('No ID provided');
  }

  if (typeof id === 'string') {
    id = parseInt(id);
  }

  const allPosts = await getAllPosts();

  const post = allPosts.find((post) => post.id === id);

  if (!post) {
    // we'll use a try/catch block around this function later
    // to redirect if a post doesn't exist with this id,
    // so make sure to throw an error here.
    throw new Error('Post not found');
  }

  return post;
};

/**
 * Converts input to a URL-safe slug
 * @param {string} title - the title of the post
 * @returns {string} a URL-safe slug based on the post's title
 */
const titleToSlug = (title: string) => {
  const uriSlug = slugify(title, {
    lower: true, // convert everything to lower case
    trim: true, // remove leading and trailing spaces
  });

  // encode special characters like spaces and quotes to be URL-safe
  return encodeURI(uriSlug);
};

// given a post, return its slug
export const getPostSlug = (post: Post) => {
  return `${titleToSlug(post.title)}-${post.id}`;
};

// given any slug, try to extract an id from it
export const getIdFromSlug = (slug: string) => slug.split('-').pop();
```

### Generate a sitemap with the correct canonical URL for each post

Let's talk SEO for a moment: Google (and other search engines) use your site's sitemap file to understand the structure of your site. This helps them index your site more accurately, and it helps them understand which pages are the most important. Next.js supports static and dynamic sitemap generation, which you can read about in their [docs on sitemap.xml](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap). Your sitemap should contain the canonical URL for every page in your site.

When Google and other search engines crawl your site, they use the Sitemap as an address book, and then visit each page found in the sitemap to analyze the content on the page, and deciding how to rank it in search results. If the URL in the address bar doesn't match the URL that Google has indexed for that page, it can cause problems with SEO. For example, if you have a page with the URL `https://example.com/foo/bar/some-url-here`, but Google has indexed the page as `https://example.com/foo/bar/some-other-url-here`, Google will think that you have two pages with the same content, and it will penalize you for duplicate content.

This is where the **canonical tag** comes in. The [canonical tag](https://ahrefs.com/blog/canonical-tags/) is a special bit of metadata that you can add to your page's `<head>` tag, which is used to tell search engines which URL is the _original URL for the content onthat page_. Ideally, the canonical URL for our blog posts should _exactly_ match the pattern we've set up for our self-healing URLs: `https://example.com/posts/${POST_TITLE}-${POST_ID}`. This is the URL that we want Google to index for each post. We'll do that by making sure we use this URL in our sitemap, and by adding a canonical tag to each post page.

A canonical tag looks like this:

```html
<link rel="canonical" href="https://example.com/foo/bar" />
```

So, this is what sitemap.ts looks like:

```ts
import { MetadataRoute } from 'next';

import { getAllPosts, getPostSlug } from '@/utils/posts';

export default async function sitemap(): MetadataRoute.Sitemap {
  const allPosts = await getAllPosts();

  let urlPrefix = 'http://localhost:3000';
  if (process.env.NODE_ENV !== 'production') {
    urlPrefix = 'https://example.com';
  }

  return allPosts.map((post) => ({
    url: `${urlPrefix}/posts/${getPostSlug(post)}`, // https://example.com/posts/this-is-a-post-1
    lastModified: new Date(), // ideally, this is the last modified date of the post
    changeFrequency: 'daily', // this will be used to determine how often pages are re-crawled
    priority: 0.7, // the priority of this URL relative to other URLs on your site
  }));
}
```

Now, if you run your app and visit `https://localhost:3000/sitemap.xml`, you should see a sitemap that includes an entry for each post, with the correct canonical URL specified.

### Setting up page.tsx: where the magic happens

In the file `app/posts/[slug]/page.tsx`, we use the [Next.js App Router's `generateStaticParams` function](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#generating-static-params) to generate URLs for all posts. This function is called at build time, and it returns an array of objects that contain the `slug` for each post. The `slug` is used to generate the URL for each post page.

Then, in the server function which renders the post page, we check whether the current URL's readable portion matches the post's actual slug. If not, we redirect to the correct URL.

We also use the [Next.js App Router's `generateMetadata` function](https://nextjs.org/docs/app/next-script#generating-metadata) to generate metadata for each post. This function is called at build time, and it returns an object that contains the `title` and `alternates` for each post. The `alternates` object contains the `canonical` URL for each post, which is used to tell search engines which URL is the correct one for each post. **This is critical for SEO purposes** - it helps Google verify that when your page loads, the URL in the address bar matches the URL that Google has indexed for that page.

```tsx
import { Metadata, ResolvingMetadata } from 'next';
import { RedirectType, notFound, redirect } from 'next/navigation';
import { isRedirectError } from 'next/dist/client/components/redirect';

import { Post, getAllPosts, getPostById, getPostSlug } from '@/utils/posts';
import { getIdFromSlug } from '@/utils/posts';

// generate URLs for all posts
export async function generateStaticParams() {
  const posts = await getAllPosts();

  return posts.map((post) => {
    const slug = getPostSlug(post);

    return {
      slug,
    };
  });
}

type PostPageParams = {
  params: {
    slug: string;
  };
};

export default async function Post({ params }: PostPageParams) {
  const id = getIdFromSlug(params.slug);

  let post: Post;
  try {
    post = await getPostById(id);
    const correctSlug = getPostSlug(post);

    // check whether the current URL's readable portion matches the post's actual slug
    if (correctSlug !== params.slug) {
      // if not, redirect to the correct URL
      const redirectUrl = `/posts/${correctSlug}`;
      await redirect(redirectUrl, RedirectType.replace);
    }
  } catch (e) {
    // this is a hack to make redirects work from within a try/catch block
    // shout out to @jeengbe on github for the tip
    // https://github.com/vercel/next.js/issues/49298#issuecomment-1537433377
    if (isRedirectError(e)) {
      throw e;
    }

    // if the post doesn't exist, return the "not found" 404 page
    notFound();
  }

  // make your post look nice IRL
  return <div>My Post: {params.slug}</div>;
}

export async function generateMetadata(
  { params }: PostPageParams,
  parent: ResolvingMetadata,
): Promise<Metadata> {
  // read route params
  const id = getIdFromSlug(params.slug);
  // fetch data
  const post = await getPostById(id);

  return {
    title: post.title,
    alternates: {
      canonical: `https://example.com/posts/${params.slug}`,
    },
  };
}
```

Another important note - _entire_ component is rendered server-side - visitors to this page won't see any content flash on screen if they enter an incorrect URL. This is huge for page performance and SEO purposes, and has traditionally been challenging while using Static Site Generation.

Instead of a screen flash, your users get a great experience: they can try to load an incorrect URL, and as long as the URL ends with a hyphen followed by the `id`, they'll be redirected to the correct URL seamlessly, like magic. If the URL doesn't match the pattern, they'll be redirected to the 404 page.

### Not Found: a 404 page for posts that don't exist

In `app/not-found.tsx`, create a 404 page that will render if someone tries to visit a post page with an id that doesn't exist in the url. [Next provides a `notFound` function](https://nextjs.org/docs/app/api-reference/functions/not-found) that will return a 404 page. We used this in page.tsx to return a 404 page if the post doesn't exist. You'll want to make this page look nice and include some helpful text, but for the sake of this example, we'll keep it simple:

```tsx
/*
  redirect to this page by calling the `notFound` function from the App Router in a page's server function:
  import { notFound } from 'next/navigation';
*/

export default function NotFound() {
  return <div>Not Found</div>;
}
```

## Try it out!

That should do it! run `yarn dev` to start the server, and navigate to `http://localhost:3000/posts/1` - you'll see it _automatically_ redirect to a better URL.

<Image
  publicId="posts/self-healing-urls-nextjs-seo/demo"
  alt="A demo of a self-healing URL made in Next.js"
/>

Nice!

Head over to `http://localhost:3000/sitemap.xml` and check out the nicely formatted sitemap, with the correct canonical URL for each post. Now your web app, your readers, _and_ Google are all on the same page. 🔥

## To do: update your redirects when a post's title changes

To be completely thorough there's one more thing we should probably do: if a post's title changes, you should add an entry to your redirects file to redirect the old URL to the new one. Even though this is a self-healing URL, it's still a good idea to add a redirect for the old URL, just in case someone has bookmarked it, or if someone has shared it on social media. This will also help Google understand that the old URL is no longer the correct one, and that it should index the new URL instead.

This is a bit more challenging, but it's worth it.

Because making this work is dependent on your specific setup, I'm not going to include a code example here, but I'll give you a few pointers:

- In your CMS, when a post is saved, check whether the title has changed. If it has, add an entry to your redirects file to redirect the old URL to the new one.
- It's a good to make sure that you don't accidentally create a redirect loop. If the new URL for a given path is the same as any of the prior URLs, don't add a new redirect, and remove any existing redirects for that path.
- You may need to kick off a rebuild of your site to make sure that the new redirect is picked up by your app. If you're using Vercel, you can use their [API to trigger a rebuild](https://vercel.com/docs/api#endpoints/deployments/redeploy-all-deployments) when a post is saved.

## Summary: self-healing URLs in Next.js

In this post, we learned how to set up self-healing URLs in Next.js. We used the App Router to generate URLs for all posts, and we used the App Router's `generateMetadata` function to generate metadata for each post. This function is called at build time, and it returns an object that contains the `title` and `alternates` for each post. The `alternates` object contains the `canonical` URL for each post, which is used to tell search engines which URL is the correct one for each post. **This is great for SEO purposes** - it helps Google verify that when your page loads, the URL in the address bar matches the URL that Google has indexed for that page. It also has usability benefits: if your post's title ever changes, the URL will magically update itself to match the new title. Additionally, people who visit your page while using a screen reader will have a better experience, because the URL will always match the content on the page.

Not too shabby!

## Get the code

You can find the code for this tutorial on [GitHub at mbifulco/next-self-healing-urls-app-router](https://github.com/mbifulco/next-self-healing-urls-app-router). If you enjoyed this post, please consider giving it a star ⭐️ on GitHub!

## PS: What about using the Next.js Pages router?

This post _started_ as a tutorial for using the Next.js Pages router to create self-healing URLs, but I ran into a few issues that would make it really challenging to recommend going down this path if you're using the pages router (which is actually what [mikebifulco.com uses](https://github.com/mbifulco/blog)!). For that reason, I think **this is a feature you should only add if you're using the App Router**. I'm including the draft of my original post here [in a gist](https://gist.github.com/mbifulco/daf23aed0d827ec6317962691cb9cd0d) in case anyone wants to take a stab at it. If you figure it out, please let me know!


How to set up self-healing URLs in Next.js for better SEO

Self-healing URLs in Next.js with the App router

Generate a sitemap with the correct canonical URL for each post

Setting up page.tsx: where the magic happens

Not Found: a 404 page for posts that don't exist

To do: update your redirects when a post's title changes

PS: What about using the Next.js Pages router?


## What is this thing?

The podcast [Acquired has a fantastic episode on the history of Costco's business](https://www.acquired.fm/episodes/costco). It's a tremendous episode, and you should add it to your queue... but it's also 3 hours long. After lisrtening to it, I wanted to talk about the episode with my teammates. Knowing they all wouldn't likely have the the time to listen to the whole show, I built a tool with OpenAI's Whisper API and GPT4 to summarize the show for them

This post is a sample summary of the episode for a few different personas, generated by LLM tools that I cobbled together. I wrote a bit about it in an issue of my newsletter Tiny Improvements, called

## Executive Summary:

This podcast analyzed the story of Costco, one of the largest and most successful warehouse clubs in the world with revenues of more than $230 billion.

Key Highlights:

- Costco's success is rooted in its unique model that has stripped away the complexities of traditional retail and focuses on providing high-quality goods at low prices. It has also benefited from its membership model, which encourages customer loyalty and provides a steady stream of revenue.
- The company was founded as Price Club in 1976 and pivoted towards the consumer market in the 1980s. It merged with Costco in 1993, and the combined entity became a hit with consumers in North America and beyond.
- Costco's growth has been driven by its keen focus on operational efficiency and a commitment to its core values. The company prioritizes serving its members, treating its employees well, being honest in its business practices, and rewarding its investors.
- The company continually looks for ways to keep operating costs low and pass the savings on to customers. This has led to Costco's successful strategy of having a limited number of products (SKUs), allowing the company to negotiate better deals with suppliers and streamlining operations.
- Costco's approach to growing its business has been defined by discipline and long-term vision. The company emphasizes incremental improvements and sustainability over explosive growth, and this has allowed Costco to steadily increase its market share without compromising on its core principles.

### Points for a Technical Executive (CTO):

- Costco has embraced technology to streamline operations, improve efficiency and support its growth. Most notably, the company has invested in warehouse automation technologies to reduce costs and improve efficiency.
- However, Costco's approach to e-commerce has been slower than other retailers, reflecting the company's emphasis on its brick-and-mortar operations.

### Points for an Operations Executive (COO):

- Costco's operational efficiency is central to its business model, with the company continually looking for ways to reduce costs and pass the savings on to customers.
- The company's decision to limit the number of products (SKUs) it sells has allowed it to streamline operations and negotiate better deals with suppliers.
- Costco's emphasis on retaining employees and promoting from within is also key to its success, helping to ensure consistent service and build a strong company culture.

### Points for a Growth Executive (CBO):

- Costco's growth has been driven by its unique membership model, opening of new stores domestically and internationally, and the introduction of new product categories.
- Even as it expands, the company has remained committed to its core business model of selling high-quality goods at low prices.
- Costco's decision to limit the number of SKUs it sells, and thus avoid the 'paradox of choice', has also helped to drive customer loyalty and repeat purchases.

### Related Reading or Listening:

- 'Made in America' by Sam Walton
- 'The Everything Store: Jeff Bezos and the Age of Amazon' by Brad Stone
- 'The Costco Craze: Inside the Warehouse Giant' documentary by CNBC.
- 'Margin of Safety' by Seth Klarman.


Acquired: Costco podcast summaries, generated using a GPT/LLM tool

Points for an Operations Executive (COO):


## 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: [
    {
      slug: '../../public/fonts/Grosa/Grosa-Regular.woff2',
      weight: '500',
      style: 'normal',
    },
    {
      slug: '../../public/fonts/Grosa/Grosa-Medium.woff2',
      weight: '600',
      style: 'normal',
    },
    {
      slug: '../../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

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

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

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

After loading custom fonts, generate CSS variables for each font

Use these variables your Tailwind config to create font families


## Growing feels great

It feels a little wild to say this, but I'm a few days away from hitting 400 Subscribers to my weekly newsletter, [Tiny Improvements](https://mikebifulco.com/newsletter). I started writing to share my expertise with the world, and to try to pay forward some of my luck and privilege to anyone who might benefit from it.

I've been writing about startups, building products, design, and React for a few years now, and it feels like the newsletter has really hit its stride lately.

In the past 6 months, I've grown by 350%, and landed about half a dozen sponsored newsletters. It's been really encouraging to see people enjoying what I have to say - and I have gotten some amazing feedback along the way.

## The basics: what I've learned so far

For my friends who may be interested in doing something like this, here's my advice: write on a dependable, regular cadence, publish your newsletters for SEO-driven growth, and don't be afraid to share your work.

## Growth comes in phases

<Image
  publicId="posts/building-in-public-growth-report-400-readers/growth-chart"
  alt="a chart showing the growth of Tiny Improvements since its launch in May of 2020"
/>

This chart shows a few important milestones in the story behind Tiny Improvements:

- **0-34** readers: May 2020, when I first announced I was writing
- **34-50** readers: December 2020, months later, after I sent my second dispatch
- **88-143** readers: July - Nov 2022, I started writing weekly
- **143-215** readers: November 9th - Dec 1 2022, I [Got laid off from my Job @ Stripe, and went viral](https://mikebifulco.com/newsletter/leaving-stripe-going-viral)
- **215-215** readers: December 2022 - Jan 2023: Flatlined! Turns out I introduced a bug to my site that prevented anyone from subscribing. lol.
- **215-394** readers: This brings us to today! Steady growth from steady writing, half a dozen sponsorships, and some promising deals coming my way.

## What's next?

I'll be writing more about my [experience as a founder](https://mikebifulco.com/newsletter/building-a-startup-in-2023-90-day-report), and sharing the lessons and challenges I will no-doubt run into as we grow. I've also got some ideas for short multi-segment posts/tutorials that I'd like to share, like more about [design for developers](https://mikebifulco.com/tags/design), and [networked note-taking](https://mikebifulco.com/newsletter/unlock-productivity-with-networked-note-taking).

Finally, on the business front, I'm hoping I'll be able to start working with sponsors who I think will really connect with my readers - I'm hoping to build relationships with some of the devtools companies which I really love, to see if there are opportunities to work together. I want to really come through for the people who have supported me (if you're reading this, that's you!), and I want to make sure that I'm only working with companies that I think will really benefit my readers.

By the way - if you're interested in [sponsoring Tiny Improvements](https://mikebifulco.com/sponsor), let's talk!

And of course, I'm looking forward to 400, and then 500 readers, and then anything to come after that!

## You should probably subscribe to Tiny Improvements

If you're interested in startups, building products, design, or React, I think you might really like [💌 Tiny Improvements](https://mikebifulco.com/newsletter).


Building in public: 400 subscriber milestone report for my newsletter

You should probably subscribe to Tiny Improvements


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

My last resort to fix TypeScript errors in VS Code

Make sure VS Code is using the correct version of TypeScript

Oh, hello