DEV Community: Sebastian Sdorra

Introducing Content Collections

Sebastian Sdorra — Thu, 18 Jan 2024 19:49:00 +0000

Working with Markdown files in a web project can be a pain.
You have to find the files in the file system, read the content, parse the frontmatter, validate the content, and transform it into a data structure that can be used by your application.
This is a lot of work, and it is easy to make mistakes.

Content Collections is a library that helps you transform your content into type-safe data collections.
After you have integrated Content Collections into your project, you only need one configuration file, and then you can just use your content with a normal import statement.
And the best thing is, you get HMR (Hot Module Replacement) for your content.

A simple example

Let's say you have a directory content which contains markdown files for your blog posts, for example content/2021-01-01-hello-world.md.

---
title: Hello World
published: true
---

# Hello World

This is a sample blog post.

Now we can use Content Collections to convert the markdown files into a data collection.

import { defineCollection, defineConfig } from "@content-collections/core";

const posts = defineCollection({
  name: "posts",
  directory: "content",
  include: "*.md",
  schema: (z) => ({
    title: z.string(),
    published: z.boolean().optional(),
  }),
});

export default defineConfig({
  collections: [posts],
});

The code above shows a simple example of the Content Collections configuration file content-collections.ts.
The schema function uses zod to define the structure of the frontmatter data.
Content Collections will validate and convert the Markdown files into objects with the following data structure:

type Post = {
  title: string;
  published?: boolean;
  content: string;
};

The content property contains the content of the Markdown file and the other properties are defined by the schema. Content Collections will not generate those types for you; they are inferred by TypeScript.
This means you can do very powerful things with the schema, such as defining nested objects or arrays, and you get all the type safety you expect from TypeScript.
Content Collections will also generate a _meta property for each object, which contains information about the location of the file.

Now, let's see how we can use the data collection in our application.

import { allPosts } from "content-collections";
import Markdown from "react-markdown";

export default function App() {
  return (
    <main>
      <h1>Posts</h1>
      <ul>
        {allPosts
          .filter((post) => Boolean(post.published))
          .map((post) => (
            <li key={post._meta.path}>
              <h2>{post.title}</h2>
              <Markdown>{post.content}</Markdown>
            </li>
          ))}
      </ul>
    </main>
  );
}

The allPosts variable is our generated collection, which we can simply import. If we change the content of a markdown file, the application will automatically reload the data collection, and the UI will be updated.

The example above uses react-markdown, but you can use any library you want to render the markdown content. You can also use a transform function to modify the markdown content during the build process. Here is an example that uses MDX to compile the markdown content.

import { defineCollection, defineConfig } from "@content-collections/core";
import { compile } from "mdx";

const posts = defineCollection({
  name: "posts",
  directory: "content",
  include: "*.md",
  schema: (z) => ({
    title: z.string(),
    published: z.boolean().optional(),
  }),
  transform: async (context, { content, ...data }) => {
    const body = String(
      await compile(content, {
        outputFormat: "function-body",
      })
    );
    return {
      ...data,
      body,
    };
  },

And the cool thing is that Content Collections is able to infer the types from the transform function too.

If you want to learn more about Content Collections, then check out the documentation.

Contentlayer

If you think that sounds like Contentlayer, then you are right. Content Collections is heavily inspired by Contentlayer, but there are some fundamental differences.

If you want to learn more about why I have built Content Collections and have not stuck with Contentlayer, then check out this blog post at sdorra.dev.

Feedback

Content Collections is still in its early stage, and I would love to receive some feedback. If you have any questions or suggestions, please open an issue on GitHub.

Responsive components with grid and TailwindCSS

Sebastian Sdorra — Wed, 15 Feb 2023 13:36:24 +0000

If we want to build real responsive components, it is often no longer enough to let something slide into the next line. Sometimes it is necessary to change the structure of a component and this can quickly become complicated. I would like to use the following example to show how the problem can be solved with Flexbox and Grid.

The Example

Let's assume that we want to implement the following card:

The card consists of an avatar, a title and a short description text.
In the mobile view the avatar and the title should be in the same line and the description should take up the whole line below.

For larger viewports, we want the avatar to be larger and the description to be next to the avatar as well.

Ok, let's see how we can implement this.

Flex solution

We start with a flexbox implementation, because I always start with flexbox.
An initial implementation of the mobile variant could look like this:

<section>
  <div className="flex items-center gap-4">
    <Avatar className="h-16 w-16" />
    <h3 className="text-2xl font-bold">Title</h3>
  </div>
  <p className="mt-5">Description</p>
</section>

But when we try to implement the larger viewports, it gets difficult quickly.
The problem is that the structure changes.
The only solution I can think of here is to duplicate the description:

<section>
  <div className="flex items-center gap-4">
    <Avatar className="h-16 w-16 flex-shrink-0 sm:h-24 sm:w-24" />
    <div className="w-full">
      <h3 className="text-2xl font-bold">Title</h3>
      <p className="mt-5 hidden sm:block">Description</p>
    </div>
  </div>
  <p className="mt-5 sm:hidden">Description</p>
</section>

To solve the problem we had to group the title and description with a div,
hide the description (hidden) and
only show it when we are in a larger viewport (sm:block).
The description for the small viewport is displayed by default and
is hidden when we are in a larger viewport (sm:hidden).

But we need to do more.
The grouping of the title can cause the avatar to be squeezed,
so we need to add a w-full to the grouping div and a flex-shrink-0 to the avatar.

This solution is far from optimal.
We had to include more markup and we had to duplicate content.
There is probably a better way to solve this problem with Flexbox,
but I couldn't think of one.

If you know of a better solution, please leave a comment

Grid to the rescue

Lets try to implement the same layout with grid instead of flexbox.
We start again with the mobile view:

<section className="grid grid-cols-[5rem,1fr] items-center">
  <Avatar className="h-16 w-16" />
  <h3 className="text-2xl font-bold">Title</h3>
  <p className="col-span-2 mt-5">Description</p>
</section>

Except for the arbitrary value for grid-cols, the whole thing is pretty simple.
We create a grid with 2 columns, the first is 5rem wide (1rem wider than the avatar) and the second is 1fr wide (grid grid-cols-[5rem,1fr]).
In the first column of the first row is the avatar,
in the second column is the title.
We have extended the description to two columns (col-span-2) and
it is in the second row.

In the case of the larger viewport,
we actually only need to draw the avatar over 2 lines and
take back the col span of the description.

The whole thing could look like this:

<section className="grid grid-cols-[5rem,1fr] items-center sm:grid-cols-[7rem,1fr]">
  <Avatar className="row-span-2 h-16 w-16 sm:h-24 sm:w-24" />
  <h3 className="text-2xl font-bold">Title</h3>
  <p className="col-span-2 mt-5 sm:col-span-1">Description</p>
</section>

With the row-span-2 we could draw the avatar over both lines and
with sm:col-span-1 we reset the col span of the description.
We also had to reserve more space for the avatar in the first column of the grid (sm:grid-cols-[7rem,1fr]).

Conclusion

With the grid solution we needed much less markup.
We also didn't need duplication anymore and it's also much easier to understand.

Component development with ladle and next/image

Sebastian Sdorra — Mon, 30 Jan 2023 12:27:38 +0000

Sometimes it is easier to build a component in isolation than in the place where it will be used.
It is much easier to test all variations and edge cases of the component.
There are tools out there which can help us to build our components in isolation.
The most famous is Storybook,
but I like to use Ladle.
Ladle is much smaller than Storybook and it is built for speed.
In this post we will set up Ladle and
we will learn how we can use next/image within Ladle.

Setup

First we have to install Ladle:

# with pnpm
pnpm add -D @ladle/react
# with yarn
yarn add -D @ladle/react
# with npm
npm install --save-dev @ladle/react

And for most installations, that's it.
Ladle has a useful default configuration,
you only need to create a configuration if your installation differs from the default.
But for most Next.js installations the default does not fit.
Ladle expects stories and components in the "src" folder,
but in many Next.js installations they are in a folder called components.
So we have to create a configuration at .ladle/config.mjs:

export default {
  stories: "components/**/*.stories.{js,jsx,ts,tsx}",
};

With this configuration ladle is able to find our stories.
A good time to write our first story.

First Story

We want to create our first Story for the following component.

type Props = {
  src: string;
  alt: string;
  size?: "sm" | "md" | "lg" | "xl";
};

const sizes = {
  sm: 16,
  md: 32,
  lg: 64,
  xl: 128,
};

const Avatar = ({ src, alt, size = "md" }: Props) => (
  <img
    className="rounded-full shadow-md ring-2 ring-zinc-300 dark:ring-zinc-700"
    src={src}
    width={sizes[size]}
    height={sizes[size]}
    alt={alt}
  />
);

export default Avatar;

We want to create a story which shows us all sizes of the Avatar component next to each other.
To create a new story we have to create a story file next to our component:

import Avatar from "./Avatar";

export const Default = () => <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" />;

export const Sizes = () => (
  <div className="flex gap-4">
    <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" size="sm" />
    <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" size="md" />
    <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" size="lg" />
    <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" size="xl" />
  </div>
);

Now it is time to start Ladle.

# with pnpm
pnpm ladle dev
# with yarn
yarn ladle dev
# with npm
npm ladle dev

Ladle should show 2 stories below Avatar.
Default which shows our component within its default size and
Sizes which shows the component in all available sizes next to each other.

Bonus:

With a little bit of typescript magic, we can avoid the duplicate definitions of the sizes.

// we export sizes so that we can reuse it in our story
export const sizes = {
  sm: 16,
  md: 32,
  lg: 64,
  xl: 128,
};

// we can infer the union type of Size from the sizes object
export type Size = keyof typeof sizes;

type Props = {
  src: string;
  alt: string;
  // we can use our inferred type
  size?: Size;
};

const Avatar = ({ src, alt, size = "md" }: Props) => (
  <img
    className="rounded-full shadow-md ring-2 ring-zinc-300 dark:ring-zinc-700"
    src={src}
    width={sizes[size]}
    height={sizes[size]}
    alt={alt}
  />
);

export default Avatar;

import Avatar, { sizes } from "./Avatar";

export const Default = () => (
  <Avatar src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" />
);

// We can now create an array of sizes from the exported object.
// Unfortunately we have to cast the array using `as`,
// because `Object.keys` only returns `string[]`.
// https://github.com/Microsoft/TypeScript/issues/12870
const sizeKeys = Object.keys(sizes) as Size[];

export const Sizes = () => (
  <div className="flex gap-4">
    {/* We can loop over the array of sizes */}
    {sizeKeys.map(size) => (
      <Avatar key={size} src="https://robohash.org/sdorra.dev" alt="Robohash of sdorra.dev" size={size} />
    )}
  </div>
);

next/image

After we got Ladle running and wrote our first story,
we want to develop our component further.
We want to use next/image instead of img to get all the advantages of next/image.
So we just replace the img tag with the Image tag from next/image.

import Image from "next/image";

// Types and props remain unchanged

const Avatar = ({ src, alt, size = "md" }: Props) => (
  <Image
    className="rounded-full shadow-md ring-2 ring-zinc-300 dark:ring-zinc-700"
    src={src}
    width={sizes[size]}
    height={sizes[size]}
    alt={alt}
  />
);

But now we get an error in ladle.

Error: Uncaught ReferenceError: process is not defined

After a short research session I found the following issue on GitHub.

https://github.com/tajo/ladle/issues/100

One of the comments provided the following solution.
We have to create a file called vite.config.ts in the root of our project.

import { defineConfig } from "vite";

export default defineConfig({
  define: {
    "process.env": process.env,
  },
});

That fixes the process is not defined error,
but we immediately get the next error.

Error:
Uncaught Error: Invalid src prop (https://robohash.org/sdorra.dev) on next/image, hostname "robohash.org" is not
configured under images in your next.config.js See more info:
https://nextjs.org/docs/messages/next-image-unconfigured-host

All right, but we don't want to add the entry to next.config.js at all,
since this is just test data and besides,
we still get the same error when we make the entry.

After another look at issue #100,
we can tell next/image that it should skip the optimization if the component is rendered in Ladle.
That is fine, because the bandwidth does not play a big role during the development.
With the following code placed inside .ladle/components.tsx ...

import * as NextImage from "next/image";

const OriginalNextImage = NextImage.default;

Object.defineProperty(NextImage, "default", {
  configurable: true,
  value: (props) => <OriginalNextImage {...props} unoptimized />,
});

... we can add the unoptimized to each usage of next/image.
Great, that fixed our problem.
But unfortunately only in the development mode of Ladle.
If we run the production build (ladle build and ladle preview), we get the next error.

Error: Uncaught TypeError: Cannot redefine property: default

Our solution does not work with the production build, we have to find another solution.

The solution

Fortunately, I thought of another way to get the unoptimized prop to all image instances.
We can create an alias for the next/image import and resolve next/image to a custom component.
This can be done in the vite.config.ts:

import path from "path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      "next/image": path.resolve(__dirname, "./UnoptimizedImage.tsx"),
    },
  },
  define: {
    "process.env": process.env,
  },
});

