Stories by Alex Gurr on Medium

Turning a React app into an installable PWA with offline detection, service workers and theming.

Alex Gurr — Wed, 20 Oct 2021 09:11:23 GMT

Recently I decided to take the dive into making my web app progressive. Some of the benefits are excellent caching, sped up page load times and the ability for a user to install it “natively”.

There are definitely some gotchas and other interesting tidbits which I’ll also be covering below.

I’m using React, so I’ll assume you are too. If you want to jump in to the code, it’s all in the mixmello GitHub repo.

Let’s get started!

Setting Up Service Workers

Create-react-app provides us a couple of excellent service worker files to help us get started. They automatically configure lots of useful things like caching your webpack output. They’ll pretty much contain everything we need for our PWA.

You can get these files by running npx create-react-app my-app --template cra-template-pwa.

This will give you two files you can move into your project, serviceWorkerRegistration.js and service-worker.js. Add these into /src of your project (or use the new project provided by the command). I'm not going to deep dive into these files today as they are extremely well documented via comments.

Now we actually need to register our service worker on launch. In your app index file, import the service worker.

import { register as registerServiceWorker } from './serviceWorkerRegistration';

Now simply run the function with registerServiceWorker();.

A finished index file should look something like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { register as registerServiceWorker } from './serviceWorkerRegistration';
import App from './App';

ReactDOM.render(
  
    
  ,
  document.getElementById('root')
);

registerServiceWorker();

Service workers will only register/run in a production build, unless specifically enabled (see create-react-app documentation in the extras section below). This is because hot-reloading and service worker caching don’t mix very well! This means you won’t see the service worker running in Dev tools > Application > Service Workers.

Offline Detection & UI/UX

Offline detection is not specifically a service worker/PWA feature, however, PWAs are ‘offline first’, meaning it’s a good idea to have code to handle offline/online state.

In my application, I decided to add a little bubble that comes down from the top of the screen and block the page. See what it looks like below (might take a few seconds to load):

To make a good user & developer experience for this feature -

It should be a higher order component we can wrap round our whole app, for single responsibility and no code duplication
It should prevent the user from scrolling when open
It should be able to detect when the app is online/offline in real time
It should be clear what’s happening

The Component

Let’s make a new folder, Offline. Where you put it is up to you. In my app, it's in src/common/components. I'm using SCSS, but you can continue to use whatever framework your app is using.

Create 3 new files, index.js, Offline.js and _offline.scss.

index.js provides the default export for our component:

export { default } from './Offline';

Offline.js is our main component. The component is comprised of two main bits of functionality. 1) The window event handlers to handle network state changes and 2) the actual JSX/HTML itself. Here I'm using React 17 and hooks but you could retrofit this to a class component if needed.

Let’s start building!

export default function Offline({ children }) {
  return (
    <>
      
      {children}
    
  );
}

We’ve instantiated a new component and rendered it inside a fragment, because we don’t want to add an additional layer/container above our app’s children.

import cx from 'classnames';
import './_offline.scss';

export default function Offline({ children }) {
  return (
    <>
      
      
      {children}
    
  );
}

Now we have our styles import and an overlay div that will fade out the background. I’m using a library called classnames to chain classes but you don't have to use it. Later on, we'll conditionally change the overlay styles bases on our online/offline state.

import cx from 'classnames';
import { ReactComponent as OfflineLogo } from 'assets/images/logo-offline-icon.svg';
import Text from '../Text';
import './_offline.scss';

export default function Offline({ children }) {
  return (
    <>
      
                
                    
                    
                        You're not online
                        Check your internet connection.
                    

                

      
      {children}
    
  );
}

Now we’re adding some content to our little offline bubble. Text is a component wrapper for text elements like

. I've created a dedicated SVG logo for offline, but you can use whatever you like in it's place. The mt-x helper classes are for margin which I cover in my other article here.

import cx from 'classnames';
import { useEffect } from 'react';
import { useBooleanState, usePrevious } from 'webrix/hooks';
import { ReactComponent as OfflineLogo } from 'assets/images/logo-offline-icon.svg';
import Text from '../Text';
import './_offline.scss';

