Forem: Joshua Pohl

Site Search Powered by JSON Feed

Joshua Pohl — Sun, 05 Mar 2023 19:29:40 +0000

Inspired by Craig Mods's gist for client-side site search, I ported his work over to a React component I could use with this Next.js powered site. At the time of posting, every page of lightpohl.me is generated at build time — sites like these fall into the category called 'static site generation.' At build time, I grab all posts and photos from a CMS, tell Next.js which pages it needs to build, and generate an RSS feed. When a post is created or is updated, I generate a new build via a webhook and the process starts over again. Without a live API, where would I get the data to power the site search? RSS! Well, sort of.

I use jpmonette/feed to generate my existing rss.xml, but it also supports the JSON Feed specification as an output type. By tweaking the config, I was able to expose an rss.json as well. A simplified version of output looks like the following:

{
    "version": "https://jsonfeed.org/version/1",
    "title": "Joshua Pohl",
    "home_page_url": "https://lightpohl.me",
    "feed_url": "https://lightpohl.me/rss.json",
    "description": "Writing about programming, the Internet, and travel.",
    "author": {
        "name": "Joshua Pohl",
        "url": "https://lightpohl.me"
    },
    "items": [
        {
            "id": "https://lightpohl.me/i/waikiki-morning-sailboat",
            "url": "https://lightpohl.me/i/waikiki-morning-sailboat",
            "title": "Waikiki Morning Sailboat",
            "summary": "A small sailboat near Waikiki.",
            "date_modified": "2023-02-21T18:00:00.000Z"
        }
    ]
}

The list of items works perfectly with Fuse.js. Add a fetch() call, a couple pieces of state, a few keyboard listeners, and you have a super fast client-side search. Try it out on desktop either by clicking the search button in the top right corner or by pressing CTRL + /.

It was reminder that feeds need not only be an API for external users, but are powerful tools for sites and web apps themselves. RSS and friends are still cool.

Refresh Your React App Discretely

Joshua Pohl — Sat, 14 May 2022 18:08:19 +0000

One of the hurdles introduced by single-page apps is that users can go much longer without being updated to the latest deployed code. This affects not only custom React setups but even more opinionated options like Next.js. In a perfect world, APIs should be backwards compatible and fail gracefully when something is missed, but there's no doubt in my mind that a user with a client bundle that is several days old will be more likely to run into issues. Fortunately, there's an easy way we can update our client app with the user being none the wiser. We'll build our example with React and React Router, but the concepts apply to all client JavaScript frameworks.

Links And Anchors

The main reason users can have much longer running sessions without receiving new JavaScript is because of the nature of single-page applications. Single-page applications often utilize client-side routing, which means the full page will not be refreshed: the app will instead fetch data it needs for the next page and manipulate the browser history manually without requesting the full HTML. We could just not use client-side routing, but we will lose a lot of that speediness we associate with these feature-rich web applications. What if we could fall back to native anchors only when necessary?

function SuperLink({ href, ...other }) {
  const { shouldUseAnchor } = useSomeFunction();

  if (shouldUseAnchor) {
    return <a href={href} {...other} />;
  }

  // a React Router <Link />
  return <Link to={href} {...other} />;
}

This code looks promising. But how can we calculate shouldUseAnchor to determine which type of link to render?

git.txt

One simple option is to expose a text file with a Git hash that is generated from our source code. Wherever we expose our fonts and possible images (e.g. /static), we can place git.txt at build-time.

{
  "git:generate-hash": "git ls-files -s src/ | git hash-object --stdin > static/git.txt"
}

As part of our build command, we'll also call && npm run git:generate-hash and place it into our publicly accessible directory. All we need to do now is poll for this file on a fixed interval to check for new updates and update our SuperLinkcomponent.

GitHashProvider

Any page could have a number of links on it — it would be mistake to have each instance poll for our hash file. Instead, we'll wrap our app in a React context provider so all our instances of our SuperLinkcan use it.

import * as React from 'react';

// Some boilerplate to prepare our Context
const GitHashContext = React.createContext({
  hash: '',
  hasUpdated: false
});

// Setup our hook that we'll use in `SuperLink`
export const useGitHash = () => React.useContext(GitHashContext);

// Function used to actually fetch the Git hash
const TEN_MINUTES_IN_MS = 60000 * 10;
async function fetchGitHash() {
  let gitHash = '';

  try {
    const result = await fetch('/static/git.txt');
    gitHash = await result.text();
  } catch (error) {
    console.error(error);
  }

  return gitHash;
}

// The provider we'll wrap around our app and fetch the Git hash
// on an interval
export const GitHashProvider = ({ children }) => {
  const [state, setState] = React.useState({ hasUpdated: false, hash: '' });

  const updateGitVersion = React.useCallback(async () => {
    const hash = await fetchGitHash();

    if (hash) {
      setState((prevState) => ({
        hash,
        hasUpdated: !!prevState.hash && prevState.hash !== hash
      }));
    }
  }, []);

  React.useEffect(() => {
    const interval = setInterval(() => {
      updateGitVersion();
    }, TEN_MINUTES_IN_MS);

    return () => clearInterval(interval);
  }, [updateGitVersion]);

  return (
    <GitHashContext.Provider value={state}>{children}<GitHashContext.Provider>
  );
};

