DEV Community: Emma Goto 🍙

Fun with Hardcover's Book API: A quick reference

Emma Goto 🍙 — Sat, 26 Oct 2024 08:16:03 +0000

I'm a longtime Goodreads user, but have always wanted to try something better when it comes to tracking my books. So I've recently started using Hardcover, a competitor run by a small indie team. It's still in the early days, and I know it's hard to beat something as large as Goodreads, but I'm hopeful!

One of the great things about Hardcover is that, unlike Goodreads, it has an API that is free-to-use and lets you query for any data on the books that are stored in Hardcover. It also can be used to do basically anything you would be able to do yourself in the Hardcover UI, like update the status of books you are
reading, add books to lists and more.

How I'm using Hardcover's API

Right now I'm using the API to generate the book review section of my site. I fetched all my reviews from Hardcover, and am storing them in a JSON file. I then loop through the reviews in this list, and render them all on the page.

I wasn't too sure what to do about really short reviews, so for the moment I've settled on rendering the reviews as-is on the page if they are under 360 characters, and linking out to a separate page if they are more than that.

I also added a search bar, which will search through all my reviews, and I have some text blurring set up if there are spoilers on the review.

In the future I'd like to add a way to filter by the star rating, and by genre as well.

Getting started with Hardcover's API

Hardcover's API is also still in an early-access mode, and there isn't any proper documentation yet, so in this post I'll go over some of the queries I found useful so far. Hardcover's Discord server is also a great place to get answers to your questions.

You'll first need to go to your settings page, and get your Hardcover API key. Then you can test out your queries in Hardcover's GraphQL console.

Getting all the books you have read

Starting off with a basic GraphQL query, we can filter using the status_id to get a list of titles of all the books you have marked as “read” in Hardcover:

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

We've wrapped it in me which is what you can use to query on anything specific to your user.

The way the status_id value works is:

1: A “want to read” book
2: An “currently reading” book
3: A “read” book
5: “A did not finish” book

Getting the author of a book

If you search for cached_contributors, you'll get an array containing a list of “contributors” to a book. This will contain a predetermined set of data, like the contributor's name, ID, and image.

book {
  cached_contributors
}

The reason they're “contributors” and not “authors” is that it can also contain the names of people who have translated the book. If there are multiple authors, they will also all be in the list. If you're querying on a regular fiction book with one author, using the first item in the list will usually be fine.

The cached version is faster to query, but if there was something specific you wanted, you can also query on the non-cached contributions:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Getting a book's Hardcover URL

If you wanted to get the book's link on Hardcover, you can query for its slug:

book {
  slug
}

A slug is the string after the domain name of the website, e.g. on emgoto.com/hardcover-book-api, the “hardcover-book-api” bit is the slug.

So once you get the slug, you'll just need to prepend https://hardcover.app/books/ to the beginning of it to create your Hardcover URL.

Getting the genre tags on a book

The genre tag system in Hardcover is user-generated. You can query on the cached_tags, which will return you the tags in order from most-tagged to least.

book {
  cached_tags
}

Once you have the full list of tags, you can use cached_tags['Genre'] to get the genre-specific ones.

If a lot of people have tagged a particular book as fiction, that will be the first genre that shows up in the list. Interestingly people love to tag their books as fantasy, and so this genre often shows up before the fiction tag. People love tagging their books as fantasy so much, that sci-fi books like Dune even end up with both sci-fi and fantasy tags as well.

If you are going to use this data, I recommend doing a little bit of clean-up on it first. For example if the book has both fantasy and sci-fi as a genre tag, only use the one that comes first in the list and discard the other one, since that is more likely to be accurate.

Adding a book to your “to read" list

So far I've only touched on fetching data, but you can also use Hardcover's API to manipulate data - of course you can't touch anyone else's things, but anything that you could do on your own Hardcover account is fair game.

If you have a book's ID, you can add it to your “to read” list by setting its status_id to 1:

mutation addBook {
  insert_user_book(object: {book_id: 123, status_id: 1}) {
    id
  }
}

Getting your book reviews

This is what I use to fetch all the reviews I have written in Hardcover:

{
  me {
    user_books(
      where: { _and: [ 
        {has_review: {_eq: true}},
        {status_id: {_eq: 3 }}
      ]}
      order_by: [
        { date_added: desc },
        { reviewed_at: desc }
      ]
    ) {
      reviewed_at
      date_added
      review_raw
      rating
      book {
        title
      }
    }
  }
}

Nearly all of my books and reviews are imported from Goodreads, and I think sometimes the data gets a little bit messed up in the import. I found that sorting it by both dated_added and reviewed_at was more accurate.

I used the review_raw value to get the review text, which is doesn't include any formatting like newlines. This unfortunately means if you have multiple paragraphs in your review, the API spits it out all as one long paragraph like this:

this is the end of one paragraph.And this is the start of the next

With JavaScript, I got around this by doing a regex like the following:

const text = review_raw
    .replace(/(?<=[.!?])(?=[A-Z])/g, '\n\n');

If there are any periods with no spaces after them, you can make a guess that this should be a new paragraph and add the double newline \n\n. Which creates a new paragraph.

Another downside is that spoiler tags are also missing, so you'll have to add these in manually.

There is also a review_html value, which I thought might be more useful, but unfortunately it always seems to be null for me. Similarly, if you have a review with spoilers, there is a review_has_spoilers value, but for all the books I've imported from Goodreads, this value is false so you may not be able to rely on it.

Searching for a book by title and/or author

Hardcover's book search is pretty accurate, but they don't have a 1-1 version of this in their API. There's a lot of ways you could try and mimic their search behaviour, but a quick way to get started would be to search on title, using _eq:

{
  books (
    order_by: {users_read_count: desc}
    where: {title: {_eq: "Dune"}}
    limit: 5
  ) {
    users_read_count
    title
  }
}

I ordered the list of books by users_read_count, as the likelihood is that the book called Dune with the highest number of readers is going to be the Dune that you are looking for.

If you want to filter by title and author, the filter query will look like this:

where: {_and: [
  {title: {_eq: "Dune"}},
  {contributions: {author: {name: {_eq: "Frank Herbert"}}}}
]},

If you didn't want to do exact string matching, you can use the _ilike query instead, which doesn't match on cases, so using lower case will still work:

{_ilike: "frank herbert"}

You can also use % characters as wildcards with _ilike, so you can do

{_ilike: "%frank%"}

Which will match any author that contains the word “frank”.

As a side note, since Hardcover uses Hasura, Googling for “how to do X in Hasura” will generally bring up how you can do these sort of more complicated queries.

Getting books in your Hardcover Lists

As well as the standard “want to read” and “read” lists, Hardcover also has a separate custom lists feature. To grab all of your lists, and the books inside of them, you can do the following:

{
  me {
    lists(order_by: {created_at: desc}) {
      id
      name
      slug
      list_books {
        book {
          title
        }
      }
    }
  }
}

Adding a book to a list

If you wanted to add a book to a list, first you would need to grab the list ID and the book's ID. Then it's easy as the following:

mutation addBook {
  insert_list_book(object: {book_id: 123, list_id: 123}) {
    id
  }
}

Making an API call with JavaScript

Once you want to move out of the GraphQL console, you can make API calls using fetch(). As a really quick example, here's me fetching all my reviews (I've abbrievated it down a bit):

const HARDCOVER_API_KEY = 'Bearer ...';

const query = `
{
  me {
    user_books(
      where: {has_review: {_eq: true}}
      order_by: [
        { date_added: desc },
        { reviewed_at: desc }
      ]
    ) {
      review_raw
      rating
      book {
        title
      }
    }
  }
}`;

const fetch('https://api.hardcover.app/v1/graphql', {
    headers: {
        'content-type': 'application/json',
        authorization: HARDCOVER_API_KEY,
    },
    body: JSON.stringify({ query }),
    method: 'POST',
})
  .then((response) => response.json())
  .then(({ data }) => {
    const reviews = data.me[0]['user_books'].map(review => {
      // Just as an example of what you could do
      const author = cached_contributors[0].author.name;
      console.log("author!", author);
    });
  });

A programming pro-tip that I have to make constructing fetch calls easier is if you:

Go to Hardcover
Search for graphql in the Network tab
Find one that looks useful and is returning info
Right click the network call > Copy > Copy as fetch

It will copy for you a fetch call similar to the one I've pasted above, which you can then use in your own code.

A note on rate limiting

Once you move out of the GraphQL console and start doing things in a script, you may run into errors or rate limiting issues if you try and do too many things at the same time.

For example, when adding a new book to a list, I find that trying to add two at the same time will error in the API, probably because it is trying to add two books to the same position in the list.

Similarly, if you tried to make 100 different calls to search for a book based on its title, some of these calls will time out. If you spread them out and do one every second like the following, then you shouldn't have any issues:

let delay = -1000;
const delayIncrement = 1000;

const addBooksToList = async () => {
  const promises = books.map((book) => {
    delay += delayIncrement;
    return new Promise((resolve) =>
      setTimeout(resolve, delay))
      .then(() => addBookToList(book.id))
  });

  const results = await Promise.all(promises);
};

