Deploy a Netlify Scheduled Function with TypeScript: A Step-by-Step Guide

Problem and Takeaway

You need a cron-like serverless function that runs on a schedule (for example, every six hours) and lives in your Netlify site repository. Netlify Scheduled Functions provide this capability, but they require a specific TypeScript setup, a correct netlify.toml schedule definition, and a deploy to register the cron. This guide walks you through creating, testing, and verifying a scheduled function so you can automate recurring tasks without managing infrastructure.

Prerequisites

• A Netlify account linked to a Git provider (GitHub, GitLab, or Bitbucket).
• Node.js 18+ and npm installed locally.
• Netlify CLI installed globally: npm i -g netlify-cli.
• An existing Netlify site initialized with netlify init (or a known site ID).
• Basic familiarity with TypeScript and the Netlify Functions directory structure (netlify/functions).

Procedure

1. Create the Scheduled Function

Add a new file netlify/functions/scheduled-task.ts with the following content. The handler logs the execution timestamp and returns a minimal HTTP response.

// netlify/functions/scheduled-task.ts
import type { Handler } from "@netlify/functions";

export const handler: Handler = async () => {
  const timestamp = new Date().toISOString();
  console.log(`Scheduled function executed at ${timestamp}`);
  return {
    statusCode: 200,
    body: "OK",
  };
};

Netlify compiles TypeScript automatically during build; ensure your tsconfig.json targets ES2020 and uses moduleResolution: node.

2. Define the Schedule in netlify.toml

Add or update the [[functions]] block in your repository root netlify.toml. The schedule uses UTC cron syntax.

# netlify.toml
[[functions]]
  name = "scheduled-task"
  schedule = "0 */6 * * *"  # Runs at minute 0 every 6 hours (UTC)
  path = "scheduled-task"

The name must match the function filename without extension. The path is the same value Netlify uses for the function endpoint.

3. Add Required Dev Dependency

Ensure package.json includes netlify-lambda as a devDependency (version 2.0.0 or later). This package provides local TypeScript compilation for netlify dev.

"devDependencies": {
  "netlify-lambda": "^2.0.0"
}

Run npm install to install the dependency.

4. Test Locally (Manual Invocation Only)

Start the Netlify development server:

netlify dev

This compiles the function and serves it at http://localhost:8888/.netlify/functions/scheduled-task. Note: netlify dev does not simulate scheduled triggers; you must invoke the endpoint manually (e.g., with curl or a browser) to verify the handler logic.

5. Commit, Push, and Deploy

Commit the new files and push to your Git provider. Netlify’s build process will:

1. Compile the TypeScript function.
2. Deploy the function to the Functions runtime.
3. Register the cron schedule defined in netlify.toml.

No additional CLI commands are required; the schedule becomes active after a successful deploy.

Expected Checks After Deploy

1. Dashboard verification: Open the Netlify dashboard → Functions → scheduled-task. The Schedule field should display 0 */6 * * *.
2. CLI list: Run netlify functions:list (requires Netlify CLI authentication) and confirm the function appears with the schedule attached.
3. Manual invocation: Execute netlify functions:invoke scheduled-task from your local terminal (linked to the site). Expect a 200 response with body OK.
4. Log inspection: After the next scheduled run (according to UTC), check the function logs in the dashboard for the timestamp line Scheduled function executed at ....
5. Build log: Verify the deploy log shows no TypeScript compilation errors.

Recovery Options

Issue	Diagnosis	Resolution
Schedule not registered	Dashboard shows empty Schedule field; netlify.toml syntax error or name mismatch.	Validate netlify.toml YAML/TOML syntax; ensure name matches the function filename exactly. Commit fix and redeploy.
Function throws error	Logs show stack trace; possible TypeScript compile issue or runtime exception.	Inspect logs, fix code, commit, and redeploy. For quick rollback, revert the offending commit and trigger a new deploy.
Timeout (26 s default)	Function exceeds synchronous execution limit.	Refactor long-running work into a background function: rename file to scheduled-task-background.ts (max 15 min) and update netlify.toml path accordingly.
Schedule change needed	Cron expression must be updated.	Edit netlify.toml schedule value, commit, and push. Dashboard UI does not support schedule edits.

Limitations and Practical Notes

• Timezone: All schedules run on UTC. Adjust your cron expression to match the desired local time offset.
• Free tier limits: 125,000 invocations per month include scheduled runs. Monitor usage in Netlify Analytics or Team dashboard.
• Timeouts: Synchronous functions max out at 26 seconds. Use background functions (file suffix -background) for longer tasks.
• Local simulation: netlify dev cannot trigger scheduled runs; only manual HTTP invocation works.
• TypeScript config: Netlify’s build environment compiles with tsc. Ensure tsconfig.json sets target: "ES2020" and moduleResolution: "node".
• Schedule updates require deploy: Changing the cron expression in netlify.toml only takes effect after a new successful deploy.

Verification Checklist

• Dashboard Functions page shows correct schedule.
• netlify functions:list outputs the function with schedule.
• Manual invoke returns HTTP 200.
• Logs contain expected timestamp after scheduled run.
• Invocation count increments in Analytics per schedule.