That's quite a bit of code, so let's walk through it. We define the boilerplate for context and the hook that will provide access to its data (GitHashContext and useGitHash). Next, we define a simple wrapper around fetch that will query our git.txt and pull out the hash.

The meat of the logic is in GitHashProvider and it's not too bad. We define our state and kick off an interval that will run every ten minutes and grab the latest Git hash. If we have already saved a Git hash before and it's different than the latest, we'll set hasUpdated to true. We keep track of the previous hash for later comparisons. We're now ready to use it in SuperLink!

function SuperLink({ href, ...other }) {
  const { hasUpdated: hasGitHashUpdated } = useGitHash();

  if (hasGitHashUpdated) {
    return <a href={href} {...other} />;
  }

  // a React Router <Link />
  return <Link to={href} {...other} />;
}

When to Use It

Depending on the application, the locations where you'd want to use our new SuperLinkcould change. Personally, I feel that links in your header are almost always good candidates. Let's imagine the flow as the end-user, we've left a tab open overnight and return to SomeCoolWebApp.xyz. Unknown to us, the devs have deployed a really important bugfix in code that we'll now receive if we click on any of these "smart" links. The user might notice a quick flash as the full page loads on navigation, but this should happen infrequently enough to not really be noticeable.

Persist Formik State on Refresh with React Hooks

Joshua Pohl — Tue, 23 Feb 2021 23:33:08 +0000

Hey there! If you're just looking for the full code example, jump down to Putting It All Together.

Out of all the different React form libraries I've used in different projects, Formik is currently my favorite. It's intuitive and provides lower-level API access to workaround situations a high-level only API might not anticipate.

If you're building a large form, or one that will be filled out slowly over some time, persisting its state across sessions is really important. It's especially important if you anticipate much usage on mobile where apps are often removed from memory unexpectedly when users are multitasking.

Fortunately, Formik makes adding that behavior simple, and that behavior can also be consolidated into one reusable component that you can drop into any Formik form provider.

Saving to Local Storage

Let's start by saving the form state into local storage when the form is updated. We're going to use a two libraries here (react-fast-compare and use-debounce) to simplify the example code, but feel free to roll your own code or use an equivalent library as a replacement.

import {useEffect, useRef} from 'react';
import {useFormikContext} from 'formik';
import isEqual from 'react-fast-compare';
import {useDebouncedCallback} from 'use-debounce';

const FormikPersist = ({name}) => {
  const {values} = useFormikContext();
  const prefValuesRef = useRef();

  const onSave = (values) => {
    window.localStorage.setItem(name, JSON.stringify(values));
  };

  const debouncedOnSave = useDebouncedCallback(onSave, 300);

  useEffect(() => {
    if (!isEqual(prefValuesRef.current, values)) {
      debouncedOnSave.callback(values);
    }
  });

  useEffect(() => {
    prefValuesRef.current = values;
  });

  return null;
};

export default FormikPersist;

Our FormikPersist component takes one prop: a name to be the unique identifier we will use to store the form in window.localStorage. Since our component will live underneath a Formik provider, we can use useFormikContext to access the current values of the form. On each render of our component, we compare the previous list of values with the current values and save the latest values to local storage if they differ. We use a debounced version of our onSave function to write to local storage so as to not write too many times in quick succession.

The hardest part is over—the rest is even easier.

Rehydrating on Refresh

Now we just need to check our local storage on component mount and initialize the form values if we find them.

...

  // We're now grabbing 'setValues' as well
  const {values, setValues} = useFormikContext();

  ...

  useEffect(() => {
    const savedForm = window.localStorage.getItem(name);

    if (savedForm) {
      const parsedForm = JSON.parse(savedForm);

      prefValuesRef.current = parsedForm;
      setValues(parsedForm);
    }
  }, [name, setValues]);

...

Tip: one alteration you might want to make to this component is to only rehydrate form values that were saved within a certain time span (e.g. the last day or the last week). To do that we would save a timestamp with the form values and compare that timestamp with the current time in this useEffect.

Putting It All Together

We now have our complete FormikPersist component that we can place under a Formik provider to handle persisting our form state on refresh.

import {useEffect, useRef} from 'react';
import {useFormikContext} from 'formik';
import isEqual from 'react-fast-compare';
import {useDebouncedCallback} from 'use-debounce';

const FormikPersist = ({name}) => {
  const {values, setValues} = useFormikContext();
  const prefValuesRef = useRef();

  const onSave = (values) => {
    window.localStorage.setItem(name, JSON.stringify(values));
  };

  const debouncedOnSave = useDebouncedCallback(onSave, 300);

  useEffect(() => {
    const savedForm = window.localStorage.getItem(name);

    if (savedForm) {
      const parsedForm = JSON.parse(savedForm);

      prefValuesRef.current = parsedForm;
      setValues(parsedForm);
    }
  }, [name, setValues]);

  useEffect(() => {
    if (!isEqual(prefValuesRef.current, values)) {
      debouncedOnSave.callback(values);
    }
  });

  useEffect(() => {
    prefValuesRef.current = values;
  });

  return null;
};

export default FormikPersist;

// inside some render function
<Formik {...props}>
  <Form {...props}>
    <FormikPersist name="our-form" />
  </Form>
</Formik>

And that's it! Add this to your form and you'll make mobile visitors of your website much happier if their browser tab is thrown to the wind. I'm looking at you, iOS 13