Also, if you grabbed the image URL of a book from Hardcover, and then attempted to load the images of 100 books at the same time on your page, the API will rate limit you, and some of the images will not load. I recommend putting a loading=lazy in your image tags like so:

<img
  loading="lazy"
  src={image.url}
/>

This way, the images will only load when a user scrolls down to view them.

And that's it! I'm keen to see where Hardcover goes next - I'm hoping it does well, and finally we have a Goodreads-killer on our hands. If you'd like to follow me on Hardcover, I fortuitously have managed to snag the @emma handle.

2021 in review: my second year of blogging

Emma Goto 🍙 — Sat, 01 Jan 2022 06:44:27 +0000

2021 was a much more quiet year on my blog than compared to 2020. Continuing the tradition of my 2020 review post, here’s how my site has performed over this past year.

My most popular posts on emgoto.com

I published 14 posts on my website in 2021, and received 165,203 page views (according to Google Analytics):

I only received 25k views in 2020, so it's a pretty huge jump. One of my goals for this blog was to eventually hit 10k views a month, and I passed this milestone in May 🎉 This growth is largely due to my posts showing up more frequently in Google search results.

My top three posts were the following:

How to build a search bar in React (published Nov 2020)
Jest code coverage report explained (published April 2020)
Jest partial matching on objects, arrays and functions (published March 2021)

The search bar post in particular was a big success. It was a bit of fluke that I managed to hit upon this topic, actually. I built a search bar for my own site, and then decided to write a post about it since I didn't already see a good one out there.

My DEV.to statistics

After publishing a post on emgoto.com, I also cross-post it to DEV.to.

I started 2021 with 2,820 reactions, 40,848 views and 6,518 followers on DEV. Here’s how my DEV dashboard looked at the end of 2021:

You can see that the numbers didn’t have a significant increase (e.g. 40k views in 2020 to 53k views). Considering I only posted 13 new posts on DEV, it makes sense to see that lack of growth.

Since I didn’t have much of an audience for my blog in 2020, the DEV community was a great way to introduce people to my content. It’s become less important in 2021, compared to the growth in views from Google search results.

DEV also hosts some pretty fun hackathons. I participated in one in March, and won a runner's up prize.

Twitter, my newsletter, and making money

On Twitter, I went from 293 followers to 524. I don’t tweet much, so the growth may be people coming across my site on Google, and then deciding to give me a follow. Hi to any new followers, and thank you!

I have a “monthly” newsletter that I have yet to post anything to (oops), which now has 71 subscribers.

I added Carbon ads to my site at the end of October. In 2 months, I made about $40 in revenue. I do feel a bit bad, since I think the ad ruins the aesthetic of my site (ha). But for now I’ll be keeping it.

A foray into food blogging

Designing and coding a blog is the most fun part of blogging for me. So in April I decided to build a second blog devoted to Japanese food. In hindsight, 2021 wasn’t the best year to start a food blog, considering that we’re living through a pandemic. Sydney also had a multi-month lockdown where all the restaurants were closed. Right now everything has re-opened but I’m too scared to go because we’re seeing a huge surge in COVID cases.

Since emgoto.com has a dark colour scheme, for my food blog I decided I wanted to do the opposite and went for something brighter. It looked pretty boring though so I spiced it up by buying a stock image to use for the background.

Writing about eating food is a lot easier than writing about programming, so it’s also more fun. Although I’m not too sure how entertaining it is to read what I wrote (there’s only so many ways you can talk about how you enjoy food). But because it’s so much easier, the competition is probably a lot higher too. So this is more just a “for fun” blog than one that I actually see going anywhere.

I also learnt that photographing food is hard. My current technique involves handing my phone over to whoever I’m eating with and the chances are high that they are going to take better pictures than me. Maybe it’s a skill I can work on in 2022.

Honestly I have been too embarrassed to show this site to anyone but my mum so the site gets 0 hits, but if you happened to read this far you can go check out my food blog at japango.to.

A shoutout to the Blogging for Devs community

I joined the Blogging for Devs community towards the end of 2020. Unfortunately I haven’t been too active in the last half-year, but I would highly recommend it for anyone with a blog, or for anyone looking to start a blog in 2022. I’ve picked up a lot of useful SEO tips that I’ve implemented on my site, and I’ve gotten into the habit of making SEO tweaks to older posts to boost their page views as well.

Goodbye 2021 and hello 2022!

I don’t want to turn this post into too much of a downer so I’m just briefly mentioning it at the end, but 2021 really sucked for me. And that’s reflected in the amount of posts I’ve written this year compared to 2020. My motivation and passion for writing hasn’t quite recovered, so I’m not too sure yet what 2022 will look like for my blog. I don't have any big plans or goals, and I'm just going to take each day as it comes.

Fingers crossed for a better year in 2022!

Writing a script to cross-post to DEV.to

Emma Goto 🍙 — Wed, 29 Sep 2021 10:16:49 +0000

After publishing a post to my site, I usually cross-post it to DEV.to. Originally I would use their RSS feature and cross-posting was quite a painless process, but over time I've added new features to my blog like:

Line highlighting and code block headings (covered in my post on Gatsby code blocks)
MDX components
Additional Markdown frontmatter fields that aren’t used in DEV.to

Which meant that I had to keep making manual changes to all my posts to make them ready for publishing on DEV. To save me some time, I wrote a script to automate this process.

If you've never written a script before, I've written a post on renaming files with Node.js scripts which should give you a good overview.

The cross-posting workflow I follow now is this:

Publish a new post on my personal blog.
Go to DEV.to and refresh my RSS feed (explained below).
Run my devto.js script.
Double-check the draft on DEV.to, and then hit publish.

Hook up your RSS feed to DEV.to

I cross-post my posts to DEV.to via my site’s RSS feed. This way, I get the “Originally published at” message to show up underneath the title of my posts:

If you go to your DEV.to settings page, and click the Extensions option, you’ll have the opportunity to add an RSS feed:

Once you have hooked up your RSS feed, DEV.to will periodically check it to see if there are any new posts, and add the post in DEV as a draft.

After I publish a post on my own site, I go into DEV.to and hit the “Fetch feed now” button to make it show up straightaway. Unfortunately DEV doesn't have an API to do this step from within my script.

Run the script to update the draft post in DEV.to

To run this script, you’ll need your own DEV API key. I store mine in a .env file in my site’s repository:

// .env
DEV_API_KEY=<key_goes_here>

The script makes use of two of the DEV API’s endpoints:

Getting a user’s unpublished articles.
Updating the article. The unpublished articles endpoint will give us an ID we need to use.

My posts are stored on my repository with Markdown and frontmatter, in a format like this:

---
title: "Hello! This is the markdown file"
date: 2021-09-25
tags: ["react"]
---

Content of the post goes here.

![Image with alt text](./image.png)

The script will transform it into this on DEV:

---
title: "Hello! This is the markdown file"
published: false
tags: ["react"]
---

Content of the post goes here.

![Image with alt textt](https://emgoto.com/slug/image.png)

There’s three things to point out here:

I make sure the frontmatter has published: false so it stays in draft mode
I remove the date field. If you leave this value, DEV will set it as having been published at midnight of the date you specified. This can reduce the chance of your post actually getting views on DEV’s home page since it’s considered an “old” post.
There’s no DEV image API so you'll need to host the image yourself

The full version of the script is available on my site’s Github repository, and I’ve got a shortened version below that you can copy-paste.

#!/usr/bin/env node

const { readFile } = require('fs');
const { join } = require('path');
const glob = require('glob');
const fetch = require('node-fetch');

// I store my API key in a .env file
require('dotenv').config(); 

const updateArticle = (devArticleId, content) => {
    fetch(`https://dev.to/api/articles/${devArticleId}`, {
        method: 'PUT',
        headers: {
            'api-key': process.env.DEV_API_KEY,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            article: {
                body_markdown: content,
            },
        }),
    })
};

const updateFile = (content, slug) => {
    // Update frontmatter
    content = content.replace(/date: .*\n/, 'published: false\n');

    // Update images
    content = content.replace(
        /!\[(.+?)\]\(\.\/(.+?)\)/g,
        `![$1](https://emgoto.com/${slug}/$2)`,
    );

    // TODO: Any other changes to your content

    return content;
}

const devto = () => {
    // Looks for folders inside of "posts" folder that matches the given slug.
    const slug = process.argv[1];
    const file = [
        ...glob.sync(join(process.cwd(), 'posts', slug, 'index.mdx')),
    ][0];

    readFile(file, 'utf8', (err, content) => {
        if (err) reject(err);

        const title = content.match(/title: "(.*)"\n/)[1];
        content = updateFile(content, slug);

        fetch('https://dev.to/api/articles/me/unpublished', {
            headers: { 'api-key': process.env.DEV_API_KEY },
        })
            .then((response) => response.json())
            .then((response) => {
                if (response.length > 0) {
                    const draftTitle = response[0].title;
                    if (draftTitle === title) {
                        const devArticleId = response[0].id;
                        updateArticle(devArticleId, content);
                    }
                }
            })
    });
};

