Guides & Tutorials

Render selected pages on-demand with on-demand builders

Guides & Tutorials

Render selected pages on-demand with on-demand builders

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!

For greater flexibility over when you render your pages, Netlify provide On-demand builders. They are a great way to defer the generation and persistence of some of your pages until they are first requested.

This can be a helpful way to keep site build times manageable, even for very extensive sites with large numbers of pages. Or you can use them to generate pages which contain dynamic data, perhaps data contributed by your visitors and not available during the build of your site.

Screenshot of the Every Color demo site

What does an on-demand builder look like?

On-demand builder are serverless functions with a particular configuration. We’ve already mentioned the Netlify Functions workflow this month, and on-demand builder functions are just an extension of those.

There are 2 main pieces to consider when building a site using on-demand builders:

1. What URLs will resolve to an on-demand builder function?

You can decide exactly which URLs will have their views generated by on-demand builders by using Netlify’s Redirects configuration. Here’s an example from a netlify.toml file which would specify a function.

# Generate the view of a less commonly requested page
# the first time it is requested via a serverless functions
[[redirects]]
  from = /not/popular/but/still/important/*
  to = /.netlify/builders/page-from-the-archive.js
  status = 200

Any on-demand build functions you create will available with the path /.netlify/builders/{function_name}, but how do you create them in the first place?

2. Create an on-demand builder function

You can write your functions in JavaScript or TypeScript and place them in either the default functions serverless directory, or wherever you chose and configure. Netlify provides a library function for you which tells Netlify’s Edge infrastructure how to serve and cache the response from your functions.

Here's an example of page-from-the-archive.js:

// Make "builder" method available from the Netlify functions package
// (don't forget to add the package to your package.json)
const { builder } = require("@netlify/functions");

// A handler function to generate a response
async function handler(event, context) {

  // Logic to generate the required content
  const htmlResponse = "<h1>Your content, on-demand!</h1>";

  // A response to return
  return {
    body:htmlResponse ,
    statusCode: 200,
    ttl: 3600, // An optional time to live for this response.
  }
}

// Wrap the handler function with Netlify's builder method
exports.handler = builder(handler);

On-demand functions are Netlify’s implementation of the Distributed Persistent Rendering (DPR) pattern. We think that it’s particularly powerful as it adds the ability to serve large sites, and sites with dynamic content without undermining some of the core attributes of Jamstack sites such as atomic and immutable deploys (which lead to some of those goodies we discussed this month such as instant rollbacks, deploy previews, and so on).

We have a simple demo site and repo which uses on-demand builder for you to explore. You can even deploy it yourself with a quick click of the button below.