Create Function

Define your functions using the createFunction method on the Inngest client.

import { inngest } from "./client";

export default inngest.createFunction(
  { name: "Import product images" },
  { event: "shop/product.imported" },
  async ({ event, step, runId }) => {
    // Your function code
  }
);

inngest.createFunction(configuration, trigger, handler): InngestFunction

The createFunction method accepts a series of arguments to define your function.

Configuration

  • Name
    name
    Type
    string
    Required
    required
    Description

    A unique name for your function. This will be used to create a unique slug id by default.

  • Name
    id
    Type
    string
    Required
    optional
    Description

    A unique identifier for your function to override the default (a slug of your function name).

  • Name
    concurrency
    Type
    number | object
    Required
    optional
    Description

    Limit the number of concurrently running functions (reference)

  • Name
    rateLimit
    Type
    object
    Required
    optional
    Description

    Options to configure how to rate limit function execution (reference)

  • Name
    batchEvents
    Type
    object
    Required
    optional
    Description

    Configure how the function should consume batches of events (reference)

    Properties
    • Name
      maxSize
      Type
      number
      Required
      required
      Description

      The maximum number of events a batch can have. Current limit is 100.

    • Name
      timeout
      Type
      string
      Required
      required
      Description

      How long to wait before invoking the function with the batch even if it's not full. Current permitted values are from 1s to 60s.

  • Name
    retries
    Type
    number
    Required
    optional
    Description

    Configure the number of times the function will be retried from 0 to 20. Default: 3

  • Name
    onFailure
    Type
    function
    Required
    optional
    Description

    A function that will be called only when this Inngest function fails after all retries have been attempted (reference)

  • Name
    cancelOn
    Type
    object
    Required
    optional
    Description

    Define an event that can be used to cancel a running or sleeping function (reference)

    Properties
    • Name
      event
      Type
      string
      Required
      required
      Description

      The event name which will be used to cancel

    • Name
      match
      Type
      string
      Required
      optional
      Description

      The property to match the event trigger and the cancelling event, using dot-notation, e.g. data.userId

    • Name
      timeout
      Type
      string
      Required
      optional
      Description

      The amount of time to wait to receive the cancelling event. A time string compatible with the ms package, e.g. "30m", "3 hours", or "2.5d"

Trigger

One of the following function triggers is Required.

  • Name
    event
    Type
    string
    Required
    optional
    Description

    The name of the event that will trigger this event to run

  • Name
    cron
    Type
    string
    Required
    optional
    Description

    A unix-cron compatible schedule string.
    Optional timezone prefix, e.g. TZ=Europe/Paris 0 12 * * 5.

Handler

The handler is your code that runs whenever the trigger occurs. Every function handler receives a single object argument which can be deconstructed. The key arguments are event and step. Note, that scheduled functions that use a cron trigger will not receive an event argument.

function handler({ event, events, step, runId, logger, attempt }) {/* ... */}

event

The event payload object that triggered the given function run. The event payload object will match what you send with inngest.send(). Below is an example event payload object:

{
  name: "app/account.created",
  data: {
    userId: "1234567890"
  },
  v: "2023-05-12.1",
  ts: 1683898268584
}

events
v2.2.0+

events is an array of event payload objects that's accessible when the batchEvents is set on the function configuration. If batching is not configured, the array contains a single event payload matching the event argument.

step

The step object has methods that enable you to define

  • step.run() - Run synchronous or asynchronous code as a retryable step in your function
  • step.sleep() - Sleep for a given amount of time
  • step.sleepUntil() - Sleep until a given time
  • step.waitForEvent() - Pause a function's execution until another event is received
  • step.sendEvent() - Send event(s) reliability within your function. Use this instead of inngest.send() to ensure reliable event delivery from within functions.

runId

The unique ID for the given function run. This can be useful for logging and looking up specific function runs in the Inngest dashboard.

logger
v2.0.0+

The logger object exposes the following interfaces.

export interface Logger {
  info(...args: any[]): void;
  warn(...args: any[]): void;
  error(...args: any[]): void;
  debug(...args: any[]): void;
}

It is a proxy object that is either backed by console or the logger you provided (reference).

attempt
v2.5.0+

The current zero-indexed attempt number for this function execution. The first attempt will be 0, the second 1, and so on. The attempt number is incremented every time the function throws an error and is retried.