devto();

How to export from Ulysses to Markdown

Emma Goto 🍙 — Sun, 26 Sep 2021 03:37:19 +0000

I use the Ulysses text editor to write all my posts. Converting them into Markdown files for my blog isn’t as easy as copy-pasting, especially when things like frontmatter and images are involved.

So here's the script I use to convert Ulysses files to Markdown.

Right click a sheet in Ulysses and choose the Quick Export option. Choose the Textbundle format.
Save the Textbundle folder to your desired location. I save it inside the scripts folder of my repository.
Then run the following script to convert the Ulysses file to Markdown.

#!/usr/bin/env node

const { renameSync, unlink, rmdir } = require('fs');
const { join } = require('path');
const glob = require('glob');
const replace = require('replace-in-file');

const toFrontMatter = (title) =>
    `---
title: "${title}"
date: ${new Date().toISOString().substring(0, 10)}
tags: []
---`;

const ulysses = async () => {
    const file = glob.sync(
        join(process.cwd(), 'scripts', '**', '*.textbundle'),
    )[0];

    // Moves the .textbundle file to the /posts directory
    const slug = file.match(/\/([^\/]+).textbundle/)[1];
    const postsDirectory = join(process.cwd(), 'posts');
    let newFolder = `${postsDirectory}/${slug}`;
    renameSync(file, newFolder);

    // Move images out of assets folder
    const images = glob.sync(join(newFolder, 'assets', '*'));
    images.forEach((image) => {
        let imageName = image.match(/assets\/([^\/]+)/)[1];
        const newFolder = `${postsDirectory}/${slug}`;

        renameSync(image, `${newFolder}/${imageName}`);
    });

    // Remove redundant folder and files
    rmdir(`${newFolder}/assets`, () => {});
    unlink(`${newFolder}/info.json`, () => {});

    // Formats into frontmatter structure
    const headerRegex = /^# .*/g;
    const markdownPngRegex = /!\[.*\]\(assets.*png\)/g;

    const headerFn = (title) =>
        toFrontMatter(title.replace('# ', '').trim());
    const markdownPngFn = (line) => line.replace(/\(assets/, '(.');

    const options = {
        files: `${newFolder}/index.mdx`,
        from: [headerRegex, markdownPngRegex],
        to: [headerFn, markdownPngFn],
    };

    return replace(options);
};

ulysess();

You can run the script directly with:

node ./scripts/ulysses.js

Or you can add the script to your package.json file:

"scripts": {
    "uly": "./scripts/ulysses.js",
},

And then run it with yarn uly.

How the Ulysses to Markdown script works

Exporting a Ulysses file as a Textbundle saves it with the following file structure:

scripts
    ulysses-to-markdown.textbundle
        info.json
        text.md
        assets
            image.png

The script will rearrange it to look like this:

posts
    ulysses-to-markdown
        text.md
        image.png

The original Markdown file, directly from Ulysses, will look like this:

# How to export from Ulysses to Markdown

Here's the content of the post. 

![](assets/image.png)

And the script will convert it into this format:

---
title: "How to export from Ulysses to Markdown"
date: 2021-09-25
tags: []
---
Here's the content of the post. 

![](./image.png)

How to build an inline edit component in React

Emma Goto 🍙 — Wed, 22 Sep 2021 04:40:55 +0000

Inline editing allows users to edit content without navigating to a separate edit screen. In this tutorial, we’ll be building an accessible inline edit component in React. Here’s the final product:

We’ll also learn how to write some unit tests with React Testing Library. Let’s get started!

This tutorial assumes a basic understanding of React, including hooks.

If you want to jump straight to the full code, check out the React inline edit example on Codepen.

Inline editing and accessibility

When creating any React component, keep accessibility in mind. For example, your component should:

Work with only a keyboard
Use the correct HTML elements and other attributes to provide the most context to users

One way to approach writing an inline edit component is to have two separate components. One for a “view mode” and one for a “edit mode”:

// View mode
<div onClick={startEditing}>Text value</div>

// Edit mode
<input value="Text value" />

When a user clicks on the view mode component, it will disappear and the edit mode will appear.

The second approach (and the one we will be implementing below) is to always use an input element. We can use CSS to make it look as though it has begun editing when a user focuses on it.

// View and edit mode
<input value="Text value" />

By always using an input element, we get behaviours like tabbing and focusing for free. It also makes more explicit what the purpose of the component is.

Create your inline edit component with an input

Let’s get started by creating a React component that uses the HTML input tag:

const InlineEdit = ({ value, setValue }) => {
  const onChange = (event) => setValue(event.target.value);

  return (
    <input
      type="text"
      aria-label="Field name"
      value={value}
      onChange={onChange}
    />
  )
}

The aria-label tells screen reader users the purpose of the input. For instance, if it was the name of a list, you could use "List name".

Then, let's render our new InlineEdit component, and pass in a value and setValue props:

const App = () => {
  const [value, setValue] = useState();

  return <InlineEdit value={value} setValue={setValue} />;
}

In a real-life app, the setValue function would make an endpoint call to store the value in a database somewhere. For this tutorial though, we'll store the value in a useState hook.

Add CSS to make it "click to edit"

We’ll then add some CSS to remove the input styling. This makes it look as though the user needs to click or focus on the input to start editing.

input {
  background-color: transparent;
  border: 0;
  padding: 8px;
}

We’ll also add some styling to show that the component is editable when a user hovers over it:

input:hover {
  background-color: #d3d3d3;
  cursor: pointer;
}

Allow users to save when they press Enter or Escape

If a user clicks away from the input, it will lose focus and return to “view” mode. To keep things keyboard-friendly, we’ll want the escape and enter keys to achieve the same affect.

const InlineEdit = ({ value, setValue }) => {
  const onChange = (event) => setValue(event.target.value);

  const onKeyDown = (event) => { if (event.key === "Enter" || event.key === "Escape") { event.target.blur(); } }
  return (
    <input
      type="text"
      aria-label="Field name"
      value={value}
      onChange={onChange}
      onKeyDown={onKeyDown} />
  )
}

Only save on exit

Currently we call the setValue prop on each key press. In a real-life situation, where setValue was making an endpoint call, it would be making an endpoint call per keypress.

We want to prevent this from happening until a user exits the input.

Let’s create a local state variable called editingValue. This is where we’ll store the value of the input when it is in a “editing” phase.

const InlineEdit = ({ value, setValue }) => {
  const [editingValue, setEditingValue] = useState(value);
  const onChange = (event) => setEditingValue(event.target.value);
  const onKeyDown = (event) => {
    if (event.key === "Enter" || event.key === "Escape") {
      event.target.blur();
    }
  }

  const onBlur = (event) => { setValue(event.target.value) }
  return (
    <input
      type="text"
      aria-label="Field name"
      value={editingValue} onChange={onChange}
      onKeyDown={onKeyDown}
      onBlur={onBlur} />
  )
}

A user exiting the input will call the onBlur handler. So we can use this to call setValue.

Adding validation on empty strings

Finally, you don’t want users to be able to save an empty string or spaces as a value. In that case, we’ll cancel the edit and use the original value.

const onBlur = (event) => {
  if (event.target.value.trim() === "") {
    setValue(value);
  } else {
    setValue(event.target.value)
  }
}

You'll now have a complete single-line inline edit component. Here's the full code:

import { useState } from 'react';

const InlineEdit = ({ value, setValue }) => {
  const [editingValue, setEditingValue] = useState(value);

  const onChange = (event) => setEditingValue(event.target.value);

  const onKeyDown = (event) => {
    if (event.key === "Enter" || event.key === "Escape") {
      event.target.blur();
    }
  }

  const onBlur = (event) => {
    if (event.target.value.trim() === "") {
      setEditingValue(value);
    } else {
      setValue(event.target.value)
    }
  }

  return (
    <input
      type="text"
      aria-label="Field name"
      value={editingValue}
      onChange={onChange}
      onKeyDown={onKeyDown}
      onBlur={onBlur}
    />
  );
};

const App = () => {
  const [value, setValue] = useState();

  return <InlineEdit value={value} setValue={setValue} />;
};

Creating a multiline inline edit

If you want your inline edit component to be multiline, we can use the textarea element instead:

<textarea
  rows={1}
  aria-label="Field name"
  value={editingValue}
  onBlur={onBlur}
  onChange={onChange}
  onKeyDown={onKeyDown}
/>

The one difference with textarea is that you pass in a rows value. This specifies the height of your textarea.

By default, textareas aren't dynamic. Luckily, over on StackOverflow I found a solution to this problem.

If you add the following CSS to your text area:

textarea {
  resize: none;
  overflow: hidden;
  min-height: 14px;
  max-height: 100px;
}

And then pass in an onInput handler, you’ll be able to achieve a “dynamic” look.

import { useEffect } from 'react';

const onInput = (event) => {
  if (event.target.scrollHeight > 33) { 
    event.target.style.height = "5px";
    event.target.style.height = (event.target.scrollHeight - 16) + "px";
  }
}

return (
  <textarea
   rows={1}
   aria-label="Field name"
   value={editingValue}
   onBlur={onBlur}
   onChange={onChange}
   onKeyDown={onKeyDown}
   onInput={onInput} />
)

Note you may need to fiddle around with some of the values in the onInput depending on the height and font size of your text area.

The one other thing you’ll need to add is a focus ring - the blue outline around a focused element. We can do this with some CSS:

textarea:focus {
  outline: 5px auto Highlight; /* Firefox */
  outline: 5px auto -webkit-focus-ring-color; /* Chrome, Safari */
}

And you’re done! Here's the full code for a multiline inline edit:

import { useState, useRef } from 'react';

const MultilineEdit = ({ value, setValue }) => {
  const [editingValue, setEditingValue] = useState(value);

  const onChange = (event) => setEditingValue(event.target.value);

  const onKeyDown = (event) => {
    if (event.key === "Enter" || event.key === "Escape") {
      event.target.blur();
    }
  };

  const onBlur = (event) => {
    if (event.target.value.trim() === "") {
      setEditingValue(value);
    } else {
      setValue(event.target.value);
    }
  };

  const onInput = (target) => {
    if (target.scrollHeight > 33) {
      target.style.height = "5px";
      target.style.height = target.scrollHeight - 16 + "px";
    }
  };

  const textareaRef = useRef();

  useEffect(() => {
    onInput(textareaRef.current);
  }, [onInput, textareaRef]);

  return (
    <textarea
      rows={1}
      aria-label="Field name"
      value={editingValue}
      onBlur={onBlur}
      onChange={onChange}
      onKeyDown={onKeyDown}
      onInput={(event) => onInput(event.target)}
      ref={textareaRef}
    />
  );
};

Ensure your component's functionality with unit tests

Before we finish, let’s write a couple of unit tests to ensure the functionality of our component. We’ll be using React Testing Library:

npm install --save-dev @testing-library/react @testing-library/user-event
# or
yarn add -D @testing-library/react @testing-library/user-event

We can ensure that pressing enter causes the input to lose focus:

import { useState } from 'react';
import { fireEvent, render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import InlineEdit from "./Inline-Edit";

const apples = "apples"
const oranges = "oranges"

const TestComponent = () => {
  const [value, setValue] = useState(apples);
  return <InlineEdit value={value} setValue={setValue} />;
}

describe("Inline Edit component", () => {
  test("should save input and lose focus when user presses enter", () => {
    render(<TestComponent />)
    const input = screen.getByRole("textbox");

    userEvent.type(input, `{selectall}${oranges}{enter}`);
    // RTL doesn't properly trigger component's onBlur()
    fireEvent.blur(input); 

    expect(input).not.toHaveFocus();
    expect(input).toHaveValue(oranges);
  });
});

If you haven’t used React Testing Library before, let’s break this test down:

The render function will render your component into a container. You can access it using the screen variable
We search for the input component via its aria role, "textbox"
We can use the userEvent.type() function to simulate a user typing. If you want to type special keys like space or enter, you can do it with curly braces around it (e.g {space} and {enter})

Similarly, we can write two more unit tests:

test("should focus when tabbed to", () => {
  render(<TestComponent />);
  const input = screen.getByRole("textbox");

  expect(document.body).toHaveFocus();
  userEvent.tab();

  expect(input).toHaveFocus();
});

test("should reset to last-saved value if input is empty", () => {
  render(<TestComponent />);
  const input = screen.getByRole("textbox");

  userEvent.type(input, "{selectall}{space}{enter}");
  fireEvent.blur(input);

  expect(input).toHaveValue(originalName)
});

And finally, we can use a cool library called jest-axe. You can use it to assert that your component doesn’t have any accessibility violations:

import { axe, toHaveNoViolations } from "jest-axe"

expect.extend(toHaveNoViolations)

test("should not have any accessibility violations", async () => {
  const { container } = render(<TestComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

If we had forgotten to include an aria-label, for instance, then this test would have failed.

And that's it! Now you should be able to create inline-editable components for your React app, complete with unit tests.

Generate custom social card images for your Gatsby blog

Emma Goto 🍙 — Fri, 04 Jun 2021 12:23:18 +0000

One of the ways you can make your Gatsby posts stand out to readers is to add a social card image. In this post, you'll learn how to generate these images automatically with gatsby-plugin-react-social-cards.

What is a social card?

A social card is the preview shown when you paste a link into a site like Twitter:

This can give readers more context on your post, and entice them to click the link.

There are a couple of existing Gatsby plugins which let you create social card images from a template. However their customisation options are quite limited. Up until now I've been using a modified version of Maxence Poutord's script, which lets you take a screenshot of a React component.

I decided to turn this script into a proper Gatsby plugin, gatsby-plugin-react-social-cards.

How does gatsby-plugin-react-social-cards work?

Before diving into the set-up, here's a quick summary of how the plugin works.

When you run gatsby develop, the plugin will create new pages for each of your social card images. The page will render your custom React component:

You can pass in all the relevant information from your post's frontmatter (like title and description) into the component as props, and render them however you want.

The plugin then uses Puppeteer to take a screenshot of that component, and save it to your images folder:

Simple!

Get started with gatsby-plugin-react-social-cards

First, install the Gatsby plugin:

npm install gatsby-plugin-react-social-cards
# or
yarn add gatsby-plugin-react-social-cards

As with all Gatsby plugins, you’ll need to declare it in your gatsby-config.js file:

// gatsby-config.js
{
    plugins: [
        {
            resolve: `gatsby-plugin-react-social-cards`,
            options: {
                query: // TODO
                queryToPages: // TODO
                component: require.resolve('./src/components/social-card.js'),
                cardLimit: 0, // for debugging purposes
            },
        },
    ]
}
`

I’ll be walking you through each of the option values below.

Creating your GraphQL query

The first option, query, is the GraphQL query you’ll use to fetch all the pages you want social cards for.

Your Gatsby blog probably fetches a list of pages to render on your site’s home page. You can copy-paste this query to get started.

It should look something like this:

query: `
    {
        allMarkdownRemark {
            nodes {
                fields {
                    slug
                }
                frontmatter {
                    title
                    description
                }
            }
        }
    }
`

The query should contain:

The slug for the page
Any data that you want to use in your social card (such as a page's title or description)

Create your queryToPages function

You will then need to transform the data into a shape that the plugin can use. One of your options will be a queryToPages function. It should look something like this:

// gatsby-config.js
(result) =>
    result.data.allMarkdownRemark.nodes.map(node => {
        const slugWithoutSlashes = node.fields.slug.node.slug.replace(/\//g, '');
        return {
            slug: `/${slugWithoutSlashes}`,
            pageContext: {
                title: node.frontmatter.title,
                description: node.frontmatter.description,
            },
        };
})

As you loop through all the nodes in your query, each object should contain a slug and a pageContext object:

{
    slug: '/my-page-name',
    pageContext: {
        // You can put anything you want in the context!
        title: 'My page title',
        description: 'My page description'
    }
}

The pageContext object will be passed through as a prop to your React component, so make sure you include everything that you want here.

Create your social card React component

Now we can create our React component. I've created the file in my components folder. If you're putting it somewhere else, make sure you change the location in your plugin options.

// src/components/social-card.js
import React from 'react';

const SocialCard = ({ pageContext: { title, description, height, width } }) => {
    return <div>{title}</div>
}

export default SocialCard;

By default, the screenshot taken will be with dimensions 1200px by 628px, which is the recommended image size for Twitter. height and width will be passed in as props, so feel free to use this to set the size of your React component as well.

For now you can keep your component simple - I'll be explaining how to test it below.

Test your social card React component

After completing the above steps, you can start up your Gatsby blog:

gatsby develop

You will be able to view the pages for your social cards at a URL like localhost:8000/<your-post-slug>-social-card.

💡 Can't find the page you're looking for?

Try visiting your Gatsby site's 404 page by making up a broken URL e.g. localhost:8000/blahblah. This will show you a list of all your site's pages. You may be able to spot the social card pages here.

Since this React component is going to be screenshotted at 1200x628, make sure that it renders as you would expect at this height and width. You could add some CSS like border: 1px solid red around your component to double-check.

Once you’re happy with the React component, you’re ready to screenshot!

Changing the cardLimit value

The final option in our plugin settings was the cardLimit value. This is included to let you debug your component without any screenshots being taken. Initially its value was 0, but you can change it to 1 so that it will take one screenshot. This screenshot will be saved in your static folder.

After changing your gatsby-config.js file, your browser will prompt you to restart your server. I recommend instead killing and starting your Gatsby server. I’ve found that when restarting, it will take the screenshot while your site is still loading.

If you're not happy with a screenshot, delete the image from the static folder. The next time you start up your server, the screenshot will be taken again.

When you’re happy with the screenshot, you can delete the cardLimit option altogether. Now it will take screenshots for all your pages.

Add your image to your SEO component

Now that we have our social card images, we can add its URL to your site’s SEO component.

If you want to know more about SEO and meta tags, I have a separate post on all you need to know about meta tags with Gatsby.

I’m assuming that you already have a SEO component set up, so the following code shows the minimum you need to add social card images to your site:

// src/components/seo.js
import React from 'react';
import Helmet from 'react-helmet';

const SEO = ({ slug, isPost }) => {
    const siteUrl = 'https://www.emgoto.com';
    const slugWithoutSlashes = () => slug.replace(/\//g, '');

    const socialCard = isPost
        ? `${siteUrl}/${slugWithoutSlashes()}-social-card.png`
        : `${siteUrl}/square-social-card.png`;

    const twitterCard = isPost ? 'summary_large_image' : 'summary';

    return (
        <Helmet
            meta={[
               {
                    name: 'twitter:card',
                    content: twitterCard,
                },
                {
                    property: 'og:image',
                    content: socialCard,
                },
            }],
        />
    );
}

I'm passing in a isPost prop to my SEO component. Since I only generate social card images for my posts, this lets me fall back to a default image for all other pages on my site.

I use this square image as my fallback:

The twitterCard value tells Twitter whether the image is a small square image (summary) or a large cover image (summary_large_image).

Changing the screenshot size

Different social media sites use different image sizes. If you wanted to use a different set of dimensions, you can pass it in as a plugin option:

// gatsby-config.js
options: {
    dimensions: [{
        width: 1200,
        height: 628,
        suffix: '-social-card'
    }]
}

The suffix value determines the image name e.g. your-slug-social-card.png.

Since dimensions is an array, you can also pass in more than one item, and create multiple images of varying dimensions per post.

Other options

You can further customise the plugin with a couple of other settings:

imageFolder - defaults to 'static'. Change if you want to save your images to another folder
baseUrl - defaults to 'http://localhost:8000'. Change if you start your dev server on another port.
timeout - defaults to 5000. These are the milliseconds waited before the screenshot is taken. Increase this number if you need to wait for images to load, or decrease if you’re finding it to be too slow.

Conclusion

This was my first ever Gatsby plugin, so I would love to hear your feedback if you gave this plugin a go!

Please feel free to leave a comment below, or raise an issue on the gatsby-plugin-react-social-cards repository.

How to build a table of contents in React

Emma Goto 🍙 — Fri, 02 Apr 2021 10:15:26 +0000

A table of contents lets your readers see a high-level summary of your page. In this tutorial, we’ll be building a table of contents with React. This component will dynamically render a list of page headings and highlight which heading you are currently viewing.

Here's our final product:

If you are viewing this post on my website, you will be able to see it in action there as well.

Looking for a full code example? Check out the tutorial’s Codepen.

Get started with a new component file

To begin, let’s create a new TableOfContents file.

// src/components/tableOfContents.js
const TableOfContents = () => {
    return (
        <nav aria-label="Table of contents">
            Hello world!
        </nav>
    );
};

export default TableOfContents;

💡 The nav HTML element indicates parts of the page that provide navigation links, like a table of contents. The aria-label identifies this nav element to screen reader users.

Plop this component into where you want it to render. If you have a main App.js file, you could render it there alongside your main content:

// src/App.js
import TableOfContents from '../components/tableOfContents';

const App = () => (
    <Layout>
        <MainContent />
        <TableOfContents />
    </Layout>
);

export default App;

Add some CSS to make it sticky

There’s a couple of features that we want to add to our table of contents:

Keeping it sticky as the user scrolls down the page
Showing a scrollbar if it’s longer than the height of the page

nav {
  position: sticky;
  position: -webkit-sticky; /* For Safari */
  top: 24px; /* How far down the page you want your ToC to live */

  /* Give table of contents a scrollbar */
  max-height: calc(100vh - 40px);
  overflow: auto;
}

Now, you’ll have a sticky component that will follow you up and down the page as you scroll.

Make sure all your headings have IDs

For your headings to be link-able, they will need to have a unique id value:

<h2 id="initial-header">Initial header</h2>

Create a hook to find all headings on the page

For this table of contents component, I'll be rendering all the <h2> and <h3> elements on the page.

We'll create a useHeadingsData hook, which will be responsible for getting our headings. We'll do this using querySelectorAll:

const useHeadingsData = () => {
  const [nestedHeadings, setNestedHeadings] = useState([]);

  useEffect(() => {
    const headingElements = Array.from(
      document.querySelectorAll("h2, h3")
    );

    const newNestedHeadings = getNestedHeadings(headingElements);
    setNestedHeadings(newNestedHeadings);
  }, []);

  return { nestedHeadings };
};

You'll notice there's a getNestedHeadings function. Since the query selector returns a list of h2 and h3 elements, we have to determine the nesting ourselves.

If our headings looked something like this:

<h2>Initial header</h2>
<h2>Second header</h2>
<h3>Third header</h3>

We would want to nest the "Third header" underneath its parent:

Initial header
Second header
    Third header

To achieve this, we're going to store all h2 objects in a list. Each h2 will have a items array, where any children h3s will go:

[
    {
        id: "initial-header",
        title: "Initial header",
        items: []
    },
    {
        id: "second-header",
        title: "Second header",
        items: [{
            id: "third-header",
            title: "Third header",
        }]
    },
]

In getNestedHeadings, we'll loop through the heading elements and add all h2s to the list. Any h3s will live inside the last known h2.

const getNestedHeadings = (headingElements) => {
  const nestedHeadings = [];

  headingElements.forEach((heading, index) => {
    const { innerText: title, id } = heading;

    if (heading.nodeName === "H2") {
      nestedHeadings.push({ id, title, items: [] });
    } else if (heading.nodeName === "H3" && nestedHeadings.length > 0) {
      nestedHeadings[nestedHeadings.length - 1].items.push({
        id,
        title,
      });
    }
  });

  return nestedHeadings;
};

Render your headings as a list of links

Now that we have our nestedHeadings value, we can use it to render our table of contents!

Let's keep things simple and start by rendering all the h2 elements. We'll create a new Headings component to take care of that.

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a href={`#${heading.id}`}>{heading.title}</a>
      </li>
    ))}
  </ul>
);

const TableOfContents = () => {
  const { nestedHeadings } = useHeadingsData();

  return (
    <nav aria-label="Table of contents">
      <Headings headings={nestedHeadings} />
    </nav>
  );
};

Add your nested headings

We’ll then want to render our nested h3s. We’ll do this by creating a new sub-list underneath each h2:

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a href={`#${heading.id}`}>{heading.title}</a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id}>
                <a href={`#${child.id}`}>{child.title}</a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);