Now we can write our own image component to UnoptimizedImage.tsx.
But what if we want to use the original next/image in our component?
In order to achieve this we can define another alias in the vite.config.ts:

import path from "path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: {
      "next/original-image": require.resolve("next/image"),
      "next/image": path.resolve(__dirname, "./.ladle/UnoptimizedImage.tsx"),
    },
  },
  define: {
    "process.env": process.env,
  },
});

Now we should have everything together to make our UnoptimizedImage.

import React from "react";
// @ts-ignore have a look in vite.config.ts
import OriginalImage from "next/original-image";

const UnoptimizedImage = (props: any) => {
  return <OriginalImage {...props} unoptimized />;
};

export default UnoptimizedImage;

After that we only have to remove the workaround from .ladle/components.tsx or
we can remove the complete file if it has no other content.
After a quick look into Ladle (production and development mode),
we can see that we have finally solved the problem.

Dark mode with Shiki and Code Hike

Sebastian Sdorra — Sun, 29 Jan 2023 12:47:34 +0000

Warning: This article refers to versions of Code Hike before 0.8.0. Since version 0.8.0, Code Hike uses lighter instead of Shiki. The approach presented in this article uses shiki's color replacement method, which no longer works with lighter.

I'm using Code Hike a lot, including for the code snippets on my blog, and I love this library.
It has many nice features, like tabs or focus.
But it is lacking support for switching themes at runtime, which I want to use for a dark mode implementation.

https://github.com/code-hike/codehike/issues/271

That is really a pity.
But why actually?
Code Hike uses Shiki and Shiki supports changing themes via CSS variables.
We should try that out?

Shiki

In order to switch Shiki colors at runtime,
we have to load a special theme which uses CSS variables instead of hard coded colors.
This should look like this:

{
  options: {
    remarkPlugins: [
      [remarkCodeHike, { theme: "css-variables" }]
    ],
  },
}

After that we can define our colors for the theme with css variables:

:root {
  --shiki-color-text: #24292f;
  --shiki-color-background: #ffffff;
  --shiki-token-constant: #0550ae;
  --shiki-token-string: #24292f;
  --shiki-token-comment: #6e7781;
  --shiki-token-keyword: #cf222e;
  --shiki-token-parameter: #24292f;
  --shiki-token-function: #8250df;
  --shiki-token-string-expression: #0a3069;
  --shiki-token-punctuation: #24292f;
  --shiki-token-link: #000012;
}

And we can override them for the dark mode:

@media (prefers-color-scheme: dark) {
  :root {
    --shiki-color-text: #c9d1d9;
    --shiki-color-background: #0d1117;
    --shiki-token-constant: #79c0ff;
    --shiki-token-string: #a5d6ff;
    --shiki-token-comment: #8b949e;
    --shiki-token-keyword: #ff7b72;
    --shiki-token-parameter: #c9d1d9;
    --shiki-token-function: #d2a8ff;
    --shiki-token-string-expression: #a5d6ff;
    --shiki-token-punctuation: #c9d1d9;
    --shiki-token-link: #000012;
  }
}

Tailwind CSS

If you use Tailwind CSS and use the dark mode with the class strategy instead of media query,
you can override the variables like this:

html.dark {
  --shiki-color-text: #c9d1d9;
  --shiki-color-background: #0d1117;
  --shiki-token-constant: #79c0ff;
  --shiki-token-string: #a5d6ff;
  --shiki-token-comment: #8b949e;
  --shiki-token-keyword: #ff7b72;
  --shiki-token-parameter: #c9d1d9;
  --shiki-token-function: #d2a8ff;
  --shiki-token-string-expression: #a5d6ff;
  --shiki-token-punctuation: #c9d1d9;
  --shiki-token-link: #000012;
}

Bonus:
You can use colors from Tailwind CSS by using the theme function:

:root {
  --shiki-color-text: theme("colors.zinc.700");
  --shiki-color-background: theme("colors.white");
  --shiki-token-constant: theme("colors.emerald.700");
  --shiki-token-string: theme("colors.emerald.700");
  --shiki-token-comment: theme("colors.zinc.500");
  --shiki-token-keyword: theme("colors.cyan.700");
  --shiki-token-parameter: theme("colors.pink.700");
  --shiki-token-function: theme("colors.violet.700");
  --shiki-token-string-expression: theme("colors.emerald.700");
  --shiki-token-punctuation: theme("colors.zinc.800");
  --shiki-token-link: theme("colors.zinc.700");
}

Code Hike

Ok, now we have everything together let's test it.
Most of the colors are now loaded from our variables, but not all.

The background and the default text color are always very dark.
Why is that?
After some time of searching in the source code of Code Hike, I found the answer.
It reads some color information from the theme itself (theme.ts).
But shouldn't it then get variables instead of hard coded blackish color codes?
After a look into the Shiki theme,
I have to realize that there are no variables defined.
After another research phase, I found out that Shiki does some weird color code to variable replacement.

https://github.com/shikijs/shiki/pull/314

Shiki does this because the underlying library vscode-textmate or vscode-oniguruma returns black if the value is not a valid color.
This explains why Code Hike uses blackish color codes instead of variables.
But what if we write a variable directly into the theme instead of the color code.

Custom theme

At first we copy the css-variables theme from Shiki and
modify the values of editor.foreground and editor.background from the blackish color codes to variables.

{
  "name": "css-variables",
  "type": "css",
  "colors": {
    "editor.foreground": "var(--shiki-color-text)",
    "editor.background": "var(--shiki-color-background)",
  },
  ...
}

Now we can load our custom theme.

import { remarkCodeHike } from "@code-hike/mdx";
import theme from "./lib/ch-theme.json" assert { type: "json" };

const options = {
  remarkPlugins: [[remarkCodeHike, { theme }]],
};

// configure mdx ...

Great, that seems to work.
But what about tabs, if we use CH.Code?

After some research in the source code,
we add some more variables to our theme and to our css:

"colors": {
  "editor.foreground": "var(--shiki-color-text)",
  "editor.background": "var(--shiki-color-background)",

  "editorGroupHeader.tabsBackground": "var(--ch-tabs-bg)",
  "tab.activeBackground": "var(--ch-tab-active-bg)",
  "tab.inactiveForeground": "var(--ch-tab-inactive-color)",
  "tab.inactiveBackground": "var(--ch-tab-inactive-bg)",
  "icon.foreground": "var(--ch-icon-text)",

  "tab.border": "var(--ch-tab-border)",
  "tab.activeBorder": "var(--ch-tab-active-border)",
},

:root {
  --ch-icon-text: #3f3f46;
  --ch-tabs-bg: #e4e4e7;
  --ch-tab-border: #d4d4d8;
  --ch-tab-active-border: #ffffff;
  --ch-tab-active-bg: #ffffff;
  --ch-tab-active-color: #3f3f46;
  --ch-tab-inactive-color: #71717a;
  --ch-tab-inactive-bg: #e4e4e7;
}

