Cloud cron jobs with Netlify Scheduled Functions

Netlify Scheduled Functions let you run a serverless function on a schedule, like a cron job, but in the cloud.

A traditional cron job needs a server that’s always on. With scheduled functions there’s no server to maintain. Netlify runs your function at the times you choose, and that’s it.

Here’s how to set them up.

Create a serverless function in netlify/functions in your repository, for example test.js:

netlify/functions/test.js

export default async (req) => {
  const { next_run } = await req.json()
  console.log('Next run at:', next_run)
  // do something
}

export const config = {
  schedule: '@hourly',
}

The scheduled request body includes next_run, the timestamp of the following run. Log it if you want. You don’t need to return { statusCode: 200 } the way older exports.handler functions did. Finish the work and return, or just let the function complete.

You can also set the schedule in netlify.toml instead of export const config. Create the file if you don’t have it yet:

[functions."test"]
schedule = "@hourly"

With the schedule in netlify.toml, the function file only needs the handler:

export default async (req) => {
  const { next_run } = await req.json()
  console.log('Next run at:', next_run)
  // do something
}

@hourly runs every hour at minute 0. @daily runs every day at 00:00. @weekly runs every Sunday at 00:00.

@monthly and @yearly are available too.

You can also use a cron expression, like 5 4 * * * or any other expression (crontab guru is your friend).

Watch out for the timezone

Schedules run in UTC, not in your local timezone.

I got bitten by this. I set 0 7 * * * expecting the function to run at 7 AM my time, and it ran at 7 AM UTC instead. If you need a specific local time, adjust the cron expression to the equivalent UTC time.

Also note that scheduled functions only run on the published production deploy. They don’t run on deploy previews or branch deploys, and they don’t fire while you work locally.

How to test a scheduled function

You don’t want to wait an hour to see if your function works.

Using the Netlify CLI you can invoke it manually with netlify functions:invoke test, where test is the name of the function.

One more thing: nobody receives the response of a scheduled function. Netlify only cares that the run finished. Log anything you need with console.log().

What I use them for

You can use Netlify Scheduled Functions for many different use cases.

I set a Netlify Scheduled Function to auto-deploy the repository every day to publish scheduled blog posts, for which I set the publishing date in advance.

I use the Fetch API to call the deploy webhook so I can do automatic deploys on Netlify.

Want me to talk about your product? You can sponsor this site.