Make your browser smoothly scroll to headings

Right now if we click on a header link, it will immediately jump to the header.

With scrollIntoView, we can instead ensure that it smoothly scrolls into view.

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a
          href={`#${heading.id}`}
          onClick={(e) => {
            e.preventDefault();
            document.querySelector(`#${heading.id}`).scrollIntoView({
              behavior: "smooth"
            });
          }}
        >
          {heading.title}
        </a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id}>
                <a
                  href={`#${child.id}`}
                  onClick={(e) => {
                    e.preventDefault();
                    document.querySelector(`#${child.id}`).scrollIntoView({
                      behavior: "smooth"
                    });
                  }}
                >
                  {child.title}
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);

(Unfortunately this is not supported on Safari!)

Add an offset when you jump to a heading

You might also notice that the heading is very close to the top of the page. We can create a bit of space between the heading and the top of the page when it is jumped to:

h2, h3 {
    scroll-margin-top: 16px;
}

However scroll-margin-top doesn't work on Safari. Alternatively, you can do this:

h2, h3 {
    padding-top: 16px;
    margin-top: -16px;
}

Depending on the size of your offset, anything directly above the header won't be clickable (e.g. links). This won't be a problem if the offset is very small, but can cause problems if you have larger offsets (which you will need if you have a sticky header).

