What’s JournalBook?

JournalBook is a private, offline-first personal journal.

Your notes are only stored on your device — they’re never sent to a server. You don’t even need to sign-in to use it! It works offline, so you can reflect upon your day on the slow train journey home.

It’s quick, lightweight, and developed in the open. You can even add it to your homescreen as an app.

Why build it?

On one of the last days of work in 2018, one of my colleagues asked us about our highlights from the year. Sure, I could remember the big ticket items, but I quickly struggled to remember anything past that.

I’ve never been much of a writer, so keeping a diary or journal has never crossed my mind. But it dawned on me over the holiday that I would benefit from keeping some daily notes, not least to keep track of the small victories. I’m a creature of habit, and most days blend into one routine, so pulling out differences can be a challenge.

After considering existing solutions, I decided that building a small Progressive Web App would be perfect for this use case. Something that would work entirely offline, reading and writing directly to my device. Not only would it be faster, it would be personal and private, like a physical journal.

It needed to be a product that worked on the underground whilst on my commute home. But it also needed to be fully-featured, as ‘paper-like’ as possible, and a joy to use. I’m hoping JournalBook rises to those challenges.

How does it work?

Right, sales pitch over, let’s get technical. The stack is as follows:

• Preact
• IndexedDB
• Netlify

I chose Preact as it’s tiny and fast. This project would be more than achievable in Vanilla JS, but I’m working day-to-day in React so this seemed like a good way to build something nice and quickly. It was mostly built on Boxing Day and I didn’t want to get bogged down in application decisions!

IndexedDB wrapped with idb was the perfect local database layer. It’s all stored directly in the browser and I can separate the data far better than with LocalStorage. There are two data types: questions and entries. Each entry is autosaved to the cache each keypress so there’s no need for ‘save’ buttons, nor waiting for network requests to resolve.

As there’s no servers or databases storing user information, this was (yet again) an opportunity to use the wonderful Netlify. I’ve waxed lyrical about Netlify in the past so I won’t dwell on it too long, but once again it just worked. There’s nothing like it.

Even though the application works entirely offline, it’s still able to provide features like data import/export, data eradication and autosave. The former two features are thanks to Blob and FileReader. It’s genuinely incredible to me that you can read and write data files entirely in the browser. That’s bonkers! But amazingly, it’s not that complex, 15-20 lines of code for each and we’ve got personal data managment on the web!

What’s next?

To ensure I actually launched this product, and it didn’t fall into the pile of abandoned side-projects, I first created a Roadmap with features ranked in order of importance. There was an MVP column, a V1 column, and a backlog. By breaking it down this way, I could separate the ‘musts’ from the ‘coulds’ and the ‘shoulds’, and have sensible milestones for each release.

Now the V1 pile is clear, the product can be launched!

Next up is data visualisation, being able to navigate neatly to previous months/years, and the ability to search your content. I really don’t want to have heavy tracking on this, as it goes against the spirit of the product, but it would be nice to know if people are using it. Basically, I want a 90’s hit counter as a service! So that’s probably next on the list.

The product will continue to be developed in the open, so please file issues and suggestions on GitHub.

Ingrid Michaelson & Leslie Odom Jr.

In a client-side app, a new ApolloClient gets created for each page load. But in a node.js service, it runs once on application launch and sits in memory till the whole application has been killed - that could be days or weeks.

Not only that, as the server-side ApolloClient sits in memory, it’s shared between every user connection, and is therefore ripe for leaking data between connections. Not what we want.

To overcome this problem, we instantiate a new ApolloClient for each connection. We can wrap this up in a nice reusable method:

import { ApolloClient } from 'apollo-client';
import { createHttpLink } from 'apollo-link-http';
import { InMemoryCache } from 'apollo-cache-inmemory';
import { withClientState } from 'apollo-link-state';
import { ApolloLink } from 'apollo-link';

const CreateClient = (defaults = {}, links: any[] = []): ApolloClient<{}> => {
  const cache = new InMemoryCache();

  const stateLink = withClientState({
    cache,
    resolvers: {},
    defaults
  });

  return new ApolloClient({
    connectToDevTools: false,
    ssrMode: true,
    link: ApolloLink.from([
      stateLink,
      ...links,
      createHttpLink({
        uri: process.env.GRAPHQL_URL
      })
    ]),
    cache
  });
};

export { CreateClient };

We can then import the file on launch, and crucially, run the CreateClient function for each request. Not only that, we can pass in defaultState and prime the apollo-link-state cache with any user defaults. Furthermore, we can add additional link helpers like onError.