But the color definition for tab.activeForeground caused problems.
Code Hike tries to convert the color from hex to rgba in order to add opacity to the color (transparent).
But our color definition (var(--ch-tab-active-color) is not a hex color code and the function throws an error.
With a bit of css we are able to workaround the problem:

div.ch-editor-tab-active {
  color: var(--ch-tab-active-color);
}

That's it, we can now use CSS variables for the style of our syntax highlighting
and we can use different themes for light and dark mode.

Warning: I've tested not all feature of Code Hike. It is very likely that there will still be problems at one point or another.

Existing Themes

That is all nice, but how can we use existing VS Code themes with this approach (Shiki and Code Hike are using VS Code themes).
We have to read the theme and copy the color codes from the theme to our css variables.
But this is a very tedious work, so I have written a small tool that can take this task from us.

$ npx convert-sh-theme https://raw.githubusercontent.com/shikijs/shiki/main/packages/shiki/themes/dracula.json

style.css
=======================================

:root {
  --shiki-color-text: #F8F8F2;
  --shiki-color-background: #282A36;

  --shiki-token-constant: #BD93F9;
  --shiki-token-string: #8BE9FD;
  --shiki-token-comment: #6272A4;
  --shiki-token-keyword: #FF79C6;
  --shiki-token-parameter: #F8F8F2;
  --shiki-token-function: #8BE9FD;
  --shiki-token-string-expression: #FF79C6;
  --shiki-token-punctuation: #F8F8F2;
  --shiki-token-link: #8BE9FD;
}

To create styles and the theme for Code Hike:

$ pnpx convert-sh-theme --code-hike --out output https://raw.githubusercontent.com/shikijs/shiki/main/packages/shiki/themes/dracula.json

... write file style.css
... write file theme.json

For more information about the converter tool, have a look at convert-sh-theme.

Implementing a share button

Sebastian Sdorra — Mon, 09 Jan 2023 18:31:12 +0000

In this article we will create a button, which makes it easy for our readers to share our articles.
We all know the share button on our phones,
which allows us to send a piece of information from an app to one of our contacts via messenger, email, etc.
Wouldn't it be awesome if we could include a button like this on our blog as well.
It turns out we can.
The Web Share API allows us to open the well known share menu on our phones.
The example below shows a simple example in react.

type Props = {
  title: string;
  text: string;
  url: string;
};

const ShareButton = ({ title, text, url }: Props) => {
  const onClick = async () => {
    await window.navigator.share({
      title,
      text,
      url,
    });
  };
  return <button onClick={onClick}>Share</button>;
};

Quite simple, isn't it.

Support

It could be so simple if desktop operating systems and browsers also had a share menu.
But sadly this is not yet the case.
So we have to implement a fallback for those which do not have a share menu.
We can check if the browser supports sharing our kind of information with the following function.

const isWebShareSupported = (data: ShareData) => {
  return window.navigator.canShare && window.navigator.share && window.navigator.canShare(data);
};

The function will check if the browser has an implementation of the canShare and share function.
It will also check with canShare if the api is able to share our information.
If this function returns false, we should display a fallback instead.

Fallback

For the fallback we could open a modal, with some options to share the article e.g.:

All of these services are popular for sharing information and they all offer a url to simplify this process.
In addition to the services we could add a share with email link and a copy to clipboard function.

For the modal we will use headlessui,
because it makes it easy for us to implement the modal and we can style it how we want.
Furthermore headlessui will handle the accessibility attributes and functions for us,
which are quite complicated for modals.

First we have to install headlessui.

pnpm add @headlessui/react
# or with yarn
yarn add @headlessui/react
# or with npm
npm install @headlessui/react

Ok, now we are able to open the modal if the Web Share API is not supported.

import { Dialog } from "@headlessui/react";
import { useState } from "react";

type Props = {
  title: string;
  text: string;
  url: string;
};

const ShareButton = ({ title, text, url }: Props) => {
  const [isOpen, setIsOpen] = useState(false);

  const onClick = async () => {
    const data = {
      title,
      text,
      url,
    };
    if (isWebShareSupported(data)) {
      await window.navigator.share();
    } else {
      setIsOpen(true);
    }
  };

  return (
    <>
      <button onClick={onClick}>Share</button>
      <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
        <Dialog.Panel>
          <Dialog.Title>Share article</Dialog.Title>
          {/* TODO add share links */}
        </Dialog.Panel>
      </Dialog>
    </>
  );
};

With this modification,
we check on every click on the button if we are able to use the Web Share API.
If the api is supported we open the native share menu,
if not we set an internal state to open the modal.
We are now ready to add some links.

Pocket

Pocket is a social bookmarking service for storing, sharing, and discovering web bookmarks.
Pocket has a special link for sharing buttons.
Our implementation could look like the following.

import { Pocket } from "lucide-react";

type Props = {
  url: string;
};

const PocketLink = ({ url }: Props) => (
  <a href={`https://getpocket.com/save?url=${encodeURIComponent(url)}`} target="_blank" rel="noreferrer">
    <Pocket /> Pocket
  </a>
);

We use the lucide-react to render a nice icon for the Pocket link.

Twitter

Twitter is a social networking service that probably everyone has heard of.
Twitter has also a special link,
which is able to pre-fill the tweet editor.

import { Twitter } from "lucide-react";

type Props = {
  title: string;
  url: string;
};

const TwitterLink = ({ url, title }: Props) => (
  <a
    href={`https://twitter.com/intent/tweet?url=${encodeURIComponent(url)}&text=${encodeURIComponent(title)}`}
    target="_blank"
    rel="noreferrer"
  >
    <Twitter /> Twitter
  </a>
);

Facebook

Facebook is another quite popular social media network,
with a link which pre-fills the post editor.

import { Facebook } from "lucide-react";

type Props = {
  url: string;
};

const FacebookLink = ({ url }: Props) => (
  <a href={`https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(url)}`} target="_blank" rel="noreferrer">
    <Facebook /> Facebook
  </a>
);

LinkedIn is another social media network with a business focus.
They also have a share link.

import { Linkedin } from "lucide-react";

type Props = {
  url: string;
};

const LinkedInLink = ({ url }: Props) => (
  <a
    href={`https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`}
    target="_blank"
    rel="noreferrer"
  >
    <Linkedin /> LinkedIn
  </a>
);

Email

Another simple option to share an article is to send the url per email.
Here is how we can provide a button, which opens the email client with a prepared email.

import { Mail } from "lucide-react";

type Props = {
  title: string;
  text: string;
  url: string;
};

const MailToLink = ({ url, title, text }: Props) => (
  <a
    href={`mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(text + "\n\n")}${encodeURIComponent(
      url
    )}`}
    target="_blank"
    rel="noreferrer"
  >
    <Mail /> Send as email
  </a>
);

Copy to clipboard

The last option we want to offer is a button which copies the article url to the clipboard of the client.

import { Check, Copy } from "lucide-react";

type Props = {
  url: string;
};

const CopyToClipboardButton = ({ url }: Props) => {
  const [copied, setCopied] = useState(false);

  const copy = () => {
    window.navigator.clipboard.writeText(url);
    setCopied(true);
  };

  return <button onClick={copy}>{copied ? <Check /> : <Copy />} Copy to clipboard</button>;
};

The button shows a copy icon and after it is clicked we use the clipboard api to copy the url.
After the url is copied, the button shows a check mark instead of the copy icon.

Share menu

Now we are able to complete the fallback share menu.

<Dialog open={isOpen} onClose={() => setIsOpen(false)}>
  <Dialog.Panel>
    <Dialog.Title>Share article</Dialog.Title>
    <ul>
      <li>
        <PocketLink />
      </li>
      <li>
        <TwitterLink />
      </li>
      <li>
        <FacebookLink />
      </li>
      <li>
        <LinkedInLink />
      </li>
      <li>
        <MailToLink />
      </li>
      <li>
        <CopyToClipboardButton />
      </li>
    </ul>
  </Dialog.Panel>
</Dialog>

Complete example

For a complete example,
which is styled with Tailwind CSS,
have a look at the source code of my blog (ShareButton sdorra.dev).

Contentlayer with next/image

Sebastian Sdorra — Wed, 04 Jan 2023 14:50:17 +0000

Getting images right and fast on the web is hard.
If we are doing it wrong,
we create a poor user experience with slow loading times and
CLS (Cumulative Layout Shift).

next/image

In Next.js we can use the next/image component to avoid this bad user experience.
next/image automatically optimizes our images in three ways to reduce the slow loading times:

Converts the image to the smallest supported format
Resizes the image based on the used device viewport
Uses image compression

It also creates a placeholder to avoid the CLS.
The following example shows the usage of next/image with a static image:

import picture from "./pictures/mountain.jpg";

<Image src={picture} alt="Picture of a mountain" placeholder="blur" />;

Markdown

This looks great, but how can we use it in our markdown files?

MDX

My first reaction was to use MDX and use next/image just as in the example.
But that means that we can't use normal markdown images and it turns out that this won't work with contentlayer.
It won't work, because Next.js does some magic on the import of the static image.
The object which gets returned by the import contains not only a path to the image, it contains also the width and height plus a very small version of the image for the blurred placeholder.
This magic does not work if the MDX file is loaded with contentlayer,
because contentlayer uses its own bundler, which knows nothing about the import magic for images.

The trick with the public folder

The next idea was to use normal markdown images and to place the images in the public folder.
This eliminates the need for static imports and treats our image like a remote image.
But in order to make this work, we have to tell next/image the dimensions of the image.
If we would use a static import for the image, the import magic would provide the dimensions for us.
To pass the width and height to the image component we use a rehype plugin called rehype-img-size.

# pnpm
pnpm add -D rehype-img-size

# yarn
yarn add -D rehype-img-size

# npm
npm install --save-dev rehype-img-size

After installation we can configure contentlayer to use the plugin within MDX, but it should work with markdown too.

export default makeSource({
  contentDirPath: "content/posts",
  documentTypes: [Post],
  mdx: {
    rehypePlugins: [[rehypeImgSize, { dir: "public" }]],
    remarkPlugins: [],
  },
});

The plugin will now find each image in the markdown content and pass its dimensions to the image component.
If we have the following markdown content...

![Picture of a mountain](/pictures/mountain.jpg)

...rehype-img-size will look up pictures/mountain.jpg in the public directory (as configured in the contentlayer config) and
calculate its size.
Now we can replace the image component with next/image:

import { useMDXComponent } from "next-contentlayer/hooks";
import Image from "next/image";

type Props = {
  code: string;
};

const Markdown = ({ code }: Props) => {
  const MDXComponent = useMDXComponent(code);
  return (
    <section className="prose prose-zinc">
      <MDXComponent
        components={{
          img: Image,
        }}
      />
    </section>
  );
};

export default Markdown;

And that's it, we are now using next/image to render our markdown images.
This approach works, but it is not ideal, because the images can't be located next to the content.
They have to be placed in the public directory.
It would be better if we could locate the images right next to the content.

We also don't have the small image for the blurred placeholder,
we can only use the empty placeholder.

If these two things are not so important to you, this is the right approach.

Custom rehype plugin

To fix the two weaknesses from the last approach, we can write a custom rehype plugin.
Our plugin should do the following things:

Copy the image from its location to the public folder
Update the src attribute to the new location
Calculate the width and height
Create small image for blurred placeholder

Before we write this plugin,
we should understand how the markdown processing works in contentlayer.

contentlayer uses remark to parse the markdown into a mdast.
We can now use remark plugins to modify the mdast.
Then rehype comes into play and converts the mdast into a hast.
rehype plugins can now modify the hast.
Finally the hast is converted into react components.

For our plugin we have to modify the hast,
because images in the mdast don't have width or height and they don't support custom properties.
The hast on the other hand supports all properties of the HTML img component and we can pass custom properties.

Implementation

We start our plugin by defining the options:

publicDir: path to the public directory

Then we can define our plugin.
The plugin is a function which gets the options and returns another function which receives the following parameters:

tree: the whole hast
file: the parsed file with path and content
done: a function which should be called when our plugin has finished

Our plugin searches the hast tree and for each element with the tagName img we call the processImage function.
rehype plugins can't be async, but image processing is async.
That's the reason why we store each resulting Promise of the processImage function in an array and call the done function if all Promises are resolved and the work is done.

type Options = {
  publicDir: string;
};

const staticImages: Plugin<[Options], Root> = (options) => (tree, file, done) => {
  const tasks: Promise<void>[] = [];

  visit(tree, "element", (node) => {
    if (node.tagName === "img") {
      tasks.push(processImage(options, file, node));
    }
  });

  Promise.all(tasks).then(() => done());
};

const processImage = async (options: Options, file: VFileWithOutput<unknown>, node: Element): Promise<void> => {
  // implementation comes next
}

export default staticImages;

Ok, now we can have a detailed look at the implementation of the processImage function.
At first we have to find the real path of the image.
Fortunately, contentlayer stores information about the location of our markdown file in the data field of the file.

// find the content directory
const root = file.dirname || process.cwd();

// find the directory of the markdown file
// RawDocumentData is an import from contentlayer/source-files
const data = file.data as { rawDocumentData: RawDocumentData };
const directory = data.rawDocumentData.sourceFileDir;

// get the path of the image from the src attributes
const filePath = image.properties?.src as string || "";

// create the path by joining root, directory and filePath
// path is imported from node:path
const imagePath = path.join(root, directory, filePath)

Now that we have the path we can use sharp to read the width and height of the image.

// sharp is an import from sharp (@types/sharp)
const image = await sharp(imagePath);

// get the width and height of the image
const { width, height } = await image.metadata();

After that we can create a small version of the image for the blurred placeholder.
We will create a png with a quality of 75, a width of 8px and we keep the aspect ratio.

const imgAspectRatio = width / height;
const blurDataURL = await image
  .resize(8, Math.round(8 / imgAspectRatio))
  .png({
    quality: 75,
  })
  .toBuffer()
  .then((buffer) => `data:image/png;base64,${buffer.toString("base64")}`);

Then we can copy the image to the public folder and create a new path for the src attribute of the image.

const src = path.join(directory, filePath);
const target = path.join(options.publicDir, src);

await fs.mkdir(path.dirname(targetDir), { recursive: true });
await fs.copyFile(imagePath, target);

With all the information in place we can update the properties of the img tag.

node.properties = {
  ...node.properties,
  width,
  height,
  src: path.join("/", src),
  blurDataURL,
};

After we have finished writing our plugin, it is time to configure contentlayer.

import mdxImages from "./lib/static-images";

export default makeSource({
  contentDirPath: "content/posts",
  documentTypes: [Post],
  mdx: {
    rehypePlugins: [[mdxImages, { publicDir: path.join(process.cwd(), "public") }]],
    remarkPlugins: [],
  },
});

Don't forget to replace the img tag with next/image.
As we have seen in the rehype-img-size method.

Conclusion

Ok, let's summarize again what we have achieved.

We have written a rehype plugin, which does the following steps fully automatic for us:

Copy the image from its location to the public folder
Update the src attribute to the new location
Calculate the width and height
Create a small image for the blurred placeholder

With this plugin we can use the normal markdown image syntax and gain all the benefits of next/image:

Smallest supported format
Resized version based on the used device viewport
image compression

For a more complete example have a look at the source of this blog.

MDX autolink headings

Sebastian Sdorra — Wed, 04 Jan 2023 08:20:06 +0000

Sometimes it is useful to create a link to a specific section of an article.
So it is common that headings of articles have an id which can be used to create an anchor link.

<h1 id="hello-world">Hello World</h1>

If we want to create a link which scrolls directly to that heading,
we can append the following anchor to the url of the article #hello-world.

So much for the theory, but how can we automate this?

Generating ids

Generating ids for each heading is easy with MDX.
We can use the rehype-slug plugin, which does the whole work for us.

# pnpm
pnpm add -D rehype-slug
# yarn
yarn add -D rehype-slug
# npm
npm install --save-dev rehype-slug

After the installation we have to tell MDX that it should use the plugin.
The example below shows a contentlayer config,
but it should work with every MDX setup.

import rehypeSlug from "rehype-slug";

export default makeSource({
  contentDirPath: "content/posts",
  documentTypes: [Post],
  mdx: {
    rehypePlugins: [rehypeSlug],
    remarkPlugins: [],
  },
});

That's it.
Now every heading in our articles should have an id and we could create links for them.
But how do we create those links?
Do we need to look up the id of the heading from the source code?
This sounds too complicated, there must be an easier way.

Self link

The simplest way to make it easier to generate links to our headings,
is to turn the headings into links which point to themselves.
Doing so, we can click them and copy the url from the browser address bar afterwards.

We could use rehype-autolink-headings for this.
But if we want to do some styling with TailwindCSS, we have to wrap the heading manually.

To wrap our headings into links,
we need to override the default MDX heading components.

const Markdown = ({ code }: Props) => {
  const MDXComponent = useMDXComponent(code);
  return (
    <section className="prose">
      <MDXComponent
        components={{
          h1: heading("h1"),
          h2: heading("h2"),
          h3: heading("h3"),
          h4: heading("h4"),
          h5: heading("h5"),
          h6: heading("h6"),
        }}
      />
    </section>
  );
};

We use a simple factory function to create a component for each heading:

import { Hash } from "lucide-react";
import { ReactNode } from "react";

type HeadingProps = {
  id?: string;
  children?: ReactNode;
};

const heading = (As: "h1", `h2`, `h3`, `h4`, `h5`, `h6`) => {
  const Heading = ({ id, children }: HeadingProps) => (
    <a href={`#${id}`} className="group relative no-underline">
      <Hash className="absolute -left-6 hidden group-hover:block p-1 pink-cyan-500 h-full" />
      <As id={id}>{children}</As>
    </a>
  );
  Heading.displayName = As;
  return Heading;
};

The heading component renders an a tag,
with an href pointing to the id which was generated by the rehype-slug and passed as a prop to our component.
On the a tag we use the group class
which allows us to apply styling to children if the parent is hovered.
Also we use the relative class, because we want to position an icon absolute to the left of the heading.

Inside of the a tag we use a Hash icon from the lucide-react package.
The icon is positioned absolute with -1.5rem to the left of its normal position (absolute -left-6).
The icon is hidden by default, but gets displayed as block if the group is hovered (hidden group-hover:block).

The last child of the a tag is the heading itself which is one of h1, h2, h3, h4, h5 or h6 depending on the parameter with which the factory function was called.
The heading renders the id where the href of the a tag points to and the children which is the text of the heading.

And that's it, we can now hover over our MDX headings and should see a hash to the left.
If we click a heading, we should see the id appended to the url in the browser address bar.

Social Media Cards with @vercel/og

Sebastian Sdorra — Fri, 09 Dec 2022 19:55:07 +0000

Recently I added social media cards to sdorra.dev.
Social media cards are images which are displayed,
when you or someone else post a link to your content on a social media platform.
Posts with a nice looking image are more often clicked, as those without an image.
Lets see how we can implement them.

Possible implementations

I've implemented social media cards many times before and
I've used many different techniques to implement them,
but all of them had their downsides.

Manually creation

The simplest way is to create the social media cards manually.
Just open figma or a similar tool and create a card for each post.
This approach works, but it is very error prone and time consuming.
We had to remember to create a new card, every time we create a new post.

Node Canvas

Another approach is it to create a background image and
insert the texts and the metadata with a canvas library like node-canvas.
This approach is very well described in this Learn With Jason episode.
But with a canvas library we have to specify on which coordinates we want to render our texts and
it does not wrap automatically if it becomes to long.

External service

We could also use an external service like cloudinary.
The post of Jason describes this approach very detailed.
Cloudinary is able to break texts on a certain width,
but the api is not very intuitive and the largest part of the card is an image which must be build with an external tool.

SVG and opentype.js

With an SVG we can define our image as code, which is pretty neat.
But SVG is not able to wrap texts.
We can use opentype.js to calculate the width of our texts and to wrap it manually.
Finally we have to convert the SVG to a PNG, because the most of social media platforms do not support SVG.
This approach could work, but requires a lot of code and it is very complicated.

Headless browser

If all these solutions have problems with wrapping texts or require us to build the image with an external tool,
why could we just use HTML+CSS to define our image?
This is possible!
We can create our card with HTML+SVG+CSS, open a browser and create a screenshot of the result.
I've used this approach in the past and it worked well.
The problem is that the process is very slow.
This example creates the cards during the build.
Creating the cards during the build requires external caching, because it slows down the build extremely.
Also generating cards with this approach in a serverless function is often not possible,
because it requires a browser within the function which breaks the size limit of those functions.

@vercel/og

@vercel/og promises a new way of generating social media cards, which does not have the downsides of the other approaches.
The library uses Satori under the hood.
Satori describes itself as follows:

Enlightened library to convert HTML and CSS to SVG.

We can use HTML+SVG+CSS to create an image without the requirement to start a browser for a screenshot.
This sounds exactly like the solution I've been looking for.
So let's try it out.

Hello World

First we have to install the package from the npm registry:

pnpm add @vercel/og
# or with yarn
yarn add @vercel/og
# or with npm
npm install @vercel/og

After the installation we have to create an edge function, which renders our social media card.

import { ImageResponse } from "@vercel/og";

export const config = {
  runtime: "experimental-edge",
};

export default function () {
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 128,
          background: "white",
          width: "100%",
          height: "100%",
          display: "flex",
          textAlign: "center",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        Hello world!
      </div>
    ),
    {
      width: 1200,
      height: 600,
    }
  );
}