In this case, the "best of both worlds" approach would be to use scroll-margin-top where we can, and fall back to the alternate approach for Safari users.

h2, h3 {
    scroll-margin-top: 16px;
}

/* Safari-only */
@supports (-webkit-hyphens:none) {
    h2, h3 {
        padding-top: 16px;
        margin-top: -16px;
    }
}

Find the currently “active” heading

The final step is to highlight the currently visible heading on the page in the table of contents. This acts as a progress bar of sorts, letting the user know where they are on the page. We’ll determine this with the Intersection Observer API. This API lets you know when elements become visible on the page.

Instantiate your Intersection Observer

Let's create an Intersection Observer. It takes in a callback function as its first argument, which we'll keep empty for now.

You can also pass in a rootMargin value. This determines the zone for when an element is "visible". For instance on my site I have -110px on top and -40% on the bottom:

const useIntersectionObserver = () => {
  useEffect(() => {
    const callback = () => {};

    const observer = new IntersectionObserver(callback, {
      rootMargin: '-110px 0px -40% 0px',
    });
  }, []);
};

The -110px is the height of my sticky nav at the top, so I don't want any content hidden under there to count as "visible".

The -40% means that if a header is in the bottom 40% of the page, this doesn’t count as being "visible". If a heading is visible near the bottom of the page, you're probably not actually reading it yet.

