Quick start

This guide will run through setting up your local development version of Inngest's event-driven queue. By the end of this guide, you'll have a working devlepment server which runs functions in response to custom events. It'll only take a couple of minutes.

We'll run through:

• Installing the CLI
• Creating functions, via inngest init
• Testing functions, via inngest run
• Running the server locally, via inngest dev
• Detail on the development lifecycle.

Prerequisites

• In order to build and run functions, docker must be installed. It's easy to get started.
• We use buildx to build your images locally, so use a recent version of Docker.

1. Install the CLI

You can install the CLI by running the following script:

curl -sfL https://cli.inngest.com/install.sh | sh

This will place inngest in your $PWD. Move it into your $PATH to invoke: sudo mv ./inngest /usr/local/bin/inngest.

You can also download prebuilt binaries from Github or build from source, with Go 1.18+ installed.

2. Creating a new function

In order to use the event-driven queue, you'll need functions which are executed - otherwise, the queue does nothing. 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.

For now, the CLI has created everything you need to test the function.

3. Testing the new function

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:

It's possible to pass event data via stdin (echo '{}' | inngest run), if you have test data. Any current ENV variables are passed to your function; secrets are passed as env vars and are fully usable in 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.

4. Run the dev server locally

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:

This environment only persists state in-memory, so is not production ready.

5. Sending events to invoke the function

It's important 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 "source key". Here's what happens when the server receives your event:

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:

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