Introducing the Inngest TypeScript / JavaScript SDK
Join our Discord
Sign up for free

Writing and running functions

Follow along to learn how to:

  • Create new functions
  • Test and run functions locally
  • Set up an entire test environment for end to end testing

With a few simple commands you'll have a full serverless function running locally. Once you have it set up, you can continue to develop and test your function locally then deploy it when it's finished.

Creating a function

Functions can be created by running inngest init. You'll be asked the following questions:

  1. Function name: This is a human description of the function
    • In this guide, let's use the name "Test func"
  2. How should the function run?: Here, you can specify whether the function is triggered by events or whether it runs via a cron schedule.
    • Choose "Event based", which means each time an event is received this function will run
  3. Event trigger: This is the name of the event that will trigger this function.
    • We're going to use a custom event: "test/event.received" by typing this event name. There are also built-in events for common services (which we're expanding).
  4. Do you want to write a new function or call a URL?: You can invoke an existing serverless function or API, or write new business logic as code.
    • Select "New function" to write some new code.
  5. Which language would you like to use: This lets you use scaffolds for common languages.
    • Let's select Typescript, for now.

After selecting a language the CLI will create a new folder containing your code and config. You can read more about this in the functions documentation.

Creating your function

For now, the CLI has created everything you need to test the function. Your new folder will contain:

  • ./inngest.json, which configures the function,
  • ./steps/, which holds code for each step of your function
  • ./events/, which contains type definitions for the event that triggers this function

Code that you write will go inside of ./steps/. A function starts with a single step, but you can add as many as you like to create complex flows of logic.

Running the function locally

First, run cd to navigate to the function's root directory (cd ./test-func, based off of the function name).

In the function's root directory, run inngest run from the CLI. This will:

  • Inspect the function config, at ./inngest.json.
  • Build your function
  • Parse the function's event definition, then generate mock data for the event's schema
  • Invoke the function with the mock data, showing you the output.

Here's what you should see:

Running your function

It's possible to pass event data via stdin (echo '{}' | inngest run) if you have specific data to test with. You can use a .env file in your folder to pass environment variables and secrets to your code.

That's it! From here, you can make changes to the code within the function's steps and re-run. You can also set up a local event-driven queue via the dev server. When the dev server receives events, it will invoke your functions automatically.

Testing the function via events

Run inngest dev to start the entire local environment. With this single command, your server is up and running, ready to listen for events at http://127.0.0.1:9999.

When you run the dev server, the command will recursively read your current directory to find all functions (defined by inngest.json files). If one or more functions are found, the dev server will accept events on http://127.0.0.1:9999. If not, the dev server will stop. Your application can send events to this dev server to trigger these functions in a production-like manner.

Here's what you should see after running inngest dev:

Inngest dev server running

This environment only persists state in-memory so is not production ready - it's so that you can test your application end-to-end locally. With Inngest, you can set up an entire local environment by running inngest dev.

Once the dev server is running you can test your functions by sending events to your server:

bash
curl -X POST --data '{"name":"test/event.received","data":{"test":true}}' http://127.0.0.1:9999/e/KEY

In production, KEY will be replaced by your own "event key". Here's what happens when the server receives your event:

Inngest dev server executing

The dev server receives the event, inspects which functions are triggered by the event, and automatically runs the steps in each function for full end-to-end testing.

Summary & next steps

That's it! You've created a serverless function triggered by events - a queue without any queues! Admittedly, the function doesn't do anything interesting yet, but that's up to you :)

Next, read about events and functions to dive deeper into how things work.


Additional tips:

  • You need to have Docker installed to build and run functions.
  • If you're on ARM and you're not using Docker for Mac, you should install the binfmt emulators to enable cross-compilation. This is only required for deploys.