Observe your headings to listen for when they scroll in and out of view

After creating the observer, you need to call observe() on each of the elements we want to observe. In our case, this is all the h2 and h3 elements on the page.

You'll also want to call disconnect() when you unmount.

const useIntersectionObserver = () => {
  useEffect(() => {
    const callback = () => {};

    const observer = new IntersectionObserver(callback, {
      rootMargin: "-110px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));
    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};

Store heading elements from callback function

Next, we’ll need to write the code for our callback function. The observer will call this function each time elements scroll in or out of view.

When you first render the page, it calls the callback with a list of all the elements on the page. As elements scroll in and out of view, it will call the callback with these elements.

Since we want to keep track of the visibility of all the heading elements, we'll store these values in a useRef hook. You can learn more in my post about storing values with useRef.

const useIntersectionObserver = () => {
  const headingElementsRef = useRef({});

  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);
    }

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};

Calculate the index of the active heading

Each heading element in our headings list has a isIntersecting (or “is visible”) value. It’s possible to have more than one visible heading on the page, so we’ll need to create a list of all visible headings.

We’ll also create a getIndexFromId function. This will let us determine the position of a heading given its ID.

const useIntersectionObserver = () => {
  const headingElementsRef = useRef({});
  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);

      const visibleHeadings = [];
      Object.keys(headingElementsRef.current).forEach((key) => {
        const headingElement = headingElementsRef.current[key];
        if (headingElement.isIntersecting) visibleHeadings.push(headingElement);
      });

      const getIndexFromId = (id) =>
        headingElements.findIndex((heading) => heading.id === id);
    }

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};

Finally, we'll choose the visible heading that is closer to the top of the page. We pass in a function called setActiveId that we'll call once we have found the value.

If there are no visible headings, we'll do nothing, and keep the last visible heading as our “active” heading.

const useIntersectionObserver = (setActiveId) => {
  const headingElementsRef = useRef({});
  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);

      const visibleHeadings = [];
      Object.keys(headingElementsRef.current).forEach((key) => {
        const headingElement = headingElementsRef.current[key];
        if (headingElement.isIntersecting) visibleHeadings.push(headingElement);
      });

      const getIndexFromId = (id) =>
        headingElements.findIndex((heading) => heading.id === id);

      if (visibleHeadings.length === 1) {
        setActiveId(visibleHeadings[0].target.id);
      } else if (visibleHeadings.length > 1) {
        const sortedVisibleHeadings = visibleHeadings.sort(
          (a, b) => getIndexFromId(a.target.id) > getIndexFromId(b.target.id)
        );
        setActiveId(sortedVisibleHeadings[0].target.id);
      }
    };

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, [setActiveId]);
};

Highlight the currently active heading

We'll create an activeId state variable to store the currently "active" heading. Then we can pass that information into our Headings component:

const TableOfContents = () => {
  const [activeId, setActiveId] = useState();
  const { nestedHeadings } = useHeadingsData();
  useIntersectionObserver(setActiveId);

  return (
    <nav aria-label="Table of contents">
      <Headings headings={nestedHeadings} activeId={activeId} />
    </nav>
  );
};

And then add an active class to the currently active heading:

const Headings = ({ headings, activeId }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id} className={heading.id === activeId ? "active" : ""}>
        <a
          href={`#${heading.id}`}
          onClick={(e) => {
            e.preventDefault();
            document.querySelector(`#${heading.id}`).scrollIntoView({
              behavior: "smooth"
            });
          }}
        >
          {heading.title}
        </a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id} className={child.id === activeId ? "active" : ""}>
                <a
                  href={`#${child.id}`}
                  onClick={(e) => {
                    e.preventDefault();
                    document.querySelector(`#${child.id}`).scrollIntoView({
                      behavior: "smooth"
                    });
                  }}
                >
                  {child.title}
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);

Finally, you’ll need some CSS to go along with your active class name:

a {
  color: grey;
  text-decoration: none;
}

li.active > a {
  color: white;
}

li > a:hover {
  color: white;
}

Conclusion

And you're done! 🎉 You'll now have a dynamically generated table of contents that will live alongside the contents of your posts.

Looking for the full code? Check out this tutorial’s Codepen.

PS: Creating a table of contents with Gatsby

If you’re using Gatsby, the methods we’re using above won’t work with server-side rendering (SSR). This means for a Gatsby blog your table of contents will be empty when the page first loads, before they render in.

Gatsby lets you grab the table of contents via GraphQL for both Markdown and MDX. This way you can render the table of contents on the initial server-side render.

Gatsby + Markdown

With Markdown, you can add tableOfContents to your page's GraphQL query:

query($slug: String!) {
    markdownRemark(id: { eq: $id }) {
      tableOfContents
    }
}

This will return you an HTML table of contents which you can directly render on the page:

<ul>
  <li><a href="/hello-world/#initial-header">Initial header</a></li>
  <li>
    <p><a href="/hello-world/#second-header">Second header</a></p>
    <ul>
      <li><a href="/hello-world/#third-header">Third header</a></li>
    </ul>
  </li>
</ul>

Gatsby + MDX

Similarly with MDX you can add tableOfContents to your GraphQL query:

query($slug: String!) {
    mdx(slug: { eq: $slug }) {
        tableOfContents
    }
}

This returns a list of top-level headings. Any child headings will live inside of the items array. This data follows a similar structure to nestedHeadings so it should be straightforward to re-use in your code.

[
    {
        url: '#initial-heading',
        title: 'Initial heading', 
        items: [],
    }
];

How to add comments to your Gatsby blog

Emma Goto 🍙 — Wed, 17 Mar 2021 18:03:20 +0000

Does your Gatsby blog have a commenting system set up? If not, you could be missing out! Comments help drive engagement by giving your readers an avenue to ask you questions and add useful information to your blog posts.

Gatsby doesn’t provide comments out of the box, but I’ll be showing you how easy it is to get started with two separate commenting systems - utterances and GraphComment.

Add comments to your Gatsby blog with utterances

How does utterances work?

utterances is a commenting system built on top of Github. Users will have to authenticate with their Github account before they can leave a comment on your site:

This will create a new issue in a Github repo of your choice, and the comment will appear there.

If another comment is left on the same page, a comment will be added to that same Github issue.

This integration with Github makes utterances a good choice if you're running a blog that is mainly read by other developers (since they will most likely have Github accounts).

Setting up utterances

You can follow the set-up steps from the utterances documentation. Namely:

Make a new public repository on Github for your comments.
Go to the utterances Github app, and install it on that repository.

Add a comments component to your Gatsby blog

You’ll be given a script to add to your site that looks like this:

<script src="https://utteranc.es/client.js"
     repo="[emgoto/emgoto-comments]"
     issue-term="pathname"
     theme="github-light"
     crossorigin="anonymous"
     async>
</script>

Since we’re using React, we won’t be able to just plop this script in. Instead, make a React component called Comments:

// src/components/comments.js
import React, { useEffect } from 'react';

const COMMENTS_ID = 'comments-container';

const Comments = () => {
    useEffect(() => {
        const script = document.createElement('script');
        script.src = 'https://utteranc.es/client.js';
        script.setAttribute('repo', 'emgoto/emgoto-comments');
        script.setAttribute('issue-term', 'pathname');
        script.setAttribute('theme', 'dark-blue');
        script.setAttribute('crossorigin', 'anonymous');
        script.async = true;

        const comments = document.getElementById(COMMENTS_ID);
        if (comments) comments.appendChild(script);

        // This function will get called when the component unmounts
        // To make sure we don't end up with multiple instances of the comments component
        return () => {
            const comments = document.getElementById(COMMENTS_ID);
            if (comments) comments.innerHTML = '';
        };
    }, []);

    return (
        <div id={COMMENTS_ID} />
    );
};

export default Comments;

You can just copy-paste the code above, but make sure to change the repo line to your own comments repository.

After that, you can drop your new component into wherever you render your blog posts. I have a template file that is rendered on each blog post page, so I put mine at the bottom of that file:

// src/templates/blog-post.js
const BlogPost = () => (
    <>
        // Code to render blog post content
        <Comments />
    </>
);

And you're done! 🎉 If you're reading this post on my website, you can scroll down to the bottom to view this component in action.

Theming and styling utterances

utterances provides 7 different colour schemes, including both dark mode and light mode options. You can try out all the options for yourself on the documentation page.

Since utterances renders in a iframe, you can’t add your own CSS to modify the colour schemes. So you’ll have to choose one of the available options. If you really want to stick to your blog’s colour scheme, you could also try raising a PR to add a new theme.

The iframe will be wrapped a div with the .utterances class name, so it is possible to make some positioning modifications there. utterances has some built-in margins and padding on their comments component, so if you wanted to remove that, you can do something like this:

.utterances {
    margin: -16px 0;
    padding: 0 -4px;
}

Add comments to Gatsby with GraphComment

GraphComment works similarly to other comment systems like Disqus. They host the comments for you, and allow users to create an account with a username and avatar on their platform. They provide a free tier for up to 1 million data loads a month.

Anonymous users also have the ability to leave comments. In your GraphComment settings, you can choose whether these anonymous comments are immediately published, or to hold off until you approve them first.

Setting up GraphComment

After signing up for a GraphComment account, you'll need to add your site on the admin page.

GraphComment will then give you a script like this:

<div id="graphcomment"></div>
<script type="text/javascript">
  window.gc_params = {
    graphcomment_id: 'emgoto',
    fixed_header_height: 0,
  };

  (function() {
    var gc = document.createElement('script'); gc.type = 'text/javascript'; gc.async = true;
    gc.src = 'https://graphcomment.com/js/integration.js?' + Date.now());
    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(gc);
  })();
</script>

Since we’re using React, we’ll need to convert this into a React component:

import React, { useEffect } from 'react';

const COMMENTS_ID = 'graphcomment';

const Comments = () => {
    useEffect(() => {
        window.gc_params = {
            graphcomment_id: 'emgoto',
            fixed_header_height: 0,
          };

        const script = document.createElement('script');
        script.src = 'https://graphcomment.com/js/integration.js?' + Date.now();
        script.async = true;

        const comments = document.getElementById(COMMENTS_ID);
        if (comments) comments.appendChild(script);

        // This function will get called when the component unmounts
        // To make sure we don't end up with multiple instances of the comments component
        return () => {
            const comments = document.getElementById(COMMENTS_ID);
            if (comments) comments.innerHTML = '';
        };
    }, []);

    return <div id={COMMENTS_ID} />
};

export default Comments;

Make sure to change graphcomment_id to the ID you used when you added your site.

Then you can drop in this new <Comments /> component wherever you want to render it.

Theming and styling GraphComment

In my opinion the UI for GraphComment isn’t as nice as utterances (which re-uses Github UI) but considering it’s a free service, I can’t complain too much!

GraphComment is smart enough to detect whether your site is in light mode or dark mode and render accordingly. You can also choose a theme colour:

All this really does is choose the accent colour that renders on the page (in the below screenshot, it's blue).

Beyond this, there are no customisation options available.

Add a unit test for your comments component

After you've set up utterances or GraphComment, make sure to add a unit test to make sure that the script is rendering on the page:

//src/components/comments.test.js
import React from 'react';
import { render } from '@testing-library/react';

import Comments from './index';

describe('Comments component', () => {
    test('should render comments script', () => {
        const { container } = render(<Comments />);
        const script = container.querySelector(
            // choose one of the following lines below
            // 'script[src="https://utteranc.es/client.js"]',
            // 'script[src^="https://graphcomment.com/js/integration.js"]',
        );
        expect(script).toBeTruthy();
    });
});

Utterances vs Disqus (and other competitors)

Disqus is the most well-known commenting system and is used across many sites. However it has had some controversies in the past with affiliate links and injecting advertising code. For that reason, I decided to give Disqus a miss and see what other solutions were out there.

utterances lets readers leave comments using a Github account, so it’s a great solution if you run a developer-targeted blog. For other types of blogs, GraphComment is the only option I found that provides a free tier (excluding Disqus).

If you don’t mind paying, it may be worth taking a look at other options like Commento or FastComments. Unfortunately there doesn't seem to be anything on the market that lets you heavily customise the design to suit your needs. The closest may be Hyvor which does provide a wide variety of appearance settings. Their system starts at $5 a month for 100k monthly pageviews.

Conclusion

Setting up comments on your Gatsby blog is a hassle-free experience with both utterances and GraphComment. utterances is a great option for developer blogs, while GraphComment does provide more features (like auto-moderation and keyword filtering) however this does come at the cost of a slightly less slick UI.

The biggest downside with both options is that you are limited to the provided colour schemes and design, and so the comments component may look slightly “off” compared to the rest of your site.

Jest partial matching on objects, arrays and functions

Emma Goto 🍙 — Thu, 11 Mar 2021 19:41:42 +0000

Sometimes with Jest, you only need to test part of an object exists, or test on a subset of an array. We can do this using Jest’s partial matchers.

In this post I will cover:

Using Jest’s objectContaining to match on certain key/value pairs in objects
Using Jest’s arrayContaining to match on certain values in arrays
How to use partial matching with Jest’s toHaveBeenCalledWith

Object partial matching with Jest’s objectContaining

When you want to test the subset of an object, or a specific key/value pair, you can use the objectContaining matcher.

test('should contain important value in object', () => {
    const object = {
        important: 'important',
        ignore: 'ignore',
    };

    expect(object).toEqual(expect.objectContaining({
        important: 'important'
    }));
d});

This test will pass as long as the object contains important: 'important'.

Nested object partial matching

If you are looking for a value in a nested object, you can also nest objectContaining.

test('should contain important value in nested object', () => {
    const nestedObject = {
        ignore: 'ignore',
        payload: {
           important: 'important',
           ignore: 'ignore',
        },
    };

    expect(nestedObject).toEqual(
        expect.objectContaining({
            payload: expect.objectContaining({
                important: 'important',
            }),
        })
    );
});

Array partial matching with Jest’s arrayContaining

As well as objects, you might only care about certain values in an array. In this case, you can use arrayContaining for partial matching on arrays.

test('should contain important value in array', () => {
    const array = [
        'ignore', 
        'important'
    ];

    expect(array).toEqual(expect.arrayContaining(['important']))
});

This test will pass as long as the array contains the string 'important'.

Match an array in any order (unordered array)

The arrayContaining matcher will also work regardless of the order of your array.

test('should contain important values in array, in any order', () => {
    const array = [
        'ignore', 
        'important',
        'alsoImportant',
        'veryImportant',
        'veryVeryImportant',
    ];

    expect(array).toEqual(expect.arrayContaining(
        ['veryVeryImportant', 'veryImportant', 'alsoImportant', 'important']
    ));
});

If you wanted to make sure that the array contained values in any order, but didn’t contain any other values, you could assert that the length of the array is as expected.

test('should contain only the important values in array, in any order', () => {
    const array = [
        'important',
        'alsoImportant',
        'veryImportant',
    ];

    expect(array).toEqual(expect.arrayContaining(
        ['veryImportant', 'alsoImportant', 'important']
    ));
    expect(array).toHaveLength(3);
});

Partial matching objects in an array

With an array of objects, we can use a combination of Jest’s arrayContaining and objectContaining. This will let you assert on a specific object in an array (and even a specific value inside of that object).

test('should contain important objects in array', () => {
    const array = [
        { 
            important: 'important',
            ignore: 'ignore'
        },
        {
            ignore: 'ignore',
        }
    ];

    expect(array).toEqual(expect.arrayContaining(
        [expect.objectContaining({ important: 'important' })]
    ));
});

Matching on arguments in function calls with Jest’s toHaveBeenCalledWith

We use toHaveBeenCalledWith when we want to assert that a function was called with a specific set of arguments. If you only care about a specific argument in a function call, you can replace the other arguments with expect.anything().

test('should have been called with specific argument', () => {
    const mockFunction = jest.fn();

    mockFunction('ignore', 'ignore', 'important');

    expect(mockFunction).toHaveBeenCalledWith(
        expect.anything(), expect.anything(), 'important'
    );
});

If you want to be a bit more specific, you can also use expect.any() if you want to specify the type of the other arguments, such as a String or Object.

mockFunction({ignore: 'ignore'}, 'ignore', 'important');

expect(mockFunction).toHaveBeenCalledWith(
    expect.any(Object), expect.any(String), 'important'
);

Unit testing Node.js fs with mock-fs

Emma Goto 🍙 — Wed, 03 Mar 2021 19:55:42 +0000

If you're using the fs module to do things like write to files, or modify file names, you might have wondered - how do I unit test this?

In this post I'll be showing you how you can use mock-fs to easily unit test your Node.js scripts.

If you want to learn more about Node.js, check out my posts on automating file renaming with Node.js and writing to files with Node.js.

Set up your Node.js script to be tested

To begin with, we'll be using an example Node.js script that uses fs to replace the string "Hello" with "Goodbye".

This example is fully synchronous, and only uses fs readFileSync and writeFileSync:

const { readFileSync, writeFileSync } = require('fs');

const modifyFile = () => {
    const file = `${process.cwd()}/folderName/index.md`

    const content = readFileSync(file, 'utf8'); // highlight-line
    const newContent = content.replace('Hello', 'Goodbye');

    writeFileSync(file, newContent); // highlight-line
};

If your script is fully synchronous, you'll have no problems and you can keep scrolling down to the mock-fs part below.

However if you're using async functions like fs readFile or writeFile, you'll need to make sure that your script has finished before beginning the unit tests.

We can do this using the fs Promises API.

Using the fs Promises API

Instead of using readFile, use promises.readFile, and you'll be returning a Promise:

const { promises } = require('fs');

const modifyFile = async () => {
    const file = `${process.cwd()}/folderName/index.md`

    return promises.readFile(file, 'utf8').then(content => {  // highlight-line
        const newContent = content.replace('Hello', 'Goodbye')
        return promises.writeFile(file, newContent);  // highlight-line
    });
};

This means that in your unit test, you can now use await and make sure your script has completed before testing it:

test('should replace Hello with Goodbye', async () => {
    await modifyFile();
    // ...

Before we make any assertions though, we’ll also need to add some mocks.

Mock your files and folders using mock-fs

We want to be able to mock out some files, because otherwise you would need to have dummy test files that live in your test folder, and you would also need to reset them to their original state at the end of each unit test.

With mock-fs, we can mock out folder structures and the content of files.

Make sure you have it installed first:

npm i mock-fs -D 
# or
yarn add mock-fs -D

Then, add it to the beforeAll hook in your test:

import mock from 'mock-fs';
import { main } from './modifyFile';

describe('modifyFile script', () => {
    beforeAll(() => {
        mock({
            'folderName': {
                'index.md': '# Hello world!',
            },
        });
    });

    afterAll(() => {
        mock.restore();
    });

These folder names are relative to the root of your repository. Here we’re mocking a folder/file structure like this:

folderName
    index.md // <- contains "# Hello world!"

Write a unit test on file modification with mock-fs

Now we can continue with our unit test. We can assert on the file's contents:

test('should replace hello with goodbye', async () => {
    const file = `${process.cwd()}/folderName/index.md`
    const expectedResult = `# Goodbye world`;

    await modifyFile();

    const result = readFileSync(file, 'utf8');
    expect(result).toEqual(expectedResult);
});

When we call modifyFile, we'll be modifying the mocked file. We can then confirm that the file was successfully modified by using readFileSync to read it.

Write a unit test on file renaming with mock-fs

In the case where we want to unit test that files were renamed, we can do the following:

import glob from 'glob';

test('should successfully move and rename files', async () => {
    const expectedFiles = [
        `${process.cwd()}/folderName/renamedFile.md`,
    ];

    await modifyFile();

    const files = glob.sync(`${process.cwd()}/folderName/*.md`);

    expect(files).toEqual(expectedFiles);
});

Since we have used mock-fs, your script can also rename mocked files. Then we can use glob to verify that our files were renamed as expected.

MonarchMap: Help save the Monarch butterfly with New Relic 🦋

Emma Goto 🍙 — Wed, 24 Feb 2021 11:33:08 +0000

Each year, Monarch butterflies make a 3000-mile migration across North America. But climate change is impacting their migration patterns and their breeding grounds.

As a result, these beautiful insects are now threatened with extinction.

Gathering data on the location and migration patterns of these butterflies is an important step towards keeping them from going extinct. For the New Relic hackathon, I've built a tool to track these butterflies.

Report a butterfly sighting with MonarchMap

MonarchMap lets you report Monarch butterfly sightings by filling out a form:

You can then view these sightings, day-by-day, on a map to track their migration over time:

MonarchMap is built using a number of technologies:

Blitz.js
Tailwind CSS
MapBox
New Relic

You can check out the full code on my Github

How does MonarchMap use New Relic?

New Relic is a platform that lets you monitor and analyse the performance of your site. I made use of four separate features/APIs that New Relic provides when creating this app.

New Relic Browser monitoring agent

By copy-pasting a JavaScript snippet into my app, I can view a New Relic dashboard that shows the app’s performance, such as page load times:

New Relic Alerts

New Relic also lets you set up alerting rules. In my case, I set up a rule for site performance. In the case where page load times become slow, I will receive an alert to my email:

Out of this world!

I’m entering MonarchMap under the hackathon’s “Out of this world” category. So when I was coming up with my idea, I tried to think - how could I use New Relic in an innovative way?

The solution I settled on was to use New Relic as my app’s database.

This isn’t technically what you’re supposed to use New Relic for, but I figured, if I could do it, why not?

New Relic Event API

New Relic has an Event API you can use to send custom events. When a user reports a butterfly sighting, this is registered as an event in New Relic. You can then make dashboards to view this data in New Relic:

New Relic NerdGraph

New Relic has a GraphQL API called NerdGraph. You can use their handy API explorer to craft your GraphQL query:

I made use of it to grab a list of all of my custom events. This is what powers the sightings map! This means that my app is fully functional without its own database - all thanks to New Relic.

I enjoy participating in DEV hackathons, and this one was no exception! I got to spend a bit of time exploring some cool tech, and I actually learned a lot about the Monarch butterfly in the process as well.

The official submission for this hackathon is viewable over at therelicans.com.

How to write to files with Node.js

Emma Goto 🍙 — Sat, 23 Jan 2021 20:32:46 +0000

In this post we’ll be covering how you can use the fs module in Node.js to write to and modify files with writeFile() and writeFileSync(). We’ll also take a look at an alternative library we can use called replace-in-file.

This post assumes you have a general knowledge of JavaScript syntax, but doesn’t expect any Node.js-specific knowledge.

If you want to learn how to write and run a Node.js script, I have covered that in my previous post on automating file renaming with Node.js.

Overwrite a file with Node.js

Using fs writeFile to write to files (asynchronous)

Let's jump straight into things with an fs writeFile() example:

const { writeFile } = require('fs');

const content = 'Hello world';
const file = '/Users/emma/src/emgoto.com/file.txt';

const callback = (err) => { /** Handle errors */ };

writeFile(file, content, callback);

This will change the contents of the file to contain the string “Hello world”.

The callback function will be executed once the file has been successfully written to, or it errors out.

Using fs writeFileSync to write to files (synchronous)

If you want an synchronous version, you can use writeFileSync:

const { writeFileSync } = require('fs');

const content = 'Hello world';
const file = '/Users/emma/src/emgoto.com/file.txt';

writeFileSync(file, content);

Read from a file, then modify part of it with Node.js

Using fs readFileSync to read from a file (synchronous)

If you want to modify a file, rather than write over its contents, you'll first need to read it. We can use readFileSync here:

const { readFileSync } = require('fs');

const content = readFileSync(file, 'utf8');
const newContent = content.replace('Hello', 'Goodbye');

writeFile(file, newContent, () => {});

After we read the file, we will have a copy of the file's contents. We can then use JavaScript's replace function to modify it, before updating the file with the new contents.

Using fs readFile to read from a file (asynchronous)

The asynchronous version of readFileSync is readFile:

const { readFile, writeFile } = require('fs');

const callback = (err, data) => {
    const newContent = data.replace('Hello', 'Goodbye');
    writeFile(file, newContent);
}

readFile(file, 'utf8', callback);

Here, when we successfully get the contents of the file (or it errors out), the callback function will be called. Then we can use writeFile to modify the contents of the file.

How to effectively use JavaScript’s replace function

In the above example, you’ll notice we were passing strings into JavaScript’s replace function:

content.replace('Hello', 'Goodbye');

This only replaces the first instance of "Hello" with "Goodbye". If you want to replace more than one instance, you’ll can make use of Regex:

content.replace(/Hello/g, 'Goodbye');

If you're rusty on your Regex (or haven’t used it before):

Regex patterns live inside of //
The g on the end signifies that it is “global”, which means it will find all occurrences.
/Hello/g will find all instances of the string “Hello”

Regex can do many more cool things, but I won’t be diving into that in this post! When writing your Regex patterns, I recommend testing it with a tool like RegExr.

As well as strings and Regex, we can also pass in functions!

const addSpacesBetweenLetters = (string) => 
    string.split('').join(' ');

content.replace(/Hello/g, addSpacesBetweenLetters);

This would convert all instances of “Hello” to “H e l l o”.

Using replace-in-file to write to files

Instead of fs readFile and writeFile, there’s also a handy library we can use called replace-in-file.

To replace all instances of "Hello" with "Goodbye", you would do the following:

const replace = require('replace-in-file');

const options = {
    files: fileName,
    from: /Hello/g,
    to: 'Goodbye',
};

replace(options);

You'll notice that we no longer have to open the file and get its contents - replace-in-file will handle that for you.

The from and to variables accept strings, Regex patterns and functions.

fs writeFile vs replace-in-file

For simple use cases, fs writeFile will get the job done. There are a couple of extra features that the replace-in-file library has which make it pretty useful.

It can replace content in multiple files at once:

const replace = require('replace-in-file');

const options = {
    files: [fileName, anotherFileName],
    from: /Hello/g,
    to: 'Goodbye',
};

replace(options);

It can also replace things in bulk:

const options = {
    files: [fileName, anotherFileName],
    from: [/Hello/g, /Foo/g],
    to: ['Goodbye', 'Bar'],
}

When you're using arrays with to and from:

The from in the 0th position will convert to the to in the 0th position
The from in the 1st position will convert to the to in the 1st position

And so on!