export default function Offline({ children }) {
  const { value: online, setFalse: setOffline, setTrue: setOnline } = useBooleanState(navigator.onLine);
    const previousOnline = usePrevious(online);

    useEffect(() => {
        window.addEventListener('online', setOnline);
        window.addEventListener('offline', setOffline);

        return () => {
            window.removeEventListener('online', setOnline);
            window.removeEventListener('offline', setOffline);
        };
    }, []);

  return (
    <>
      
                
                    
                    
                        You're not online
                        Check your internet connection.
                    

                

      
      {children}
    
  );
}

We’ve added the logic that makes it do something! We have two state variables, online which will reflect our network state (boolean) and previousOnline which allows us to prevent the overlay appearing on first load which we'll set up shortly.

The useEffect hook only runs once (on first render) and sets up our window event listeners. The function that's returned will be run on page unload and will clear those same listeners. useBooleanState is a hook provided by webrix and is a simple convenience hook for boolean manipulation.

import cx from 'classnames';
import { useEffect } from 'react';
import { useBooleanState, usePrevious } from 'webrix/hooks';
import { ReactComponent as OfflineLogo } from 'assets/images/logo-offline-icon.svg';
import Text from '../Text';
import './_offline.scss';

export default function Offline({ children }) {
  const { value: online, setFalse: setOffline, setTrue: setOnline } = useBooleanState(navigator.onLine);
    const previousOnline = usePrevious(online);

    useEffect(() => {
        window.addEventListener('online', setOnline);
        window.addEventListener('offline', setOffline);

        return () => {
            window.removeEventListener('online', setOnline);
            window.removeEventListener('offline', setOffline);
        };
    }, []);

  return (
    <>
                 className={cx(
                    'offline',
                    'animate__animated',
                    'animate__faster',

                // This should be backticks, but the syntax highlighting gets confused so I've made it single quotes
                    'animate__${online ? 'slideOutUp' : 'slideInDown'}'
                )}
                style={previousOnline === online && online ? { display: 'none' } : void 0}
        >
                
                    
                    
                        You're not online
                        Check your internet connection.
                    

                

            
      {children}
    
  );
}

Now we’ll actually use our online variable to do some cool stuff! Firstly, we're adding a conditional class to our overlay, which we'll style later.

Next, we’re making it a bit more shiny with animation! I’ve used animate.css to make the bubble slide in and out of the screen. It provides us some animation classnames we can use.

Finally, we’ve added a conditional style to our container, to cover the initial load when we’re connected. This prevents the bubble from appearing and immediately sliding out of view.

import cx from 'classnames';
import { useEffect } from 'react';
import { useBooleanState, usePrevious } from 'webrix/hooks';
import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock';
import { ReactComponent as OfflineLogo } from 'assets/images/logo-offline-icon.svg';
import Text from '../Text';
import './_offline.scss';

export default function Offline({ children }) {
  const { value: online, setFalse: setOffline, setTrue: setOnline } = useBooleanState(navigator.onLine);
    const previousOnline = usePrevious(online);

  useEffect(() => {
        if (!online) { return void disableBodyScroll(document.body); }

        enableBodyScroll(document.body);
    }, [online]);

    useEffect(() => {
        window.addEventListener('online', setOnline);
        window.addEventListener('offline', setOffline);

        return () => {
            window.removeEventListener('online', setOnline);
            window.removeEventListener('offline', setOffline);
        };
    }, []);

  return (
    <>
                 className={cx(
                    'offline',
                    'animate__animated',
                    'animate__faster',

                // This should be backticks, but the syntax highlighting gets confused so I've made it single quotes
                    'animate__${online ? 'slideOutUp' : 'slideInDown'}'
                )}
                style={previousOnline === online && online ? { display: 'none' } : void 0}
        >
                
                    
                    
                        You're not online
                        Check your internet connection.
                    

                

            
      {children}
    
  );
}

Last but not least, let’s lock scrolling. Remember the earlier requirement? When the overlay and bubble are open the user shouldn’t be able to scroll in the background. For this, we use a library called body-scroll-lock and simply toggle the lock in our new useEffect hook.

The Styling

Styling in SCSS is pretty simple. Here’s how we can get the result above:

@import 'vars';

