DEV Community: Phil Hawksworth

Avoiding lock-in for your image pipeline with Nuxt Image and Netlify Image CDN

Phil Hawksworth — Fri, 19 Apr 2024 09:53:12 +0000

Resizing and optimizing image assets in our web projects has become both an important part of the efforts to safeguard performance, and also a common developer experience or code efficiency wrinkle. Many frameworks seek to streamline this for users and developers alike, and often leverage image services such as Netlify Image CDN, Cloudinary, or Imgix. Nuxt Image does this in a way that does not lock you in to any one provider, and is incredibly simple to set up with Netlify.

TL;DR

Here, we'll look at the steps to adding Nuxt Image to a Nuxt project, and see how it is automatically powered by Netlify Image CDN when deployed to Netlify. We'll also see how this can be used and tested in a local development context.

Prerequisites

To code along as we go, you'll need:

Node.js
Netlify CLI for local development with Netlify Image
A Netlify account for deploying a version to test in production

JFDI (just deploy it)

If you'd prefer to just clone and deploy an example to explore, click the button below and you'll very quickly have an example Nuxt site using Netlify Image to power Nuxt Image deployed and ready to tinker with.

Adding Nuxt Image to a Nuxt project

Nuxt Image is a module dedicated to providing image asset optimization, resizing, and associated markup generation for your Nuxt sites. If you have a project already, you can add it that, or if you'd prefer a totally clean start, use the Nuxt CLI (nuxi) to quickly create a new starter Nuxt project to experiment with.

npx nuxi@latest init my-app

Add the Nuxt Image module as a dependency to your project

The Nuxt CLI can help us with this too, which for convenience, we can use via npx like this:

npx nuxi@latest module add image

Tell your Nuxt project that you're using the module

Adding the module to your Nuxt configuration file, nuxt.config.js, will make <NuxtImg> and <NuxtPicture> components available to use in your application.

export default defineNuxtConfig({
  modules: ["@nuxt/image"],
});

Add an image to your application using `<NuxtImg>`

Nuxt Image and Netlify Image CDN can serve images assets which are part of the site repo or sourced from an external resource. To start, let's add a local image and display it in a page template.

Various attributes and modifiers can be set and passed along to the underlying image service provider.

<NuxtImg src="owl.jpg" height="400" width="600" fit="cover" />

Testing Nuxt Image in your local environment

During development, you'll want to get a realistic picture (Yes, I saw this pun coming, and did nothing to avoid it. You're welcome) of how everything is working using the underlying image provider, in our case Netlify Image CDN. Luckily, we can gain access to this by simply running our local build with Netlify Dev.

Netlify Dev is bundled into Netlify CLI and will detect your local site characteristics and run your build for you when you run the command netlify dev in your project directory (or ntl dev if you want to save a few keystrokes)

By running your project with netlify dev you'll gain local access to a number of the facilities of the Netlify platform such as redirects, serverless and edge functions, blob storage, and Image CDN (which is what we care about here)

More specific local dev command control

If for some reason your project is not correctly detected and run by netlify dev, or if you have some exotic local dev commands that you run, you can configure this with a netlify.tomlfile.

Explicitly specifying Netlify Image CDN as a provider

Although Netlify will default to using Netlify CDN automatically, you can explicitly specify this by adding an image object to your nuxt.config.ts file and declaring your provider.

export default defineNuxtConfig({
  modules: ["@nuxt/image"],
  image: {
    provider: "netlify",
  },
});

Allowing external image sources

To use images from external sources in Nuxt Image, with the same optimizations, CDN caching, and manipulation as with your local images, you need to declare the allowed domains by adding a domains array to your nuxt.config.ts file.

export default defineNuxtConfig({
  modules: ["@nuxt/image"],
  image: {
    provider: "netlify",
    domains: ["images.example.com"],
  },
});

Ummm... that's it

The tl;dr could perhaps have been:

Add the dependency
Add it to the config
Use the component
Ship it

Thanks to the thoughtful abstractions provided by Nuxt Image, this is all you need to do to use <NuxtImg> with Netlify powering the image optimizations and manipulations. You might have noticed that we've not even added any mention of Netlify Image CDN to the codebase at this stage.

Nuxt Image will automatically detect when it's being deployed to Netlify and use Netlify Image under the hood.

The power of primitives

One of the principles we value at Netlify is providing developers and framework authors access to powerful primitives to power their applications (or the frameworks that power the applications of others).