This was easy, so lets try to create something more complicated.

The goal

I've headed over to figma and started to create an example social media card.
I've ended with the following:

Ok, now lets see if we can implement this with @vercel/og.

The implementation

The first hurdle that I had to overcome was the usage of custom fonts.
The figma template uses Raleway and Cabin.
These are the same fonts which are used on the website.

Fonts

Unfortunately we can't use the @next/font package with Satori.
So we have to copy the font files to our project.

It looks like Satori has problems with dynamic fonts. Therefore only static fonts should be used and we have to load each weight used separately.

In an edge function we can't access the filesystem, but we can use fetch to load the fonts:

const ralewayBold = fetch(new URL(`../../../../content/fonts/Raleway-Bold.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

const cabinSemiBold = fetch(new URL(`../../../../content/fonts/Cabin-SemiBold.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

const cabinMedium = fetch(new URL(`../../../../content/fonts/Cabin-Medium.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

Than we have to configure our fonts in the ImageResponse:

return new ImageResponse(<div>...</div>, {
  width: 1200,
  height: 630,
  fonts: [
    {
      name: "Raleway",
      data: await ralewayBold,
      style: "normal",
      weight: 700,
    },
    {
      name: "Cabin",
      data: await cabinMedium,
      style: "normal",
      weight: 400,
    },
    {
      name: "Cabin",
      data: await cabinSemiBold,
      style: "normal",
      weight: 600,
    },
  ],
});

Now we are able to use the fonts in our jsx:

<div style={{ fontFamily: '"Cabin"' }}>Hello from Cabin</div>

Pay attention to the additional double quotes around the font name.
If we don't wrap the font in double quotes, @vercel/og will not use the font.

Tailwind

@vercel/og offers experimental Tailwind support and
I love Tailwind so I decided to use it.

In order to use Tailwind utilities, we can use the tw attribute on any element:

<div tw="rounded-xl border-2 border-zinc-700 shadow-lg"></div>

The first problem I've noticed is that my Tailwind config was not used.
It looks like @vercel/og uses the default config and
ignores the configuration of the project.

The second problem I've noticed is that not all utilities seem to work.
I'm not sure what the reason for that is, but some utilities work and others not.
For example the gradient utilities are not working, although those CSS properties are supported by Satori.
Maybe utilities that use CSS variables are not supported?
However, the following utilities I want to use are not working as expected:

bg-gradient-*, from-*, via-* and to-*
object-cover
rotate-*

Another problem took me some time.
In a normal Tailwind project,
the Tailwind preflight is loaded,
which removes the default browser margins and paddings from each element.
This does not happen for @vercel/og and
it took me some time to figure out where the spacings were coming from.
I've fixed it by just using div and span tags.
Semantics of elements could be ignored here,
because in the end we will create an image and all the elements will be gone anyways.

By the way, the debug option on the ImageResponse is pretty handy.
If it is used, every element gets a colored border,
which helps to determine which element takes how much space.

Ok, enough about problems and workarounds, here is the code:

import { ImageResponse } from "@vercel/og";
import { allPosts } from "contentlayer/generated";
import { NextRequest } from "next/server";

export const config = {
  runtime: "experimental-edge",
};

const ralewayBold = fetch(new URL(`../../../../content/fonts/Raleway-Bold.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

const cabinSemiBold = fetch(new URL(`../../../../content/fonts/Cabin-SemiBold.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

const cabinMedium = fetch(new URL(`../../../../content/fonts/Cabin-Medium.ttf`, import.meta.url)).then((res) =>
  res.arrayBuffer()
);

const Image = async (req: NextRequest) => {
  const slug = req.nextUrl.pathname.replace("/api/og/posts/", "");
  const post = allPosts.find((p) => slug === p._raw.flattenedPath);
  if (!post) {
    return new Response(
      JSON.stringify({
        message: "Could not find post with slug: " + slug,
      }),
      {
        status: 404,
      }
    );
  }

  return new ImageResponse(
    (
      <div
        tw="w-full h-full p-4 flex"
        style={{
          backgroundImage: "linear-gradient(to right, #0891B2, #164E63)",
          fontFamily: '"Cabin"',
        }}
      >
        <div tw="rounded-xl border-2 border-zinc-700 w-full h-full p-4 flex bg-zinc-800 shadow-lg">
          <img
            width="375"
            height="562"
            src={post.image}
            tw="rounded-xl border-2 border-zinc-700"
            style={{ objectFit: "cover" }}
          />
          <div tw="flex flex-col px-6 w-[740px] h-full justify-between">
            <div tw="flex flex-col">
              <span
                tw="text-7xl font-bold text-zinc-50 mb-6"
                style={{
                  fontFamily: '"Raleway"',
                }}
              >
                {post.title}
              </span>
              <span tw="text-5xl text-zinc-300">{post.summary}</span>
            </div>
            <div tw="flex justify-between items-end w-full text-zinc-400 text-xl">
              <span>{post.readingTime}</span>
              <div
                tw="flex text-4xl font-bold"
                style={{
                  fontFamily: '"Raleway"',
                }}
              >
                <span tw="text-zinc-50">sdorra</span>
                <span tw="text-cyan-400">.dev</span>
              </div>
              <span>{post.date.substring(0, post.date.indexOf("T"))}</span>
            </div>
          </div>
          <div
            tw="w-32 h-32 border-t-2 border-t-zinc-700 border-l-2 border-l-zinc-700 bg-zinc-800 rounded-full absolute left-[324px] bottom-[59px]"
            style={{
              transform: "rotate(-45deg)",
            }}
          />
          <div tw="absolute left-[338px] bottom-[68px] flex items-center">
            <img
              tw="rounded-full border-2 border-zinc-700"
              width="110"
              height="110"
              src="https://avatars.githubusercontent.com/u/493333"
            />
            <p tw="ml-6 text-4xl font-semibold text-zinc-400">Sebastian Sdorra</p>
          </div>
        </div>
      </div>
    ),
    {
      width: 1200,
      height: 630,
      debug: false,
      fonts: [
        {
          name: "Raleway",
          data: await ralewayBold,
          style: "normal",
          weight: 700,
        },
        {
          name: "Cabin",
          data: await cabinMedium,
          style: "normal",
          weight: 400,
        },
        {
          name: "Cabin",
          data: await cabinSemiBold,
          style: "normal",
          weight: 600,
        },
      ],
    }
  );
};

export default Image;

With about 120 lines of code I was able to create the following image:

Now it is time to deploy it to vercel.

Edge function size limit

The first deployment to vercel ends with the following error: Provided Edge Function is too large.

It took me some time to figure out what is going on.
I've created a separate post about this problem together with my workaround.

Unsplash image size

After I worked my way around the size limitation of the edge function,
the deployment was successful but the og endpoint responded with an error 500.
The error in the vercel log did not help at all.
So I started to look at the code and began to comment out parts of the code. Fortunately
it didn't take very long to find out that the image of the post was the problem.
It looked like there is another size limitation.
The image was loaded from Unsplash and about 7mb in size.
Luckily Unsplash has an api to resize the image,
so we can fetch the image in exactly the size we need.

const createImageUrl = (src: string, width: number, height: number) => {
  if (src.startsWith("https://images.unsplash.com/") && !src.includes("?")) {
    return `${src}?fit=crop&w=${width}&h=${height}`;
  }
  return src;
};

<img
  width="375"
  height="562"
  src={createImageUrl(post.image, 375, 562)}
  tw="rounded-xl border-2 border-zinc-700"
  style={{ objectFit: "cover" }}
/>;

After this fix we are able to generate social media cards on our production site.

Meta tags

Now it is time to link our social media cards in the header of our post page,
so that the social media networks are able to find the image.
Therefore we are creating a head.tsx file with the following content:

import { allPosts } from "contentlayer/generated";

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

const fqdn = process.env.NEXT_PUBLIC_FQDN ? process.env.NEXT_PUBLIC_FQDN : "sdorra.dev";

const Head = ({ params }: Props) => {
  const post = allPosts.find((p) => p._raw.flattenedPath === params.slug);
  if (!post) {
    return null;
  }
  return (
    <>
      <title>{post.title}</title>
      <meta name="description" content={post.summary} />

      <meta property="og:url" content={`https://${fqdn}/posts/${post._raw.flattenedPath}`} />
      <meta property="og:type" content="article" />
      <meta name="og:title" content={post.title} />
      <meta name="og:description" content={post.summary} />
      <meta property="og:image" content={`https://${fqdn}/api/og/posts/${post._raw.flattenedPath}`} />

      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:domain" content={fqdn} />
      <meta property="twitter:url" content={`https://${fqdn}/posts/${post._raw.flattenedPath}`} />
      <meta name="twitter:title" content={post.title} />
      <meta name="twitter:description" content={post.summary} />
      <meta property="twitter:image" content={`https://${fqdn}/api/og/posts/${post._raw.flattenedPath}`} />
    </>
  );
};

export default Head;

We use og tags which are accepted by most of the social media sites.
Except Twitter where I've had strange results if I only used og tags.
So I've added the Twitter tags besides the og tags.

Ensure that the image url is a complete url with scheme and hostname. The most social media sites do not render images with a relative url.

Now we can test the results with socialsharepreview.

Conclusion

Even if there are a few stumbling blocks with @vercel/og,
it is the best solution for social media cards I've worked with so far.

RSS Feed with Next.js

Sebastian Sdorra — Wed, 07 Dec 2022 20:54:27 +0000

A good blog needs an RSS feed, even if hardly anyone seems to use an RSS reader anymore.
This article will explain how to create a RSS feed for a static blog.
In this example we will use contentlayer,
but it should work with other data sources too.

Feed generator

First we need a script to create the feed from our posts.
The script will load the generated posts from the contentlayer directory.

import { allPosts } from "../.contentlayer/generated/index.mjs";

I had to specify the whole path including the extension, otherwise node threw errors at me.

After that we use the feed library to create the feed and
to convert our posts into RSS items.
First we have to install the library and install date-fns as well.
We need date-fns later to simplify working with dates.

pnpm add -D feed date-fns

# or with yarn
yarn add -D feed date-fns

# or with npm
npm install --save-dev feed date-fns

Than we can create the feed and specify some information about our blog e.g.:

title
description
url
language

This could look as follows.

import { Feed } from "feed";

const feed = new Feed({
  title: "Example blog",
  description: "Description for the awesome example blog",
  id: "https://blog.example.com",
  link: "https://blog.example.com",
  language: "en",
  favicon: "https://blog.example.com/favicon.ico",
  copyright: "All rights reserved 2022, Your Name",
  author: {
    name: "Your Name",
    email: "your.name@exmaple.com",
    link: "https://blog.example.com",
  },
});

Now we can convert our blog posts to feed items.
We start by sorting the posts by their date.
Then we convert each post to a RSS item and add it to the feed.

import { compareDesc, parseISO } from "date-fns";

allPosts
  .sort((a, b) => compareDesc(new Date(a.date), new Date(b.date)))
  .forEach((post) => {
    const url = `https://example.com/posts/${post._raw.flattenedPath}`;
    feed.addItem({
      id: url,
      link: url,
      title: post.title,
      description: post.summary,
      date: parseISO(post.date),
      category: post.tags.map((name) => ({ name })),
      image: post.coverImage,
      author: [{
        name: "Your Name",
        email: "your.name@exmaple.com",
        link: "https://blog.example.com",
      }],
    });
  });

The feed does not contain the content of our posts. If we want to include the content we can attach it as HTML.
Now we should have everything in place and we can write the feed to the public directory:

import { writeFileSync } from "fs";

writeFileSync("./public/rss.xml", feed.rss2(), { encoding: "utf-8" })

The complete script should like the following.

import { compareDesc, parseISO } from "date-fns";
import { Feed } from "feed";
import { writeFileSync } from "fs";
import { allPosts } from "../.contentlayer/generated/index.mjs";

const feed = new Feed({
  title: "Example blog",
  description: "Description for the awesome example blog",
  id: "https://blog.example.com",
  link: "https://blog.example.com",
  language: "en",
  favicon: "https://blog.example.com/favicon.ico",
  copyright: "All rights reserved 2022, Your Name",
  author: {
    name: "Your Name",
    email: "your.name@exmaple.com",
    link: "https://blog.example.com",
  },
});

allPosts
  .sort((a, b) => compareDesc(new Date(a.date), new Date(b.date)))
  .forEach((post) => {
    const url = `https://example.com/posts/${post._raw.flattenedPath}`;
    feed.addItem({
      id: url,
      link: url,
      title: post.title,
      description: post.summary,
      date: parseISO(post.date),
      category: post.tags.map((name) => ({ name })),
      image: post.coverImage,
      author: [{
        name: "Your Name",
        email: "your.name@exmaple.com",
        link: "https://blog.example.com",
      }],
    });
  });

writeFileSync("./public/rss.xml", feed.rss2(), { encoding: "utf-8" });

Discoverability

In order for RSS readers to find our feed, we can help them with a link tag in the head of our page.
For Next.js 13 and the app directory, the root layout is the right place for the link tag, since that is how it's included in every page.

import { FC, PropsWithChildren } from "react";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  <html lang="en">
    <head>
      <link rel="alternate" type="application/rss+xml" title="example.com rss feed" href="/rss.xml" />
    </head>
    <body>{children}</body>
  </html>
);

export default RootLayout;

Build

Now it's time to add our feed generator to the build:

{
  "scripts": {
    "build": "next build && node scripts/rss.mjs"
  }
}

Whenever our page is build using the build script, our RSS feed gets build afterwards.
The order is important, because contentlayer have to run first in order to generate the posts.

Git

Because our RSS feed is generated, we should exclude it from our repository:

/node_modules
/.next/
.contentlayer
public/rss.xml

If we would not do that, we would see changes to the rss.xml every time we work on our posts.

Use dark mode with TailwindCSS and Next.js

Sebastian Sdorra — Wed, 07 Dec 2022 10:22:27 +0000

Enabling dark mode with Tailwind couldn't be easier, just use the dark variant e.g.:

<h1 className="text-zinc-700 dark:text-zinc-300">Hello dark mode</h1>

In the snippet above the text-zinc-700 is used in light mode andtext-zinc-300 is used if dark mode is enabled on your operating system. This works because Tailwind uses prefers-color-scheme media query. But if we want to allow the user to switch between light and dark mode, things are getting complicated.

Dark mode toggle

First we have to enable the manual dark mode toggle in Tailwind's config:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./app/ **/*.tsx", "./pages/** /*.tsx", "./components/**/*.tsx"],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [],
};

By setting darkMode to class Tailwind applies the dark mode variant if a parent element has the class dark. Now we can implement a simple dark mode toggle:

"use client";

import { Moon, Sun } from "lucide-react";
import { useState } from "react";

const DarkModeToggle = () => {
  const [mode, setMode] = useState("light");

  const onClick = () => {
    const toggle = document.documentElement.classList.toggle("dark");
    const theme = toggle ? "dark" : "light";
    setMode(theme);
  };

  return (
    <button onClick={onClick} title={`Enable ${mode === "dark" ? "light" : "dark"} mode`}>
      {mode === "dark" ? <Sun /> : <Moon />}
    </button>
  );
};

export default DarkModeToggle;

This example renders a moon icon (from the lucide-react package). After a click on the icon, the dark class is toggled on the html element and the icon switches to a sun. If the dark class is applied to the html element, we should see that the dark mode is applied to our page.

But if we refresh the page, we are back on light mode. So we need a way to persist our selection.

Persisting the selection

According to the Tailwind docs a good way to store the selected mode is the localStorage. So we could extend our toggle button and store the selection in the localStorage:

"use client";

import { Moon, Sun } from "lucide-react";
import { useState } from "react";

const DarkModeToggle = () => {
  const [mode, setMode] = useState("light");

  const onClick = () => {
    const toggle = document.documentElement.classList.toggle("dark");
    const theme = toggle ? "dark" : "light";
    window.localStorage.setItem("theme", theme);
    setMode(theme);
  };

  return (
    <button onClick={onClick} title={`Enable ${mode === "dark" ? "light" : "dark"} mode`}>
      {mode === "dark" ? <Sun /> : <Moon />}
    </button>
  );
};

export default DarkModeToggle;

Now we are able to apply the selected mode on page load. We should do this as early as possible during the rendering of our page to avoid flickering:

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  <html lang="en">
    <head>
      <script
        dangerouslySetInnerHTML={{
          __html: `
          if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
            document.documentElement.classList.add('dark')
          } else {
            document.documentElement.classList.remove('dark')
          }
          `,
        }}
      />
    </head>
    <body>{children}</body>
  </html>
);

export default RootLayout;

The snippet above adds the dark class, if the theme key in the localStorage is set to dark or if the key is not set and the prefers-color-scheme matches dark. Otherwise the class is removed from the html element.

Finally, we should reflect the current mode in our toggle button.

"use client";

import { Moon, Sun } from "lucide-react";
import { useEffect, useState } from "react";

const DarkModeToggle = () => {
  const [mode, setMode] = useState("light");
  useEffect(() => {
    if (document.documentElement.classList.contains("dark")) {
      setMode("dark");
    } else {
      setMode("light");
    }
  }, []);

  const onClick = () => {
    const toggle = document.documentElement.classList.toggle("dark");
    const theme = toggle ? "dark" : "light";
    window.localStorage.setItem("theme", theme);
    setMode(theme);
  };

  return (
    <button onClick={onClick} title={`Enable ${mode === "dark" ? "light" : "dark"} mode`}>
      {mode === "dark" ? <Sun /> : <Moon />}
    </button>
  );
};

export default DarkModeToggle;

We use an effect to check if the html element has the dark class, to reflect the initial state of the dark mode toggle.

Now we have everything in place, we should be able to toggle between light and dark mode and our selection should be persisted.

But if we look in the console log of our browser we see an error.

Hydration error

react_devtools_backend.js:4026 Warning: Prop `className` did not match. Server: "dark" Client: ""
    at html
    at ReactDevOverlay (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/components/react-dev-overlay/internal/ReactDevOverlay.js:53:9)
    at HotReload (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/components/react-dev-overlay/hot-reloader-client.js:19:11)
    at Router (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/components/app-router.js:74:11)
    at ErrorBoundaryHandler (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/components/error-boundary.js:28:9)
    at ErrorBoundary (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/components/error-boundary.js:40:11)
    at AppRouter
    at ServerRoot (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/app-index.js:113:11)
    at RSCComponent
    at Root (webpack-internal:///./node_modules/.pnpm/next@13.0.3_biqbaboplfbrettd7655fr4n2y/node_modules/next/dist/client/app-index.js:130:11)

We see this error, because of the fact that the server renders the html element without the dark class, even if dark mode is enabled. But we add the class before react hydrates the document.

~~I don't know how to avoid this error, but the good news is that the error only shows up in development mode.~~

The error can be suppressed by using the suppressHydrationWarning property on the html element:

<html lang="en" suppressHydrationWarning={true}>

This will suppress the warning only for the html element, not for its children.

How to create a sitemap with Next.js app directory

Sebastian Sdorra — Wed, 07 Dec 2022 05:34:04 +0000

To gain the best of SEO we should use a sitemap for our sites. Search engines like Google can use those sitemaps to crawl our sites more efficiently.

Create a sitemap

We could simply create a sitemap, like the following and put it into the public directory of our app:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://sdorra.dev/</loc>
  </url>
  <url>
    <loc>https://sdorra.dev/posts/2022-11-15-sitemaps-with-appdir</loc>
  </url>
</urlset>

But this is very error prone. Every time we create a new blog post or add another page to the site we have to manually modify the sitemap.

I think we can do better.

Generate sitemap

We could generate our sitemap at build time by traversing the app directory and write it afterwards to the public directory:

import { writeFile } from "fs/promises";
import { globby } from "globby";

const PAGE = "https://sdorra.dev";

const createPath = (p) => {
  const path = "/" + p.replace("page.tsx", "");
  if (path.endsWith("/") && path.length > 1) {
    return path.substring(0, path.length - 1);
  }
  return path;
};

const collectPaths = async () => {
  const paths = await globby("./**/page.tsx", {
    cwd: "app",
  });
  return paths.map(createPath);
};

const createSitemap = async (routes) => {
  return `
  <?xml version="1.0" encoding="UTF-8"?>
  <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      ${routes
        .map((route) => {
          return `
            <url>
                <loc>${`${PAGE}${route}`}</loc>
            </url>
          `;
        })
        .join("")}
  </urlset>
  `;
};

(async () => {
  const paths = await createPaths();
  const sitemap = await createSitemap(paths);
  await writeFile("./public/sitemap.xml", sitemap, { encoding: "utf-8" });
})();

The snippet above uses globby to find each page.tsx in the app directory (collectPaths). After the file paths are collected, each path is transformed to the url path (createPath). The last step is to create the sitemap (createSitemap) and write to the public directory.

This works well, until we introduce dynamic routes to our app.

Dynamic routes

A dynamic route can be identified by the square brackets around a variable e.g.: app/posts/[slug]/page.tsx. To handle those routes in the sitemap generator could become very tricky.

I will use a simple example how it could be implemented if the site uses contentlayer:

import { writeFile } from "fs/promises";
import { globby } from "globby";
import { allPosts } from "../.contentlayer/generated/index.mjs";

const PAGE = "https://sdorra.dev";

const expandPath = (p) => {
  if (p === "/posts/[slug]") {
    return allPosts.map((p) => `/posts/${p._raw.flattenedPath}`);
  }
  return [p];
};

const createPath = (p) => {
  const path = "/" + p.replace("page.tsx", "");
  if (path.endsWith("/") && path.length > 1) {
    return path.substring(0, path.length - 1);
  }
  return path;
};

const collectPaths = async () => {
  const paths = await globby("./**/page.tsx", {
    cwd: "app",
  });
  return paths.map(createPath).flatMap(expandPath);
};

// rest of scripts/sitemap.mjs

The first interesting line in this snippet is the import of the posts generated by contentlayer (allPosts). I had to specify the whole path including extension, otherwise typescript threw errors at me. In the expandPath function we will check the path and if it is our dynamic route, we will replace it with the slugs of all posts. This function is finally used by the collectPath function to create our flat array of paths.

Warning: This method covers only the basics. If you are use something like grouped routes or the old pages directory is used in addition to the app directory, you have to go a few extra miles.

Build

Now it is time to add our generator to the build:

{
  "scripts": {
    "build": "next build && node scripts/sitemap.mjs"
  }
}

Whenever our page is build using the build script, our sitemap is build afterwards. The order is important, because contentlayer have to run first in order to generate our content types.

robots.txt

We could specify the url to our sitemap in the robots.txt, this makes it easier for search engines to find our sitemap. If we use the default path /sitemap.xml most of the search engines should find it without the entry in the robots.txt. However the entry could look like the following:

User-Agent: *
Allow: /

Sitemap: https://sdorra.dev/sitemap.xml

Git

Since our sitemap is generated, we should not include it in our repository. So we should ignore it:

/node_modules
/.next/
.contentlayer
public/sitemap.xml

If we would not do that, we would see changes to the sitemap.xml every time we change the structure of the page.

Next.js app directory and 100% height

Sebastian Sdorra — Tue, 06 Dec 2022 13:39:07 +0000

Update: This article describes the behavior of Next.js between version 13.0.0 and version 13.0.7. Version 13.0.7 removes the extra div, see section the fix for details.

The new app directory of Next.js 13 introduces the great concepts of layouts. But they come with a price ... a div wrapper. Each layout wraps its children in a div. This could break designs which are using a height of 100%.

As timneutkens (one of the Next.js maintainers) says, the problem is temporary but it has to be fixed in react:

First off: We totally understand your struggle because of the added elements.

It's indeed added for now to handle keeping the right section of the page in view when navigating between pages. Unlike in pages the new router has improved scroll and focus handling. It ensures only the changed part is scrolled into view and put focus on.

Right now this is a trade-off as React doesn't allow finding the DOM node from a component and it has to interplay with server components which can't just get a ref passed as they render outside the browser.

We're planning to create a RFC for React to solve the "selecting a underlying DOM node of a component" for this case.

The original post can be found in the answers of this github discussion.

The workaround

The good news Next.js 13.0.1 add a data attribute (data-nextjs-scroll-focus-boundary) to those div wrappers. With this attribute, we are now able to apply styles to the wrapper. For example, we can specify display: contents as suggested by bmcmahen on the same discussion:

[data-nextjs-scroll-focus-boundary] {
  display: contents;
}

Using display: contents prevent the wrapper from affecting the layout at all.

developer.mozilla.org describes display: content as follows:

These elements don't produce a specific box by themselves. They are replaced by their pseudo-box and their child boxes. Please note that the CSS Display Level 3 spec defines how the contents value should affect "unusual elements" — elements that aren't rendered purely by CSS box concepts such as replaced elements.

It sound perfect for our use case, but they mention also accessibility issues:

Due to a bug in browsers, this will currently remove the element from the accessibility tree — screen readers will not look at what's inside.

Here is blog post from Adrian Roselli, which describes the problem in more detail: Display: Contents Is Not a CSS Reset

I'm not really sure, if the accessibility bugs still exists, accordingly to caniuse.com there are still issues with it.

So if our only problem is the 100% height, perhaps we should just use:

[data-nextjs-scroll-focus-boundary] {
  height: 100%;
}

The Fix

A few weeks after this article was published Tim Neutkens, tweets the following:

https://twitter.com/timneutkens/status/1601349358255214592

A few days later Next.js 13.0.7 was released, which contains the following fix:

https://github.com/vercel/next.js/pull/43717

So if you run Next.js 13.0.7 or newer you do not need the workaround anymore.