Create Function

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

import { inngest } from "./client";

export default inngest.createFunction(
  { id: "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
    id
    Type
    string
    Required
    required
    Description

    A unique identifier for your function. This should not change between deploys.

  • Name
    name
    Type
    string
    Required
    optional
    Description

    A name for your function. If defined, this will be shown in the UI as a friendly display name instead of the ID.

  • Name
    concurrency
    Type
    number | object | [object, object]
    Required
    optional
    Description

    Limit the number of concurrently running functions (reference)

  • Name
    idempotency
    Type
    string
    Required
    optional
    Description

    A key expression which is used to prevent duplicate events from triggering a function more than once in 24 hours. This is equivalent to setting rateLimit with a key, a limit of 1 and period of 24hr.

    Expressions are defined using the Common Expression Language (CEL) with the original event accessible using dot-notation. Examples:

    • Only run once for each customer id: 'event.data.customer_id'
    • Only run once for each account and email address: 'event.data.account_id + "-" + event.user.email'
  • Name
    rateLimit
    Type
    object
    Required
    optional
    Description

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

  • Name
    debounce
    Type
    object
    Required
    optional
    Description

    Options to configure function debounce (reference)

  • Name
    priority
    Type
    object
    Required
    optional
    Description

    Options to configure how to prioritize functions

  • Name
    batchEvents
    Type
    object
    Required
    optional
    Description

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

  • 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)

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.

When using an event trigger, you can optionally combine it with the if option to filter events:

Additional options
  • Name
    if
    Type
    string
    Required
    optional
    Description

    A comparison expression that returns true or false whether the function should handle or ignore a given matching event.

    Expressions are defined using the Common Expression Language (CEL) with the original event accessible using dot-notation. Examples:

    • 'event.data.action == "published"'
    • 'event.data.priority >= 4'

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.