Nuxt Image makes use of one such primitive perfectly here, offering convenience to Nuxt users without the need to learn about the underlying primitives (although you could use the Image CDN directly if you wished, or if your site didn't justify the use of a framework).

More information

Trigger a site update from anything that speaks HTTP with build hooks

Phil Hawksworth — Tue, 02 Apr 2024 09:40:00 +0000

Many might remember (or still be subjected to) long, drawn-out deployment processes. Complex, monolithic products often needed a time-consuming deployment process, taking many days and many people. CI/CD tooling transformed this aspect of web development and also unlocked the potential for highly performant and robust static assets to power sites that frequently update to stay fresh. Triggering a site build and deployment at the right moment is key to this, and build hooks give us that ability.

TL;DR

We can manage and monitor the events that trigger updates to our sites with build hooks. In this guide, we'll see how simple it is to create build hooks from the Netlify UI or using the CLI, and show how to conveniently test them.

Creating build hooks in the Netlify UI

By creating different build hooks, we can initiate new builds from all sorts of different events and see which event triggered our builds. To create a new build hook visit your Site configuration in the Netlify UI and go to Build & deploy to find the Build hooks panel.

You can select the branch that you'd like to deploy and give your new build hook a meaningful name.

It's not possible to edit existing build hooks, but the list of your site's build hooks gives easy access to copy their URLs, and to copy a cURL command to test them out. You can also delete build hooks from here too.

Creating build hooks with the Netlify CLI

The Netlify CLI doesn't include commands to manage build hooks, but the Netlify API does. Since the CLI also gives access to any API command, you can use that facility to do this from your command line or programmatically should you wish.

Bonus Netlify CLI tip

In addition to the built-in utilities in the Netlify CLI, you can also access API commands like so:

netlify api {API—METHOD}

Try running netlify api --list to show the available API methods and get quick access to their documentation.

Use the following command to list any build hooks on your site. (You'll need your Site ID, which you can get from the Netlify UI or from the CLI by running netlify status)

netlify api listSiteBuildHooks --data '{"site_id": "YOUR—SITE—ID"}'

To create a new build hook using the CLI, use the createSiteBuildHook API method, passing it the required data:

netlify api createSiteBuildHook --data '
  {
    "site_id": "YOUR—SITE—ID",
    "body": {"title":"My build hook", "branch":"main"}
  }'

The command will return information about your new build hook including its URL:

{
  "title": "My build hook",
  "branch": "main",
  "url": "https://api.netlify.com/build_hooks/66058fe91febf5273753e516",
  "draft": false,
  "created_at": "2024-03-28T15:42:33.674Z",
  "id": "66058fe91febf5273753e516",
  "site_id": "41d9d252-cc2d-4600-bf60-XXXX",
  "msg": "POST https://api.netlify.com/build_hooks/66058fe91febf5273753e516 to trigger a build"
}

Testing a Build Hook

Invoking a build hook is as simple as making an HTTP POST request to its URL. These URLs contain a unique, non-guessable path but no other form of authentication. It's recommended that you don't advertise your build hook URLs publicly, although it is trivial to delete a build hook and you can create as many as you need. (The ones in this post are all deleted, before you try to have some fun with me!)

You can make an HTTP POST from your command line using cURL. There is no payload to pass, just an HTTP POST to the correct URL. Like this:

curl -X POST -d {} https://api.netlify.com/build_hooks/{YOUR-BUILD-HOOK-ID}

After making the request, you'll see a new build identified with the label you gave to your build hook in your site's deploys in the Netlify UI. Or you could look for the newly requested build by inspecting your deploys with the Netlify Raycast extension if you prefer not to leave your desktop.

Safeguards against build thrashing

Triggering builds programmatically from a variety of different sources and events has the potential to swamp Netlify with requests to build and deploy your site, so we have some safeguards against that, and some recommendations to further protect your build minutes.

The Netlify Build Bots (as they are affectionately known internally at Netlify) have the intelligence to protect our systems and avoid wasting your build minutes. While a build is in progress, any additional build requests are queued behind it until the active build completes, at which time all subsequent build requests are skipped except for the most recent one. This avoids wasted builds that would have been quickly superseded and also gets the most recent request processed in a more timely way.

You can also avoid making excessive build requests by being thoughtful about what events you choose to trigger a build.

For instance, most headless content management systems (CMS) can post to a webhook for different types of events in their systems. Choose wisely here. For convenience, many save your content automatically as you type. This has saved my bacon (that is to say, my content) many times over the years, but also resulted in a lot of build requests to my sites as each keystroke created another request to build. Using the configuration of your chosen CMS to request a build based on publishing events rather than save events can be a good choice.

Uses for build hooks

Combining build hooks, with access to data and content from a variety of tools and services, and the ability to trigger calls to your build hooks from different events makes for a huge array of possibilities.

By making APIs the interfaces between services, and by making the incredibly ubiquitous HTTP the means to communicate between services and trigger actions, we can compose many tools and services together with excellent hygiene and defined roles and responsibilities.

Unifying content sources, digital asset management systems, version control systems, and so much more, all becomes viable and manageable.

In addition to the more conventional uses we might imagine, I've seen many creative uses of build hooks too, with people calling on them to trigger site builds from Alexa, Apple Shortcuts on an iWatch, hardware buttons, and even motion sensors!

Whether we're having fun or solving big, serious infrastructure and tooling challenges, the days of high friction and painful deployment processes are well and truly over.

More information

Using custom error handling if a serverless function has crashed

Phil Hawksworth — Mon, 25 Mar 2024 10:36:00 +0000

When code is executed at request-time rather than at build time, and if it influences what visitors to your site see, then it is vitally important that you can control what happens should that code encounter an error. Displaying a message like "a serverless function has crashed" or a cryptic HTTP error code makes for a rough user experience. That's why Netlify edge functions give you some helpful options to gracefully handle errors, and fully control the experience passed on to the users.

TL;DR

We'll look at how to configure the custom error handling available in Netlify edge functions, and try them out with some simplified examples which you can also clone and explore in your own local and deployed sites.

The default error page

If an error ever causes an edge function to crash, that error is written to the function logs and by default it will also be displayed as a response from the Edge Handler. This default function error page is helpful for the developer, but not so much for the user.

Custom error handling in edge functions

You can configure this error handling behavior to customize the experience. You have three options:

Show the default failure page
Silently bypass the error
Display your own custom error page

1. Show the default failure page

The custom error handling is configured directly in your edge function by adding an onError property to the config. If you don't specify an onError behavior, the default of fail will be used, as you can see here.

import { Config } from "@netlify/edge-functions";

export default async () => {
  throw new Error("error");
};

export const config: Config = {
  // Display the failure message
  // (This is the default behavior if not configured)
  onError: "fail",
};

2. Silently bypass the error

By setting the onError option to bypass, an erroring edge function still throws an error which is entered into the error logs, but it does not halt the progress of the request chain. If an asset was to be returned from this request, that will still happen even though the function encountered an error.

You can see that in this example, where an edge function is invoked on requests made to the intended page. Even though the function errors, you'll still reach the intended page.

import { Config } from "@netlify/edge-functions";

export default async () => {
  throw new Error("error");
};

export const config: Config = {
  // Silently bypass the error
  onError: "bypass",
};

3. Display your own custom error page

By setting the onError option to hold any path on your site, starting with /, the Edge function still throws an error which is entered into the error logs, but the user sees the result of am HTTP rewrite to the path of our choosing within the site. This allows us to let them down gently with whatever nicely designed experience we chose, while logging the error behind the scenes.

You can see that in this example where an edge function is invoked on requests made to the this erroring route which results in you seeing the custom error page.

import { Config } from "@netlify/edge-functions";

export default async () => {
  throw new Error("error");
};

export const config: Config = {
  // Redirect the user to any URL in your site
  onError: "/your-far-prettier-error-page",
};

Try for yourself

Visiting these example links only showed you the view intended for the user. To see the error logging behind the scenes, and to experiment more, you can clone and deploy your own version of these simple examples by clicking the button below.

Build faster with the official Netlify Raycast extension

Phil Hawksworth — Fri, 15 Mar 2024 10:25:00 +0000

Raycast is an outstanding productivity tool for Mac OS offering all sorts of utilities, helpers, and deep integrations. It also has a thriving extension ecosystem. Netlify's official Raycast extension utilizes Netlify's own APIs and offers a number of helpful tools and conveniences for developers building for the web with Netlify.

TL;DR

This post shows how to install the free Netlify Raycast extension, and explores some of the useful features it provides. Don't fancy reading? There is a quick video summary too.

Install the free extension

Existing Raycast users can just click the button below, or you can head over to the Raycast site for more information and the latest release details for the Netlify extension.

Direct docs access

Quick access to the Netlify docs with less context switching is really nice. You can search the docs from within the Raycast UI and also add shortcuts to pages and locations in the docs that you might visit regularly. Assign a hotkey or custom trigger for this and the friction reduces even further.

Explore sites and deploy resources

Raycast lets you swiftly find and access management of your sites hosted on Netlify. It's a speedy way to browse, filter, and access your sites, so you can see what is happening in your Netlify projects without leaving your desktop, and then jump directly into the site, admin, or repo you're interested in. The convenience of accessing site details, scoping by team, and navigating to GitHub repositories is a real bonus. I use this a lot, especially as a stepping stone to exploring site deploys or site repos.

You can also monitor your deploys this way. Access to the active and previous deploys is made more convenient thanks to the ability to filter by deploy context (such as branch, preview, or production), and by team. I love being able to see the status of a recent build quickly, and then quickly access the underlying pull request or code change that triggered the build. This is all available via the Netlify admin, but having it accessible quickly from the Raycast UI brings it closer to where I am working and speeds me up.

Find local Netlify projects

You can also use this to locate your Netlify projects on your local machine. Raycast makes them available for you to filter by name to quickly find projects and get into your code fast. After finding your local project, you can jump into it, open the underlying version control repo, open the Netlify admin for this project and more.

Review team actions

Working in a team? There's extra help for you here too. The extension gives quick access to the team audit log. This functionality can be really useful for teams collaborating on projects and accounts, allowing you to filter and review actions taken on the account by colleagues and collaborators. With the ability to filter by team and access the details of audit logs, team actions across projects become more transparent. Very handy.

There's more to explore in this extension, and you can also submit feature requests vis the Raycast code repo. Why not install it and give it a try?

Install the free extension

You can visit the Netlify Raycast extension page for more information about the extension and to install it from there, or if you're already a Raycast user, you can click the link below to install it directly.

How to serve optimized images using Netlify's Image CDN

Phil Hawksworth — Mon, 04 Mar 2024 13:11:00 +0000

Not only can Netlify's Image CDN optimize image assets to improve site performance, but it can also handle common asset manipulation tasks on the fly. This cuts your site build times and powers valuable techniques such as responsive images and lazy loading.

TL;DR

Use a URL like this to serve your image through Netlify's Image CDN:

/.netlify/images/?url=/images/your-image.jpeg

This post explains how you can quickly start using the Netlify Image CDN, and demonstrates some helpful techniques to make using this service fit conveniently into your development workflow. Learn how to use a single image to provide all of the required asset sizes for responsive images.

No setup required, just a URL

To begin using Netlify's Image CDN, you don't need to install or enable anything in your Netlify Admin. You simply need to make requests for your assets via a special URL pattern that Netlify recognizes:

# An image served from your site's files
/images/some-image.jpeg

# The same image, but served from Netlify's optimized Image CDN
/.netlify/images/?url=/images/some-image.jpeg

You might recognize this special URL pattern from other tools you can use in your sites on Netlify, such as Netlify Functions. That /.netlify/ path is reserved on Netlify to access these sorts of helpers and utilities, so for those already using Netlify Functions this will already feel a little familiar.

Convenience and future-proofing

When using a service like this, I like to make it as unobtrusive in my code as possible. That way, should I ever wish to swap it out for an alternative, I can do so without a major refactor. Since the API is the URL, a small amount of abstraction using Netlify Redirects can help us achieve that.

Let's create a convenient URL pattern we can use to serve the full-sized original image, but serve it from the Netlify Image CDN rather from our own site assets. A few lines in our netlify.toml file will do that for us:

[[redirects]]
  # Requests to URLs matching this pattern...
  from = "/images/full/:file"
  # ...will resolve to this URL pattern
  to = "/.netlify/images/?url=/images/:file"
  # ... and the status code of 200 will make this behave as a rewrite
  status = 200

Other excellent Image CDN and optimization services out there like Cloudinary or Imgix also let you control their APIs through URLs. This means that should you need to upgrade to another service, perhaps to gain access to their more detailed asset manipulation features, you can do so by modifying the URL redirect rules here in your netlify.toml (after creating accounts with them, for example), and leave all of the image URLs across your site untouched.

With our redirect rule in place, a small change to the path used to source our images will let us choose to serve that image from the Image CDN.

From this:

<!-- an image served from my assets folder -->
<img src="/images/seedlings.jpg" alt="A photo of some green seedlings" />

to this:

<!-- an image served from my Netlify's Image CDN, originally sourced from my assets folder -->
<img src="/images/full/seedlings.jpg" alt="A photo of some green seedlings" />

Tip: Assets can be on your sites or third party domains

Netlify's Image CDN needs to source and ingest your image asset before it can optimize, cache, and serve it, which is done by specifying the URL where this can be found. This might be within your site or an external domain. For security reasons, requests for assets on external domains require a little config, which we'll get to later.

On-demand image resizing and manipulation

The Netlify Image CDN can also perform a number of image manipulation tasks for us. It's very common to need differently sized versions of images for optimal display, as seen in our responsive image example above. Doing this for every single image in your site as part of each build can be computationally expensive and make builds take a long time. Handing this off to Netlify to do on-demand the first time an asset is requested in a given size and then caching that result can simplify and speed up our build process.

Including a width or height parameter in the URL will return a suitably resized image. Using just one or the other will retain the aspect ratio for us. Like this:

/.netlify/images/?url=/images/blue-flowers.jpg&width=100

/.netlify/images/?url=/images/blue-flowers.jpg&width=200

/.netlify/images/?url=/images/blue-flowers.jpg&width=400

(Image credit: TOMOKO UJ, Unsplash)

Tip

For information about all of the parameters we support for things like resizing, cropping, transforming image formats,
and more, take a look at the Transform Images section of the Image CDN
documentation

Utility URLs for resizing

Now let's make these URLs more convenient and better abstracted on our site. Similar to the redirect rule we created for our full-sized images (/images/full/file-name.jpg), we could create some mappings for common sizes we might want so that the keywords small, medium, and large each map to a URL with given width parameters. We could also make a rule which lets us pass a width parameter dynamically, like this:

[[redirects]]
  # Get a width and file name value from the URL
  from = "/images/:width/:file"
  # ...and pass them along as the correct request parameters
  to = "/.netlify/images/?url=/images/:file&width=:width"
  status = 200

Order matters

Watch out for an easy mistake here. Netlify treats the order that rules appear in the netlify.toml file as the order of priority, meaning that the first matching rule found is the one that will be applied. This is handy for creating logic in your rules.

To make our example work as we would like, we need to add the rule that catches the variable input for width after the rule that catches the word "full" in the same part of the URL as shown below:


[[redirects]]
  # Serve a full size version
  from = "/images/full/:file"
  to = "/.netlify/images/?url=/images/:file"
  status = 200

[[redirects]]
  # ...or serve a resized version
  from = "/images/:width/:file"
  to = "/.netlify/images/?url=/images/:file&width=:width"
  status = 200

Nice. Now we have some intuitive URLs we can use to serve our images in any size.

/images/100/blue-flowers.jpg

/images/200/blue-flowers.jpg

/images/400/blue-flowers.jpg

(or /images/full/blue-flowers.jpg)

Different asset sizes for responsive images

We've got everything we need to deliver the different asset sizes for use in our srcset in responsive images. A full explanation of how the responsive images work is available at MDN, but here's a look the HTML:

<img
  srcset="
    /images/200/blue-flowers.jpg   200w,
    /images/400/blue-flowers.jpg   400w,
    /images/800/blue-flowers.jpg   800w,
    /images/1200/blue-flowers.jpg 1200w
  "
  sizes="(max-width: 450px) 200px,
         (max-width: 850px) 400px,
         (max-width: 100px) 800px,
         1200px"
  src="/images/1200/blue-flowers.jpg"
  alt="Some blue flowers"
/>

Lovely! We're using readable, intuitive image URLs serving assets that are resized, optimized, and cached for us on demand. And should we decide to make changes to the size variant in our set of images we only need to edit a URL.

Depending on what tools you are using to build your sites, this can also be a useful place for another bit of abstraction. A partial or a component that generates this markup for you when you pass it a file name and an alt tag (don't forget those alt tags, friends!) can keep your code nice and clear, and formalize some common conventions across your sites for how you deliver responsive images.

Using images from remote domains

The example here uses image assets which are part of the same site, so that relative paths are passed to Netlify's Image CDN.

You can also feed the Image CDN assets from external domains. In order to prevent your site from becoming a gateway for anyone to perform unlimited image transformations on any assets, we give you control over which domains can be used. To do this, it's time to add another bit of config to your netlify.toml file, where you can add an array of granted domains and use Reg Ex to describe detailed paths etc:

[images]
  remote_images = ["https://my-images.com/.*", "https://animals.more-images.com/[bcr]at/.*"]

Assets on relative paths, sourced from your site gain all the benefits of our atomic deploys and their default cache behaviors, so assets on the Image CDN don't become outdated as you deploy updates to your site. Assets on remote domains have different default cache characteristics. For information on how to control this, and other information about using remote domains with the Image CDN, take a look at the docs.

Bonus! Instant format optimization

You can specify the format you'd like to use to deliver your assets by providing a format (fm) parameter in the URL.

However, if you don't specify a format, the Netlify Image CDN will determine the most efficient format for the browser requesting the image, and automatically return that using the following logic:

Use avif if accepted
Otherwise, use webp if accepted
If neither is accepted, use the original format

Global infra in your local development

To get access to these capabilities while running your code in a local development environment, run your build using netlify dev which enables various Netlify Build and platform services locally, to smooth your development workflow.

Running your local build this way will provide handlers to those special /.netlify/ URLs, including automatically replicating the image transformation behaviour so that you can review appropriately as you build.

The netlify dev command is made available by installing the Netlify CLI and will serve your sites locally in a way that provides access to Netlify Functions, Edge Functions, Redirects, Image CDN and more.


# Install Netlify CLI
npm i -g netlify-cli

# Run your build with additional Netlify utilities
netlify dev

Try it on one of your sites today!

More resources for handling images

Netlify Image CDN documentation
Netlify Image CDN playground
Cloudinary + Netlify integration
Unpic an open source library of helpers for images and image CDN abstraction

Netlify trick: Adding pinned messages and thumbnails to projects

Phil Hawksworth — Fri, 16 Feb 2024 15:02:00 +0000

Anyone working with many projects over long periods of time in Netlify might be familiar with the task of seeking out a particular project in the Netlify admin. The sites page can get busy if you work on lots of projects, or if many people are collaborating and need to hop from project to project. Friction can kill your productivity momentum, so here are two little things that can make a big difference.

TL;DR

The Netlify admin supports custom thumbnail images and pinned messages on your site overviews. They are simple to use and this post will show you how.

Making the best of site thumbnails

When your site is deployed, Netlify will automatically generate a thumbnail image of the home page of your site which will be used to help you identify your sites in the site list page and in each sites overview page.

You can toggle between letting Netlify generate the thumbnail or providing an image of your own. This can be particularly helpful if you have many sites which look similar from a distance, or if you have sites which don't have much meaningful UI because they focus on providing APIs or services for example.

Specify a custom thumbnail image via the "Customize" button in your site's overview summary.

Make team collaboration easier with pinned messages

This much-requested feature makes it possible for you to locate valuable project information right in context and visible to collaborators (and let's be honest — future you) directly in the site overview page of your projects.

While much documentation about a project might live in a readme file in its code repository, some information is not appropriate to place there, or might not be so discoverable to all those needing that information. Pinned messages support markdown and are perfect for communicating useful project information to your teammates, such as project purposes, project lifespans, links to issue trackers, and links to project communication channels.

Or just emojis. You do you. 😉

Just show me

If you prefer to watch a quick video of this, here's how it looks.

Deploy a site to explore

You don't have any sites deployed on Netlify already, but you really want to click around and play with this feature? No problem, a couple of clicks and we'll get you an example site. Click the button below to get started.

Netlify tip: Explore and download assets generated by your builds

Phil Hawksworth — Mon, 12 Feb 2024 12:32:00 +0000

Understanding what assets your build generates is an important part of developing for the web. During local development that is usually easy to do, but what if you need compare the assets generated by a previous build? Or if you're looking for assurance that an asset is being faithfully generated by Netlify's build pipeline in the same way as it is locally? Netlify's Deploy file explorer can help.

TL;DR

You can download the output from any of your successful deploys in a single zip file, or by exploring the file structure generated by your builds. This post shows you where the Netlify Admin UI you can do this, and gives you a simple one-click deploy to try this out for yourself if you've never deployed a site to Netlify before.

Prerequisites

A Netlify account
A site successfully deployed to Netlify

If you don't have a site deployed to Netlify to experiment with yet, I've got you covered. Clicking the button below will create a new site for you from a simple template, set up the deployment pipeline, and perform your first deploy for your to explore.

Just show me

If you prefer to watch a quick video of this, here's how it looks.

Where to find the Deploy file explorer

The Deploy file explorer inspects the assets generated by completed build, so is available for each successful deploy regardless of if this is production, branch, or preview build.

Navigate to the Deploys page of any of your sites in the Netlify Admin, and then select any successful deploy.

Below the Deploy log panel, you'll find the Deploy file explorer where you can navigate through the assets tree of your generated build, and search within it to find precisely what you are looking for.

Download the entire deploy

You can also download any of your successful deploys in their entirety as a single zip file.

The information panel above the Deploy summary contains various pieces of information about your deploy. There you'll find a download link which will generate an archive for you to download as a single asset containing all of the files included in that deploy.

It's good practice not to commit build output to version control, so this feature is a useful way to quickly recover and explore historical archives of different versions of your sites.

Displaying your full-sized YouTube thumbnail or a custom OG image in a Twitter card

Phil Hawksworth — Wed, 05 Jul 2023 15:19:00 +0000

In days past, links to YouTube videos on Twitter used to show a nice full-sized thumbnail image. You could specify the poster image you wanted over in YouTube and it would appear along with an embedded video player.

These days, links to YouTube videos have been downgraded to only show a small image card which is frustrating for anyone wanting to share their videos on Twitter with a visible and inviting call to action to watch them. In an effort to make their videos stand out and attract clicks again, some have taken to attaching a thumbnail images directly to their tweets which, while making them visually appealing, get in the way of click-throughs as people find themselves just seeing a larger version of the image rather than viewing the video.

We can fix this with a crafty use of Netlify's Edge Functions.

How I enriched my link shortener

For some time, I've been using Netlify's redirects API to make my own simple link shortener. It lets me create short URLs for sharing resources using a domain that I own and the knowledge that I don't need to depend on a third party link-sharing service.

You can read about that in this blog post I wrote explaining it, including a handy little utility Kent C Dodds wrote to expand on this technique. (Also see Kent's video explainer for even more background info)

These days I use it in combination with a little Raycast script to make creating new URLs a snap.

Having a link shortener like this provides a nice opportunity. It offers the chance to add some logic to customise what everyone (and everything) that follows those links will see.

So, rather links to YouTube videos unfurling in Twitter like this:

They can look like this:

How to offer a different view to crawlers and unfurlers

When you share a link on Twitter and on other tools and social networks, they visit the URL and "unfurl" it in order to display a preview of what can be found there. We can give services like this hints about what we'd like them to show using metatags in the head of our HTML.

Since Netlify introduced Edge Functions we've had an ideal way to add a tiny bit of logic into our link shortener which will return a page template of our own to anything looking to unfurl the URL to display its opengraph image.

How to detect if Twitter is visiting your URL

While serving different experiences to visitors based on their brand of browser is generally understood to be a bad idea, and we should instead use feature detection if we are trying to work around differences in browser support for features we need, here it is the ideal match for our needs. So we can use UserAgent sniffing to decide if we should just redirect the visitor to the page our short URL points at, or to show our own custom page instead.

The code to do this in a netlify Edge Function is nice simple JavaScript (or TypeScript if you prefer)


// Detecting if Twitter is the requesting user agent
const agent = request.headers.get("user-agent");
if(agent.includes("Twitter")) {
  // Got something just for you, Twitter!
}

The URL we shared with Twitter is not a YouTube domain, it is on our custom domain, so Twitter won't automatically impose its own decisions about defaulting to a mini card. All we need to do is show it an HTML page with the appropriate opengraph data (which we can automatically get from the YouTube page that we're pointing at).

To do this, our edge function fetches the open graph data from the destination URL

// fetching the open graph data from the destination page, 
// and rendering it in a template

// Import Cheerio for easy DOM interrogation
import * as cheerio from "https://esm.sh/cheerio@1.0.0-rc.12";

// get the og data from the final destination page via our redirect lookup
const destination = await fetch(`https://custom-short-link.netlify.app/${url.pathname}`);
const html = await destination.text();
const $ = cheerio.load(html);

// Grab some OG data from the site
const title =  $('meta[property="og:title"]').attr('content') || "";
const description =  $('meta[property="og:description"]').attr('content') || "";
const site =  $('meta[property="og:site_name"]').attr('content') || "";
const orginal_image =  $('meta[property="og:image"]').attr('content') || "";

Now we have the open graph data from the destination page, we can use it in our own page template to render our custom view when a request is made with Twitter's user agent string.


// Our page template. 
// Just a string literal into which we can poke some variables
import page from "../og-page.js";

// Populate our OG page template
// and return it as HTML
const ogPage = page({
  site: site,
  title: title,
  description: description,
  path: url.pathname,
  domain: rootDomain,
  orginal_image: site == "YouTube" ? orginal_image : null
});
return new Response(ogPage, {
  headers: { "content-type": "text/html" },
});

The results

Now, just by making a convenient short link to any YouTube, when we share that link on Twitter it will display the large format image card within the tweet, but anyone clicking that preview card or following the link directly, will be taken to the video on YouTube. Nice.

Bonus. How to show custom OG images for third party URLs

There's more! Now that we have this logic which displays a custom page view to Twitter, we can use it to show any OG image we like and not just relay the one specified at the destination URL.

This lets us use our own branding when we share a shortened link on Twitter. By expanding the list of user agent strings that we detect, we can add the same support for other places that unfurl URLs to show a preview image, like Slack, Mastodon, LinkedIn and others.

A few more lines of logic in our function, and we can populate our custom template with our own OG image if we have one that matches the path in our short link. If not, not problem, just show the one intended by the owners of the destination page.

I've used this to add my own OG image when the link I'm sharing doesn't have one of its own, or I've wanted to enhance it for my own purposes, like this one below.

Try it for yourself

You can experiment with this without needing to buy a domain or pay for anything. Try deploying this demo repo to Netlify to get a your own URL shortener including the edge function which detects unfurlers and renders its custom template. It also includes Kent's netlify-shortener utility script which has instructions on how to add a system wide command to quickly shorten links for you.

The hardest part? Thinking of a good, short domain that you can register to use as your own short code domain. (You can register domains directly at Netlify too if you want to do the whole thing)

Resources

Link shortener with custom OG image support GitHub repo
Automatically clone the repo and deploy to Netlify
Kent C Dodd's Netlify-Shortener helper
How to add a Raycast script to make a new short link
Custom domains on Netlify
How my findthat.at link shortener works

What I learned from automating millions of web site deploys

Phil Hawksworth — Mon, 26 Sep 2022 11:53:05 +0000

Back in 2018 I decided to demonstrate how it had become feasible to automate the deployment of a web site thanks to modern web tooling and hosting services. I had been immersed in the world of enterprise web projects where deployments involved code and content freezes, a deployment team, holding your breath, and hoping for the best. the idea was triggered by this throw-away tweet from Zach Leatherman.

Free side project idea: HTML-only static site generated clock that deploys a new version to @netlify every minute
— Zach Leatherman

So I made setyourwatchby.netlify.app, a site which displayed the time. No client-side JavaScript to get the correct time for each visitor, just HTML containing the time that the site was generated as part of an automated build and deployment (and localised pages served up thanks to some CDN routing).

I've described this in some detail in the past, but let's move along.

The point I was making was that the friction and risk in deploying updates to a site had been so dramatically reduced, that it was now safe to perform unattended deployments automatically every single minute of the day.

From 2018 to 2022 the site has been automatically rebuilt and redeployed millions of times.

Time and technology moves on

As my millions of site deploy logs on Netlify will illustrate, time moves on. Reliable build automation has become readily available for developers, even in the enterprise space. But deploying every minute is silly, really. It's fine for making a point as part of a demo, but we can be far more efficient and responsible than that.

I needed to retire the demo site, but also wanted to make sure that you, dear reader, still had a way to tell the time! setyourwatchby.netlify.app still had to function even after I turned off the scheduled builds.

Edge Functions to the rescue

The arrival of Edge Functions saved the day. Netlify's Edge Functions are a low latency serverless runtime which can handle HTTP requests at locations close to the user and modify the HTTP response being returned. They provide a way to dynamically service every HTTP request without the need to manage and maintain a server. They're JavaScript, so I could just write a single function and be done.

That's what you'll find if you visit setyourwatchby.netlify.app now. Your request will be intercepted by an Edge Function running on Netlify's CDN which will determine your locale based on your IP address, and insert your current time into the HTML that it is sending to you.

No more regular redeployments for this little demo site.

But what did I learn?

Over the course of millions of unattended deployments, I did learn a few things.

1. Don't let your mistakes "leave the kitchen"

Borrowing this notion from the catering trade, it's fine for mistakes to happen in the kitchen, but they must never reach the diner. Automating deployment on this (or any) scale is possible thanks to the model where builds which fail do not result in a deployment being published.

My logs show that I had a few handfuls of builds which failed over the course of the millions of deployments since 2018, but they never worried me. The previous good deploy would always be visible until replaced by a new one, so at worst the time would be a wrong for one minute if a build broke or was skipped.

This level of confidence in automation is key to its success. And these days we include all sorts of tests to our automated builds to check for accessibility, performance, and other integrity before they can "leave the kitchen" and take their final journey out to the hosting infrastructure.

2. Knowledge is power

A model of immutable deployments, where each new build becomes an instance of the site which can live on in perpetuity, is incredibly powerful and liberating. By retaining every "known state" of a site over the course of its life, you gain the ability to redeploy any previous version of the site in milliseconds. Or to address any version of the site via a unique URL. Risk plummets when you know that you're not disrupting the integrity of your site, and can always revert.

For posterity, here is what the site looked like the very last time it was automatically redeployed.

3. Automating got easier

In 2018, I used a third party service to trigger a build of the site every minute. You can create webhooks on Netlify which trigger a build when called so this worked nicely.

Since then, Netlify released Scheduled Functions which give a cron-like interface for executing a serverless function. If I were to need to redeploy a site regularly these days, I'd use these to reduce the number of external services in play and make my life a little simpler.

Try Edge Functions yourself

If you want to learn more about Netlify Edge Functions you can explore some examples here, or visit the docs. Scheduled Functions are also very handy and simple to use, and you can find their docs here.

Lastly, if you want to know the time, you can still visit setyourwatchby.netlify.app, but I suspect you might have some other resources to help you with that :)

Seeing what triggered a build for confidence in each commit

Phil Hawksworth — Sat, 25 Dec 2021 23:27:04 +0000

Throughout December we'll be highlighting a different Netlify feature each day. It might just be the thing you need to unlock those creative juices, and dust off that domain you registered but never deployed! Keep an eye on the blog and on Twitter for each feature!
There are a number of ways to deploy a site to Netlify, or to trigger a build. So it can be helpful to see what code or content changes brought about an update to your site.

Perhaps a build was initiated by a build hook, in which case you’ll see that indicated in your Deploys page. But what if you are using Netlify Build to build your site whenever you push code changes to you repo?

Once again, the Deploys page in your project’s Netlify admin holds the answer.

Every deploy which was triggered by a code change includes a link to the commit. It gives you complete insight into what changes were responsible for the latest updates on your site. And into what to expect in the build.

Click on the git hash visible in each deploy summary to take you directly to that commit in your GitHub, GitLab, or Bitbucket repo.

More information

Monitor all of your team's projects with team audit logs

Phil Hawksworth — Fri, 24 Dec 2021 21:44:28 +0000

Throughout December we'll be highlighting a different Netlify feature each day. It might just be the thing you need to unlock those creative juices, and dust off that domain you registered but never deployed! Keep an eye on the blog and on Twitter for each feature!

When many people come together to collaborate on a project or on many projects, it can be difficult to keep track of what is happening. That’s why we created Team Audit logs.

Team audit logs give any team administrator a heartbeat view of all of the actions taken by members of a Netlify team.

Now, you have on place to check to see which of your projects have been deployed or updated and when, which projects have been rolled back and by whom, and many other activities which might be useful to know about.

Teams bring all sorts of useful ways to collaborate on all of your web projects in Netlify. And access to this summary of actions is a great part of monitoring the health and productivity of your team.

More information

Event notifications provide information and integrations

Phil Hawksworth — Thu, 23 Dec 2021 20:01:22 +0000

Throughout December we'll be highlighting a different Netlify feature each day. It might just be the thing you need to unlock those creative juices, and dust off that domain you registered but never deployed! Keep an eye on the blog and on Twitter for each feature!

Knowledge is power!

Knowing what events have taken place in your Netlify project, and being able to trigger actions based on those events, is pretty bloomin’ powerful too!

Netlify creates a variety of events throughout the lifecycle of your site deployments and for other services we provide for your sites, such as form submissions. Each of these events can create notifications and trigger actions elsewhere.

Combining tools and services using events and triggers opens up all kinds of fun possibilities for your projects!

What's happening?

Somebody submitted data to one of your forms? We’ll let you know.

Want to be notified if your site has been deployed, or if a deployment has failed? We have notifications for that.

Want to know if a pull request has triggered a build? Yep, we can let you know that too.

Here’s a list of events related to builds and deploys that we can inform you about:

Deploy started: Emitted when Netlify starts building your site for a new deploy.
Deploy succeeded: Emitted when Netlify finishes uploading a new deploy to our CDN.
Deploy failed: Emitted when a deploy does not complete.
Deploy locked: Emitted when the site is locked to a published deploy, stopping auto publishing.
Deploy unlocked: Emitted when deploys are unlocked, resuming auto publishing.
Deploy request pending: Emitted when an untrusted deploy requires approval to begin building, as specified by the site’s sensitive variable policy.
Deploy request accepted: Emitted when an untrusted deploy request is accepted and can begin building.
Deploy request rejected: Emitted when an untrusted deploy request is rejected.

More event notification details can be found in the docs.

Types of notifications

All of these events can trigger notifications. And you can configure what type of notification you receive for each event. Notification types include:

DEV Community: Phil Hawksworth

Avoiding lock-in for your image pipeline with Nuxt Image and Netlify Image CDN

TL;DR

Prerequisites

JFDI (just deploy it)

Adding Nuxt Image to a Nuxt project

Add the Nuxt Image module as a dependency to your project

Tell your Nuxt project that you're using the module

Add an image to your application using <NuxtImg>

Testing Nuxt Image in your local environment

Explicitly specifying Netlify Image CDN as a provider

Allowing external image sources

Ummm... that's it

The power of primitives

More information

Trigger a site update from anything that speaks HTTP with build hooks

TL;DR

Creating build hooks in the Netlify UI

Creating build hooks with the Netlify CLI

Bonus Netlify CLI tip

Testing a Build Hook

Safeguards against build thrashing

Uses for build hooks

More information

Using custom error handling if a serverless function has crashed

TL;DR

The default error page

Custom error handling in edge functions

1. Show the default failure page

2. Silently bypass the error

3. Display your own custom error page

Try for yourself

Further reading

Build faster with the official Netlify Raycast extension

TL;DR

Install the free extension

Direct docs access

Explore sites and deploy resources

Find local Netlify projects

Review team actions

Install the free extension

How to serve optimized images using Netlify's Image CDN

TL;DR

No setup required, just a URL

Convenience and future-proofing

Tip: Assets can be on your sites or third party domains

On-demand image resizing and manipulation

Tip

Utility URLs for resizing

Order matters

Different asset sizes for responsive images

Using images from remote domains

Bonus! Instant format optimization

Global infra in your local development

More resources for handling images

Netlify trick: Adding pinned messages and thumbnails to projects

TL;DR

Making the best of site thumbnails

Make team collaboration easier with pinned messages

Just show me

Deploy a site to explore

Netlify tip: Explore and download assets generated by your builds

TL;DR

Prerequisites

Just show me

Where to find the Deploy file explorer

Download the entire deploy

Displaying your full-sized YouTube thumbnail or a custom OG image in a Twitter card

How I enriched my link shortener

How to offer a different view to crawlers and unfurlers

How to detect if Twitter is visiting your URL

The results

Bonus. How to show custom OG images for third party URLs

Try it for yourself

Resources

What I learned from automating millions of web site deploys

Time and technology moves on

Edge Functions to the rescue

But what did I learn?

1. Don't let your mistakes "leave the kitchen"

Add an image to your application using `<NuxtImg>`