TypeScript SDK v4

Create the Inngest Client

The Inngest client object is used to configure your application, enabling you to create functions and send events.

import { Inngest } from "inngest";

const inngest = new Inngest({
  id: "my-application",
});

Configuration

  • Name
    id
    Type
    string
    Required
    required
    Description

    A unique identifier for your application. We recommend a hyphenated slug.

  • Name
    baseUrl
    Type
    string
    Required
    optional
    Description

    Override the default (https://inn.gs/) base URL for sending events. See also the INNGEST_BASE_URL environment variable.

  • Name
    env
    Type
    string
    Required
    optional
    Description

    The environment name. Required only when using Branch Environments.

  • Name
    eventKey
    Type
    string
    Required
    optional
    Description

    An Inngest Event Key. Alternatively, set the INNGEST_EVENT_KEY environment variable.

  • Name
    fetch
    Type
    Fetch API compatible interface
    Required
    optional
    Description

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

    If you need to specify this, make sure that you preserve the function's binding, either by using .bind or by wrapping it in an anonymous function.

  • Name
    signingKey
    Type
    string
    Required
    optional
    Description

    The signing key used to authenticate with Inngest Cloud. We recommend setting this via the INNGEST_SIGNING_KEY environment variable instead.

  • Name
    signingKeyFallback
    Type
    string
    Required
    optional
    Description

    A fallback signing key, useful during key rotation. We recommend setting this via the INNGEST_SIGNING_KEY_FALLBACK environment variable instead.

  • Name
    isDev
    Type
    boolean
    Required
    optional
    Description

    Set to true to force Dev mode, setting default local URLs and turning off signature verification, or force Cloud mode with false. Alternatively, set INNGEST_DEV.

  • Name
    logger
    Type
    Logger
    Required
    optional
    Description

    A logger object that provides .info(), .warn(), .error(), and .debug() methods. The SDK uses Pino-style object-first logging. For string-first loggers like Winston, use wrapStringFirstLogger. Defaults to new ConsoleLogger({ level: "info" }) if not provided. See the logging reference for details.

    import { ConsoleLogger, Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-app",
  logger: new ConsoleLogger({ level: "debug" }),
});
  • Name
    internalLogger
    Type
    Logger
    Required
    optional
    Description

    A separate logger for SDK internal messages (registration, request handling, middleware errors). If not provided, falls back to logger. Use this to route SDK internals separately from your function logs. See the logging reference for details.

  • Name
    middleware
    Type
    array
    Required
    optional
    Description

    A stack of middleware to add to the client.

We recommend setting the INNGEST_EVENT_KEY as an environment variable over using the eventKey option. As with any secret, it's not a good practice to hard-code the event key in your codebase.

Defining Event Payload Types

You can use eventType() to define event payload types using TypeScript, Zod, Valibot, or any schema library that implements the Standard Schema interface.

Event types defined with eventType() are fully typed when used with inngest.send() and inngest.createFunction(). This can more easily alert you to issues with your code during compile time. See the trigger helpers reference for full documentation on eventType() and related functions.

import { eventType, Inngest } from "inngest";
import { z } from "zod";

const accountCreated = eventType("app/account.created", {
  schema: z.object({
    userId: z.string(),
  }),
});

const subscriptionStarted = eventType("app/subscription.started", {
  schema: z.object({
    userId: z.string(),
    planId: z.string(),
  }),
});

export const inngest = new Inngest({ id: "my-app" });

Reusing event types

You can use the GetEvents<> generic to access the final event types from an Inngest client.

It's recommended to use this instead of directly reusing your event types, as Inngest will add extra properties and internal events such as ts and inngest/function.failed.

import { eventType, Inngest, type GetEvents } from "inngest";
import { z } from "zod";

const userCreated = eventType("app/user.created", {
  schema: z.object({ userId: z.string() }),
});

export const inngest = new Inngest({ id: "my-app" });

type Events = GetEvents<typeof inngest>;
type AppUserCreated = Events["app/user.created"];

For more information on this and other TypeScript helpers, see TypeScript - Helpers.

Cloud Mode and Dev Mode

An SDK can run in two separate "modes:" Cloud or Dev.

  • Cloud Mode
    • 🔒 Signature verification ON
    • Defaults to communicating with Inngest Cloud (e.g. https://api.inngest.com)
  • Dev Mode
    • ❌ Signature verification OFF
    • Defaults to communicating with an Inngest Dev Server (e.g. http://localhost:8288)

You can force either Dev or Cloud Mode by setting INNGEST_DEV or the isDev option.

If no mode is explicitly set, the SDK will default to cloud mode to ensure that Inngest applications are more secure by default. You can use INNGEST_DEV or isDev=true to let the SDK know that you are intentionally using development mode.

Best Practices

Share your client across your codebase

Instantiating the Inngest client in a single file and sharing it across your codebase is ideal as you only need a single place to configure your client and define types which can be leveraged anywhere you send events or create functions.

./inngest/client.ts

import { Inngest } from "inngest";

export const inngest = new Inngest({ id: "my-app" });

./inngest/myFunction.ts

import { inngest } from "./client";

export default inngest.createFunction(...);

Handling multiple environments with middleware

If your client uses middleware, that middleware may import dependencies that are not supported across multiple environments such as "Edge" and "Serverless" (commonly with either access to WebAPIs or Node).

In this case, we'd recommend creating a separate client for each environment, ensuring Node-compatible middleware is only used in Node-compatible environments and vice versa.

This need is common in places where function execution should declare more involved middleware, while sending events from the edge often requires much less.

./inngest/client.ts

// inngest/client.ts
import { Inngest } from "inngest";
import { nodeMiddleware } from "some-node-middleware";

export const inngest = new Inngest({
  id: "my-app",
  middleware: [nodeMiddleware],
});

// inngest/edgeClient.ts
import { Inngest } from "inngest";

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

Also see Referencing functions, which can help you invoke functions across these environments without pulling in any dependencies.