.offline {
  position: fixed;
  top: 0;
  z-index: 4;
  left: calc(50% - 200px);
  width: 400px;
  padding-top: 40px;

  @media only screen and (max-width: $mobile-width) {
    padding-top: 20px;
  }

  @media only screen and (max-width: 500px) {
    padding-top: 20px;
    width: calc(100% - 40px);
    left: 20px;
  }

  &__content {
    padding: 15px 20px;
    background: white;
    display: flex;
    align-items: center;
    justify-content: center;
    border-radius: 6px;

    > svg {
      height: 50px;
      width: auto;
      margin-right: 20px;
    }
  }

  &__overlay {
    position: fixed;
    z-index: 3;
    background: rgba(0, 0, 0, 0.8);
    top: 0;
    left: 0;
    width: 100vw;
    height: 100vh;
    opacity: 0;
    transition: opacity 0.5s ease-in-out;
    pointer-events: none;

    &--visible {
      opacity: 1;
      pointer-events: unset;
    }
  }
}

Parts worth talking about are:

Hardcoded right %, instead of translate. animate.css uses transforms to animate, so we need a different approach to center it horizontally.
@import 'vars' - this is just a file full of SCSS variables. The media query variable is just a pixel value.
padding: top instead of an actual top value - animate.css uses transform: translateY(-100%) on the container when sliding it out. If we use a top value, the component won't slide completely out of view. If we give it padding instead, we are making the component larger and therefore will all slide out, but still have the gap from the top of the screen.

Using It In Our App

You can use the component wherever you want, but I recommend as high as possible. In mine, it’s in the app index file:

ReactDOM.render(
  
    
        
    
  ,
  document.getElementById('root')
);

Icons & Splash Screens

Manifest.json

The manifest file is used to tell platforms how we want our PWA to behave. create-react-app creates a manifest.json file automatically for us, in the public folder.

