Adding a custom 404 page to your now.sh static Nuxt deployment

Static deployments with Nuxt are wonderful. You get great security benefits (good luck hacking an .html file), your entire website can be deployed to a content distribution network (CDN), greatly improving load time for your visitors, and there’s no back-end server to worry about scaling up and down to handle the performance concerns of large amounts of traffic.

At Braid, we frequently use now.sh to quickly and easily deploy static website builds we create. Now.sh is a “serverless” platform which, in short, means that they handle all of your infrastructure scaling needs for you transparently behind the scenes. While the convenience of automatically-scaling deployments is great, there are some caveats to be aware of when you don’t have full control of the environment to which your project is being deployed.

One of these caveats is needing to follow a special syntax in your project’s now.json configuration file in order to avoid serving up the default now.sh to your site visitors when they hit a broken link

This 404 page, while not bad looking, probably isn’t the look you’re going for when it comes to your own project. So how do we replace it?

Setting up a custom 404 page on a now.sh static deployment

When building a static project with Nuxt your now.json configuration file probably looks something like this:

The routes key contains an array of objects that define how a given URL should be handled. In the above configuration the ”handle”: “filesystem” rule makes sure that any files that exist on the file system are able to be loaded directly in the browser (for example, .html or .pdf files included in the project). In our case, we have a 404.html file being generated in our project, but with the above config we’d only ever see if we literally loaded the route /404.html. This isn’t very helpful because we want the 404 template to load whenever we hit a route that does not exist in our project, not just at its literal destination.

So how do we get dynamic routing to our 404 template? The solution is to tell now.sh what file we would like it to load in response to a 404 response code. We can do so by adding the following object to our routes array:

This results in a new now.json config file that looks like this:

Now, whenever now.sh see’s a response with a status code of 404 it will load the 404.html file from your project and display it at the broken route rather that the now.sh default 404 page. In the case of https://www.wearebraid.com that means we get a page that looks like this:

Much better! Now our users won’t feel like they’ve been redirected to some unexpected location if they end up following a broken link on our site.

Conclusion

Serverless solutions such as now.sh offer a tremendous amount of convenience to developers as well as performance benefits to end users, but due to the restricted nature of their platform there are occasionally special steps that need to be taken in order to provide expected behavior such as branded 404 pages. Fortunately, the team at Zeit (the creators of now.sh) have been working hard to address these issues and create simple configuration settings to address them.