Serve

The serve() API handler is used to serve your application's functions via HTTP. This handler enables Inngest to remotely and securely read your functions' configuration and invoke your function code. This enables you to host your function code on any platform.

import { serve } from "inngest/next"; // or your preferred framework
import { inngest } from "./client";
import {
  importProductImages,
  sendSignupEmail,
  summarizeText,
} from "./functions";

serve({
  client: inngest,
  functions: [sendSignupEmail, summarizeText, importProductImages],
});

serve handlers are imported from convenient framework-specific packages like "inngest/next", "inngest/express", or "inngest/lambda". Click here for a full list of officially supported frameworks. For any framework that is not support, you can create a custom handler.

serve(options)

  • Name
    client
    Type
    Inngest client
    Required
    required
    Description

    An Inngest client (reference).

  • Name
    functions
    Type
    InngestFunctions[]
    Required
    required
    Description

    An array of Inngest functions defined using inngest.createFunction() (reference).

  • Name
    signingKey
    Type
    string
    Required
    required
    Description

    The Inngest Signing Key for your selected environment. We recommend setting the INNGEST_SIGNING_KEY environment variable instead of passing the signingKey option. You can find this in the Inngest dashboard.

  • Name
    serveHost
    Type
    string
    Required
    optional
    Description

    The domain host of your application, including protocol, e.g. https://myapp.com. The SDK attempts to infer this via HTTP headers at runtime, but this may be required when using platforms like AWS Lambda or when using a reverse proxy. See also INNGEST_SERVE_HOST.

  • Name
    servePath
    Type
    string
    Required
    optional
    Description

    The path where your serve handler is hosted. The SDK attempts to infer this via HTTP headers at runtime. We recommend /api/inngest. See also INNGEST_SERVE_PATH.

  • Name
    streaming
    Type
    "allow" | "force" | false
    Required
    optional
    Description

    Enables streaming responses back to Inngest which can enable maximum serverless function timeouts. See reference for more information on the configuration. See also INNGEST_SERVE_HOST.

  • Name
    logLevel
    Type
    "fatal" | "error" | "warn" | "info" | "debug" | "silent"
    Required
    optional
    Description

    The minimum level to log from the Inngest serve endpoint. Defaults to "info". See also INNGEST_LOG_LEVEL.

  • Name
    baseUrl
    Type
    string
    Required
    optional
    Description

    The URL used to communicate with Inngest. This can be useful in testing environments when using the Inngest Dev Server. Defaults to: "https://api.inngest.com/". See also INNGEST_BASE_URL.

  • Name
    fetch
    Type
    Fetch API compatible interface
    Required
    optional
    Description

    Override the default fetch implementation. Defaults to the runtime's native Fetch API.

  • Name
    id
    Type
    string
    Required
    optional
    Description

    The ID to use to represent this application instead of the client's ID. Useful for creating many Inngest endpoints in a single application.

We always recommend setting the INNGEST_SIGNING_KEY over using the signingKey option. As with any secret, it's not a good practice to hard-code the signing key in your codebase.

How the serve API handler works

The API works by exposing a single endpoint at /api/inngest which handles different actions utilizing HTTP request methods:

  • GET: Return function metadata and render a debug page in in development only. See landingPage.
  • POST: Invoke functions with the request body as incoming function state.
  • PUT: Trigger the SDK to register all functions with Inngest using the signing key.

Custom frameworks

If the framework that your application uses is not included in our list of first-party supported frameworks, you can create a custom serve handler.

To create your own handler, check out the example handler in our SDK's open source repository to understand how it works. Here's an example of a custom handler being created and used:

import { Inngest, InngestCommHandler, type ServeHandlerOptions } from "inngest";

const serve = (options: ServeHandlerOptions) => {
  const handler = new InngestCommHandler({
    frameworkName: "edge",
    fetch: fetch.bind(globalThis),
    ...options,
    handler: (req: Request) => {
      return {
        body: () => req.json(),
        headers: (key) => req.headers.get(key),
        method: () => req.method,
        url: () => new URL(req.url, `https://${req.headers.get("host") || ""}`),
        transformResponse: ({ body, status, headers }) => {
          return new Response(body, { status, headers });
        },
      };
    },
  });

  return handler.createHandler();
};

const inngest = new Inngest({ id: "example-edge-app" });

const fn = inngest.createFunction(
  { id: "hello-world" },
  { event: "test/hello.world" },
  () => "Hello, World!"
);

export default serve({ client: inngest, functions: [fn] });