{
  "short_name": "name",
  "name": "name",
  "description": "description",
  "icons": [
    {
      "src": "/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "background_color": "#fff"
}

short_name - the title that's displayed on smaller areas, such as on home screens

name - the full title of the app

description - app description

icons - these are icons used on an android home screen or for PWA desktop apps on desktop.These are not used on iOS PWAs (see gotchas below)

start_url - entry point to your application. For standard React apps, this will be root, or .

display - how should your app be displayed within a PWA container? standalone will render full screen and give a more native experience

background_color - loading screen background colour (such as on a splash screen). This is not the background colour of your app when loaded.

theme_color - this dictates the color of the status bar at the top of the app, however I choose to just use the theme tag in index.html as I can dynamically change it (see themes below).

For my app, I took my app’s logo and turned it into a macOS-esque rounded icon, such as:

Full breakdown of the manifest.json file can be found here. Your index.html file should link to this manifest, with a line similar to .

iOS & Gotchas

iOS still doesn’t handle PWAs very well. Your manifest file will be pretty much ignored, other than to tell iOS you support PWAs. PWAs are only supported via Safari.

iOS does not support transparency on icons. It’ll render a black background behind your icon if it’s a png. You should make special icons for iOS, with a coloured background (mine’s white), which looks like:

To use it, we’ll need the link in our index.html file.

Splash Screens

To show a splash screen on iOS when the app’s loading, you’ll need a series of html code lines in index.html. Unfortunately, you'll need a different sized image per supported resolution:

Themes & Theme Colours

As mentioned before, we’ll control theme through index.html and not using manifest.json. Find out more about theme-color and what it looks like in action, here.

Static Theme Colour

Static theme colours are easy. Simply include this line in your index.html file. . create-react-app provides this by default.

Dynamic Theme Colour

In your app, you might have different page colours. For example, in my app, the homepage is green, but the rest are white. I wanted the theme-color to change based on where I was. When a Modal window opens, the theme-color becomes black.

For this, you’ll need a library called react-helmet. Helmet allows us to modify the of our document from within our components. Sweet!

To do this, simply include the element in any of your components:

We can actually extend the Offline.js component we built earlier to make the status bar black:

    className={cx(
        'offline',
        'animate__animated',
        'animate__faster',

    // This should be backticks, but the syntax highlighting gets confused so I've made it single quotes
        'animate__${online ? 'slideOutUp' : 'slideInDown'}'
    )}
    style={previousOnline === online && online ? { display: 'none' } : void 0}
>

  // The line below changes the theme dynamically, but only when we're offline
    {!online && }

    
        
        
            You're not online
            Check your internet connection.

Extras

Thanks for reading! Feel free to leave feedback 🚀

What is function Memoization and why should you care?

Alex Gurr — Wed, 20 Oct 2021 08:25:52 GMT

Memoization is a general software engineering principal/idealogy that can be applied to code in any language. My examples and libraries will all be JavaScript.

So What is Memoization?

Memoization is the principal of caching the result of a function call. If you call a function multiple times with the same arguments, you’ll get the cached result every time. The logic in your function will not re-run when there’s a cached result.

Why/When Would I Ever Need This?

Memoization is great when you find functions being called over and over again (such as in a render call in React). Your function might have some complex logic that your performance would benefit from by not calling the same logic over and over.

tl;dr performance for functions called multiple times with the same arguments.

Memoization in React

The concept of Memoization in React is exactly the same. We want to cache the result of a function call. Except in this scenario, our function returns JSX and our arguments are props.

If you have a parent being re-rendered, your child function will be called on every render, even if the props don’t change. React provides us a React.memo utility and a useMemo hook which we can utilise in our functional components to prevent unnecessary re-renders.

We can also utilise normal Memoization in class methods and other JS functions in our react components. A traditional pattern in React class components was to react to prop changes through componentWillReceiveProps, apply some logic to a prop and set it in state. Now that componentWillReceiveProps is on the way to being deprecated, Memoization provides us a great alternative method to achieving the same result. See the examples section below.

https://reactjs.org/docs/react-api.html#reactmemo

Some vanilla JS memoization Libraries

For general JavaScript, I’d recommend two battle-tested libraries instead of trying to implement yourself, which I’ve covered below.

Lodash.memoize

Creates a memoization results map, meaning it will effectively store the history of all results for use in the future.

Serialises only the first argument to string. Be careful about passing objects. Multiple arguments aren’t compared.

Useful if you’re calling the function from multiple places with different arguments.

https://lodash.com/docs/4.17.15#memoize

Memoize One

Stores the last result of the function call. Will only ever compare the arguments to the last ones the function was called with.

Uses all the arguments for comparison between function calls. No serialisation of objects so you can pass anything.

Useful if you’re only calling the memoized function from one place.

https://github.com/alexreardon/memoize-one

Differences Between the Two

Lodash memoize will serialize the arguments to use as a map key
Lodash memoize will only use the first argument
Memoize One will only remember the set of arguments/result of the previous function call. Lodash memoize will maintain a result map.

How About Some Examples?

A normal function

import _memoize from 'lodash.memoize';
import memoizeOne from 'memoize-one';

const myFunc = users => users.filter(user => user.gender === 'female');

const myMemoizedFunc = _memoize(user => users.filter(user => user.gender === 'female'));

const myMemoizedOnceFunc = memoizeOne(user => users.filter(user => user.gender === 'female'));

React.memo

import React, { memo } from 'react';

function MyFunctionalComponent {
  return ;
}

export default memo(MyFunctionalComponent);

Before/After, React class component real world scenario

Before

import React, { Component } from 'react';

function filterUsers(users) {
  return users.filter(({ gender }) => gender === 'female');
}

export default class FemaleUserList extends Component {
  constructor(props) {
    super(props);

    const { allUsers } = props;

    this.state = {
      femaleUsers: filterUsers(allUsers)
    }
  }

  componentWillReceiveProps(nextProps) {
    const { allUsers } = nextProps;

    if (allUsers !== this.props.allUsers) {
      this.setState({
        femaleUsers: filterUsers(allUsers)
      });
    }
  }

  render() {
    const { femaleUsers } = this.state;

    return femaleUsers.map(User);
  }  
}

After

import React, { Component } from 'react';
import memoizeOne from 'memoize-one';

export default class FemaleUserList extends Component {
  // We bind this function to the class now because the cached results are scoped to this class instance
  filterUsers = memoizeOne(users => users.filter(({ gender }) => gender === 'female'));

  render() {
    const { allUsers  } = this.props;
    const femaleUsers = this.filterUsers(allUsers);

    return femaleUsers.map(User);
  }
}

A React form

import React, { Component } from 'react';
import _memoize from 'lodash.memoize';

export default class FemaleUserList extends Component {
  // Yes, we can even return cached functions! This means we don't have to
  // keep creating new anonymous functions
  handleFieldChange = _memoize((fieldName) => ({ target: { value } }) => {
    this.setState({ [fieldName]: value });
  });

  render() {
    const { email, password } = this.state;

    return (
      
        
                  onChange={this.handleFieldChange('password')}
          value={password}
          type="password"
        />
      

    );
  }
}

Closing Words

Memoization is a great tool in a developer’s arsenal. When used correctly and in the right places, it can provide great performance improvements.

Just be aware of the gotchas, especially when using React.memo and expecting things to re-render.

Creating a style utility file with some SCSS magic ✨

Alex Gurr — Wed, 20 Oct 2021 08:02:01 GMT

You might have used style frameworks in the past like Bootstrap or Bulma. Most of these types of libraries provide utility classes you can easily use in your HTML layouts, such as ml-10 for left margin, or pr-5 for right padding. One way of doing this is with a super long file and repetitive class declarations. Not very readable or scalable though is it?

In this article, we’ll dive into making our own utility style file with scss, using some cool scss magic you might not have used before. In our example we’ll be working with margin, but you could easily reproduce with any properties you like! The way we do this is flexible -- you provide the values for your classes (instead of mapping 1-100 for example).

Let’s make a new .scss file

Pretty easy. I’ll let you decide on how you want to do this.

Tip: you can structure your scss files similarly to JS files and make it super readable! I love using index.scss files to group imports within a folder, then having the parent import the index file.

Let’s set up some variables

We’re going to need 4 variables (a couple are optional):

auto (optional) - good practice to extract constants to variables. This is used to hold the auto value.

directions - an array of strings, to cover the 4 different directions our margin could be (top, bottom, left, right)

css-property-map (optional) - A scss map to map our directions above to CSS properties. SCSS maps work similarly to JS, with a key/value. I use this because I want my utility classes to be shorthand/small in size. You could avoid this by having the full direction in your class.

sizes: an array of CSS values. These are the utility classes/values we want to generate. I've also included an auto value which gets handled separately as it's not a standard px value.

$auto: auto;
$directions: 't', 'b', 'l', 'r';
$css-property-map: ('t': margin-top, 'b': margin-bottom, 'l': margin-left, 'r': margin-right);
$sizes: 0, 5, 10, 20, 30, 40, 50, 60, 100, $auto;

And now some loops

We set up a couple of dynamic loops (think for each loop in JS). This will give us all sizes for each direction.

@each $direction in $directions {
  @each $size in $sizes {
    // Classes coming here
  }
}

Generate the actual utility class

We dynamically create CSS classes for each direction/size combo. This will give us the classes in a .ml-5 format.

@each $direction in $directions {
  @each $size in $sizes {
    .m#{$direction}-#{$size} {
      // CSS property/values coming here
    }
  }
}

Setup the CSS properties and values

We compare the size to our previously defined auto value. If it's auto, we don't need to build a px value.

@if $size == $auto {
  #{map-get($css-property-map, $direction)}: $auto;
} @else {
  #{map-get($css-property-map, $direction)}: #{$size}px;
}

#{map-get($css-property-map, $direction)} let's us build dynamic CSS properties. Let's deep dive into what each bit means:

#{} - inject an SCSS variable into CSS
map-get(map, key) - pull out a value from a specific map with the passed key

Complete util code

$auto: auto;
$directions: 't', 'b', 'l', 'r';
$css-property-map: ('t': margin-top, 'b': margin-bottom, 'l': margin-left, 'r': margin-right);
$sizes: 0, 5, 10, 20, 30, 40, 50, 60, 100, $auto;

@each $direction in $directions {
  @each $size in $sizes {
    .m#{$direction}-#{$size} {
      @if $size == $auto {
        #{map-get($css-property-map, $direction)}: $auto;
      } @else {
        #{map-get($css-property-map, $direction)}: #{$size}px;
      }
    }
  }
}