server.get('/*', async (req: express.Request, res: express.Response) => {
  const defaultState = {};
  const errorLink = onError((error) => {});

  const client: ApolloClient<{}> = CreateClient(defaultState, [errorLink]);

  const Application = () => {
    return (
      <ApolloProvider client={client}>
        <App />
      </ApolloProvider>
    )
  }

Reusing CreateClient

We could’ve run all that CreateClient code within the server.get method, but by moving it outside, we can reuse it in our tests. This time, there’s no defaultState or additional links, so we can call createClient directly.

import * as React from 'react';
import ApolloClient from 'apollo-client';
import { ApolloProvider } from 'react-apollo';
import { mount } from 'enzyme';
import { CreateClient } from '@/gql/CreateClient';
import { User } from '@/pages/User';

describe('<User /> page', () => {
  const client: ApolloClient<{}> = CreateClient();
  it('renders a user profile', () => {
    mount(
      <ApolloProvider client={client}>
        <User match={{ params: { username: 'trys' } }} />
      </ApolloProvider>
    );
  });
});

The first part is a linear gradient background. This feature is only going to work on -webkit browsers so we can use the -webkit-gradient.

h1 {
  background-image: -webkit-gradient(linear,0% 0%,100% 100%,from(#96A0DE),to(#4CACC1));
}

Next, we need to clip the background so it only appears behind the text:

h1 {
  -webkit-background-clip: text;
}

Then we hide the text fill so the background shows through:

h1 {
  -webkit-text-fill-color: transparent;
}

There are two final touches to make. Firstly, the headings are centred on my blog, and by default h1 is a block-level element. This’ll mean the heading, and therefore the gradient background will span the width of the parent, not the words inside. This would lead to a super-subtle gradient for short headings. By making the heading display: inline-block, the width and background are dictated by the word length.

Finally, this is a reasonably experimental feature only supported in -webkit browsers. We don’t want half a working feature, so we can use @support queries to our advantage:

@supports (-webkit-text-fill-color: transparent) {
  h1 {
    background-image: -webkit-gradient(linear,0% 0%,100% 100%,from(#96A0DE),to(#4CACC1));
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    display: inline-block;
  }
}

Here’s a ‘standard’ component as a starting point:

import * as React from 'react'

class Sidebar extends React.Component {
  public render() {
    // ...
  }
}

export { Sidebar }

On the surface, that final line looks like a ordinary object with property/value shorthand, but sadly that’s not the case. Assignment within that ‘object’ is not allowed, it only accepts a comma separated list. This prevents withApollo being assigned in a ‘normal’ object-y way:

export { Sidebar: withApollo(Sidebar) }

The solution

Although not very elegant, the best solution I found was to rename the original class declaration and export the correctly named wrapped variable:

import { withApollo } from 'react-apollo';

class SidebarComponent extends React.Component {
  public render() {
    // ...
  }
}

export const Sidebar = withApollo(SidebarComponent);

Now with added Typescript

The above code works well in JS-land, but Typescript tends to get a bit grumpy. The component needs to be aware of props being passed in from the withApollo HOC. The solution is to add a new type to the component:

import * as React from 'react';
import { withApollo, WithApolloClient } from 'react-apollo';

class SidebarComponent extends React.Component<WithApolloClient<{}>> {
  public render() {
    // ...
  }
}

export const Sidebar = withApollo(SidebarComponent);

If you already have some custom props defined on the component, they can be nested within the WithApolloClient annotation:

interface Props {
  id: number;
}

class SidebarComponent extends React.Component<WithApolloClient<Props>>

After six years, I’m moving on from the agency where I kicked off my career. I’ve learned all I know about web development in this time. But it’s the right time to move onwards and upwards.

A huge thank you to Mark for supporting, encouraging and believing in me.

Thanks to Mike for creating such amazing and interesting design work. It’s been such a pleasure to work on them with you.

Thanks to Simon for your incredible mentoring, support and sage advice - it’s seriously appreciated!

Thanks to Tom & Liam for your friendship, laughs and sass.

Thanks to Steve, Elliot & Kieran for all your help and amazing skills!

Thanks to Alex, Tim and the rest of the Slack gang for keeping me sane these past few years!

Thanks to my parents and siblings for their ever-attentive ears when I’ve rambled on about code and careers at you!

On Monday I start at Daisie. I’m so, so excited to get my teeth into this new challenge and help build an amazing project. It’s a huge gear-change for me. From a 15-minute drive and a rural agency, to a commute to the big smoke to build a product at a startup!

The time is right to be shaken out of my comfort zone - I can’t wait!

Being such a new technology, standards and best practices are yet to be formed, and I’m fascinated as to how these will evolve over the next couple of years.

Service Workers are most commonly used as a progressive enhancement, providing an offline fallback. But they can do so much more than that. What if they were central to your site architecture? What would that look like in practice? What if you build a Service worker-first web application?

Disclaimer: it’s impossible to be truly Service Worker/offline-first, a user must visit your site once on the network before the Service Worker can take hold. But the aim of this post is to consider the implications of moving towards an assumption of no network.

Network-first with cache fallback is a pretty safe option when it comes to PWAs, and a great starting point. But that only helps users with great or no connection, it doesn’t help those with slow connections, flaky connections, or high network costs.

The true power of a PWA is with offline-first

Offline-first has massive implications on UX and usability. Sadly it’s not as simple as flicking the switch and letting the cache do the work.

The ‘Webpack’ approach of ‘pre-cache all the things’ is regularly bundled into create-[FRAMEWORK]-app starter files. That might work for small applications, but I don’t believe it scales. Caching all routes is presumptive, and if you’re making regular changes to your site, those installation requests are going to mount up. As with most things on the real-world web, nuance is required.

There is so much to consider.

Stale content

How timely is your content. Does it matter if you’re reading ‘yesterdays’ website? My kneejerk reaction was yes, it does matter! But after dwelling on it, I think I’ve concluded it depends.

Some pages are so time-sensitive that no content is better than old content. But that’s pretty rare and I reckon most users would prefer to read something a little old, rather than nothing.

Are there some pages that must be served network-first? If so, how should they be flagged to the browser/Service Worker in a scalable system or CMS?

Could we use last-updated <meta> tags, or a TTL concept to keep content fresh? A means of checking whether the cached-content has past it’s sell-by date before deciding which caching strategy to use?

Running a background fetch after serving cached content helps keep everything up to date, but the user will always be one page refresh behind the ‘live’ content. This approach helps slow/flaky networks, but it still incurs a request per file, and the associated mobile data costs. Perhaps this background fetch should be limited to HTML requests only?

Refreshing

There are times when it’s crucial to get the user to see the latest version of the site. This could be for breaking news, a security fix, or a major new release.

Other times, you may wish to prompt the user with what’s changed, or just inform them that a new version of the page is available.

The activate event in the Service Worker lifecycle is the right point to check for new caches, so it’s also a good time to potentially alert the user to the change.

I wonder whether using different caches is a good distinguishing factor for these refresh events. When a cache is deleted, you can react accordingly. A deletion of the most crucial cache may send a message prompting the browser to perform an immediate reload, whereas a change to your CSS/JS cache may only prompt an update message.

Clear lines of communication between the Service Worker and browser are really important for an offline-first site. I think it feels right that the Service Worker should provide declarative information to the browser, rather than force changes itself.

There’s a difference between sending a message of ‘refresh the browser now’ and ‘the crucial cache has changed, how would you like to handle that information’. The first is a hammer/nut solution, but the second puts the control in the hands of the developer. They can decide when the time is right to refresh.

If a user was typing in your chat system, refreshing or even prompting for a refresh would be very disruptive. Much like the beforeinstallprompt event, delaying an update notification may be the smart move.

Workers use postMessage to communicate. It’s all string-based, so establishing an early standard pattern of communication with stringified objects is a good plan.

Slow networks

One of the biggest issues with the network-first approach is slow connections. In fact, network-first, cache-fallback sites perform best when you turn off your Wi-Fi. This is one of the main attractions to an offline-first approach!

I wonder whether a well-defined setTimeout race condition could be used to keep some assets as network-first, but with a sensible time limit. If the timer pings, the cached version could be served and the live version requested in the background, perhaps posting a message to the user alerting them to the new content.

Content updates

Like refreshing, it’s important to consider the best way to introduce new content into an existing page. If we view a page as offline-first, there may be regular arrivals of fresh content that need to be injected into the stale page.

For example, when you load the Twitter native app, you don’t immediately see the latest feed (let’s not dwell on non-chronological feeds just yet); you see the feed from where you left off last time. This happens regardless of your network conditions. If you’re online, the latest posts are fetched and injected at the top of the page, and you’re alerted that new content is available.

We need to be mindful of scroll position, page performance and screenreaders when injecting new content into a page.

Authentication

Handling login states in Service Workers requires yet more thought.

In some regards, the man-in-the-middle nature of Service Workers provides a neat way to handle all unauthorised requests. Listening for 403 errors in Response.status could be a good way to prompt the browser to redirect the user to the login screen. But given Service Workers are not supported by all browsers, it’s safer to ensure a server & client-side alternative is also put in place.

Purging most caches at the time of logout is probably a good step, but it’ll be important to leave a login page in a different cache. Again, nuance will be required to get authentication to feel just right in a website.

Releases

The ‘pre-cache all the things’ technique does throw up an interesting point about ‘releases’. The web is an ever-changing landscape, and fortunately, we don’t have to deal with app store walled gardens. But maybe there’s a thing or two that could be learned from staged releases.

With an offline-only approach, the only file requested at runtime is the Service Worker itself. Until that file is altered, the browser will keep merrily serving the cached files. This gives us the option to stage releases and prompt refreshes when they’re ready. I certainly don’t think that the daily multi-megabyte native app update pattern is worth copying, but perhaps there are elements worth exploring?

We need to be aware of local cache sizes, and handle them responsibly. Perhaps giving the user control to choose how much is being stored?

Consider a user on an expensive mobile data contract, do they need to load each user avatar on your web site? Thanks to the Service Worker pre-request design, we can cut off requests before they hit the network altogether, returning a pre-cached fallback image.

Non Service Worker support

Service Workers have great browser support but we can’t take that as a given. A service worker-first approach should still be progressively enhanced, but should also leverage the power of offline-first more than we currently do.

Serving content should always be the first priority, regardless of your Service Worker approach.

Classic cache-busting techniques still have their place, and need to be accounted for in our Service Workers. Again, clear lines of communication will ensure you’re handling your caching responsibilities correctly. For example, /style.css?ver=20180927, /style.20180927.css, and /style.css may need to be viewed as the same URL within the Service Worker.

Conclusion

Like all new technologies, patterns will emerge over time and standards will be forged. This is by no means to suggest a ‘bootstrap’ approach is right for all sites. But if we’re bundling generic Service Workers into starter files, we need to be sure they’re working as effectively as possible.

I’m so excited to see how we can use Service Workers to improve the web.

NPM updates

This site is written in Hugo and is compiled with hugo-bin. There are a few other devDependencies to take care of too.

NPM has a handy feature that warns you if your packages are getting out of date, or if any major security fixes are available. A quick run of npm audit fix did the job here.

Fonts - stage 1

As ever, Zach Leatherman provided the secrets to font optimisation!

Preload

I added a preload statement for the two web fonts on the site; it tells the browser to start downloading them earlier. Without a preload hint, the browser has to recieve and parse the CSS requesting the font, before it can make the request. I only preload the woff2 font as most browsers can serve this format now.

<link rel="preload" href="/fonts/[font_file].woff2" as="font" type="font/woff2" crossorigin>

Font-display

Adding font-display: swap to the @font-face block asks browsers to perform a FOUT, rather than a FOIT. It’s not hugely supported, but thanks to the declarative nature of CSS, that doesn’t matter!

Tidying up the home page

I have had two projects on the home page. They were mostly superfluous fluff. They’re gone now - saving two image requests!

That was enough for one evening, so I came back to the site today and make a few more changes…

Fonts - stage 2

Subsetting

After finally getting pip installed (it all got a bit ‘Hal changing a lightbulb’), Glyphhanger took huge chunks out of my font files by subsetting them.

It’s truly amazing. The two 17kb .woff2 files became 4kb!

I added the new fonts to the static directory and updated the @font-face references.

Service Worker font references

After running the site through WebPageTest, I was still seeing the old files being served. It transpired that the Service Worker was precaching them! Fortunately that was a quick change to the font references in the SW.

Meta description

I ran Lighthouse on the site, it showed 100 on all counts, apart from an SEO issue. Thanks to the brilliant descriptions, it showed that the home page was missing a meta description. Again, a nice quick fix.

Redirects error

When I checked the build status of a deployment, Netlify warned me that one of the redirects wasn’t formatted correctly. This is a new feature in Netlify’s deployment process, and it’s super-helpful. It alerts you to mixed-content warnings, header/redirect issues and more! It’s all outlined here.

Google Analytics

The cache time on Google Analytics has always frustrated me. WebPageTest and Google PageSpeed insights always complains that the GA JS file isn’t being cached heavily enough. Thanks to the wonderful ga-lite package, you can serve high-cache and minimal analytics! It’s all compatibe with GA, but a quarter of the size.

Results

The home page was: 147kb
The home page now is: 28kb

An article page was: 41kb An article page now is: 16kb

WebPageTest is showing all A’s and Lighthouse is all 100’s.

• Software disenchantment
• JavaScript v. backward compatibility
• Grumpy website
• Electron is flash for the desktop
• The website obesity crisis
• Six Fixes
• It’s dangerous to go stallone. Take Glyphhanger
• Disabling Ableist Language
• Ableism/Language
• A framework for web performance
• The 9am Rush Hour
• Apple - Accessibility

The weird, wild web is wonderful.