inngest-setup-redwoodjs

Setup up Inngest in a RedwoodJS project and to create new functions via command line.

The plugin command configures Inngest and auto-instruments the RedwoodJS GraphQL api using the envelop-plugin-inngest plugin.

The function command creates stubbed out background, delayed, scheduled and step functions ready for you to implement.

Installation

Add the inngest-setup-redwoodjs package to your RedwoodJS project's package.json as a development dependency:

yarn add -D inngest-setup-redwoodjs

For example:

  // package.json
  "devDependencies": {
    ...
    "inngest-setup-redwoodjs": "latest"
  },

Note: If you use RedwoodJS v5.0.6-canary or later, you can setup Inngest via yarn rw experimental setup-inngest.

Usage

yarn inngest-setup-redwoodjs plugin
yarn inngest-setup-redwoodjs function <name> -t <type> [--graphql]

Run the above commands inside your RedwoodJS project.

Note: only name is required. This will become the name of your function.

If type is not provided, you will be prompted to pick from the support function types.

If set --graphql then you will be prompted to pick from available queries and mutations in your web app. You then will be prompted to pick a function type. Note that you cannon created scheduled (aka cron) functions for graphql events,

Plugin Command

yarn inngest-setup-redwoodjs plugin

Set up Inngest plugin

Options:
      --help     Show help                                             [boolean]
      --version  Show version number                                   [boolean]
      --cwd      Working directory to use (where `redwood.toml` is located)
                                                                        [string]
  -f, --force    Overwrite existing files             [boolean] [default: false]

The plugin command will configure a RedwoodJS project to use Inngest and auto-instrument the GraphQL API.

• installs required Inngest packages
• sets up all needed inngest files
• creates the plugin for RedwoodJS GraphQLHandler
• runs a codemod to transform the GraphQLHandler to use the Inngest plugin

Tests for codemod and included.

See: envelop-plugin-inngest README for more information about the plugin.

Files Added by Plugin Setup

After running the plugin command, the following files are setup in your RedwoodJS project api side:

- api
 +-- src
  +-- functions
      +- graphql.ts         // Modified GraphQLHandler to use Inngest plugin to instrument GraphQL api
      +- inngest.ts         // Inngest endpoint to serve functions
  +-- jobs                  // Jobs
    +-- inngest             // Directory where Inngest functions are stored
        +- helloWorld.ts    // Example background function
  +-- lib
      +- inngest.ts         // Inngest client. Use this if you need to send custom events in services or functions.
  +-- plugins
        +- useInngest.ts    // GraphQL Yoga plugin that auto-instruments GraphQL api

Also, your project's package.json file is modified to add a scrip that can launch the Inngest dev server quickly:

  "scripts": {
    "inngest:dev": "npx inngest-cli@latest dev -u http://localhost:8911/inngest",
  }

Next Steps

1. Update INNGEST_APP_NAME and eventKey custom to your application

// api/src/lib/inngest.ts

export const inngest = new Inngest({
  name: INNGEST_APP_NAME,
  eventKey: 'YOUR_INNGEST_EVENT_KEY',
})

“Event Keys” are unique keys that allow applications to send (aka publish) events to Inngest.

If the eventKey is not provided, Inngest will look for and use the INNGEST_EVENT_KEY environment variable.

During local development, you can use a dummy value for your INNGEST_EVENT_KEY environment variable. The dev server does not validate keys locally.

For more information, see Creating an event key in the Inngest documentation.

What if I don't want to auto-instrument my GraphQL API

While we highly agree with the philosophy to "instrument everything" by sending events for each GraphQL execution result to Inngest (aka auto-instrument) to effortlessly build event-driven applications, you may not want to.

You have a few options:

• Filter the operations sent. See Control What Events Sent by denying particular operation, or entire types.
• Remove the plugin from the GraphQLHandler's extraPlugin.

export const handler = createGraphQLHandler({
  getCurrentUser,
  loggerConfig: { logger, options: {} },
  directives,
  sdls,
  services,
  extraPlugins: [inngestPlugin], // <-- remove

  onException: () => {
    // Disconnect from your database with an unhandled exception.
    db.$disconnect()
  }
})

Function Command

yarn inngest-setup-redwoodjs function <name> -t <type> [--graphql]

Set up an Inngest function

Positionals:
  name  Name of the function to setup                        [string] [required]

Options:
      --help       Show help                                           [boolean]
      --version    Show version number                                 [boolean]
      --cwd        Working directory to use (where `redwood.toml` is located)
                                                                        [string]
      --eventName  Name of the event to trigger the function. Defaults to the
                   function name.                                       [string]
      --graphql    Build event name from your web side GraphQL operations
                                                      [boolean] [default: false]
  -t, --type       Type of Inngest function to setup
                [string] [choices: "background", "scheduled", "delayed", "step"]
  -f, --force      Overwrite existing files           [boolean] [default: false]

The function command will create a new ready to implement function file for the provided function type.

Supported types are:

• background
• delayed
• scheduled
• step
• fan-out

Note: if you omit the type argument, you will be prompted to pick a supported function type.

See Writing Functions in the Inngest documentation for more info.

Important: In order to use Inngest functions, the plugin command should be run first to configure and setup your RedwoodJS app to use Inngest.

Inngest SDK Dashboard

To launch the SDK Dashboard, visit:

http://localhost:8910/.redwood/functions/inngest

Here, you can see which functions have be been found and registered.

Inngest Dev Server

To launch the Inngest dev server, from a new terminal run:

npx inngest-cli@latest dev -u http://localhost:8910/.redwood/functions/inngest

There will be instructions for the url to visit to view the dev server UI.

For example:

Inngest dev server online at 0.0.0.0:8288, visible at the following URLs:

  - http://127.0.0.1:8288 (http://localhost:8288)
  - http://192.168.7.158:8288

Important: Please be sure to start your RedwoodJS Dev Server as well; preferably before launching the Inngest Dev server. If not, you may see some connection warnings until both servers are up, such as:

12:29PM ERR devserver > unable to connect to the SDK error="Put \"http://localhost:8911/inngest\": dial tcp [::1]:8911: connect: connection refused" url=http://localhost:8911/inngest

Note: The endpoint needs to match the servePath (e.g., '/inngest') defined in api/src/functions/inngest.ts.

Inngest Signing Key

In Production, an INNGEST_SIGNING_KEY is required to securely communicate with the Inngest platform, either via environment variable (recommend) or it can be passed explicitly through the options argument.

It signs requests to and from Inngest in order to prove that the source is legitimate.

In local development, a INNGEST_SIGNING_KEY isn't needed; however, when the Inngest Dev Server starts, you may see an warning message:

You're missing the INNGEST_SIGNING_KEY parameter when serving your functions.

You must provide a signing key to communicate securely with Inngest when sending non-development events. If your key is not provided here, we'll try to retrieve it from the INNGEST_SIGNING_KEY environment variable.

You can retrieve your signing key from the Inngest UI inside the "Secrets" section at {@link https://app.inngest.com/env/production/manage/signing-key}. We highly recommend that you add this to your platform's available environment variables as INNGEST_SIGNING_KEY.

When in Production, if no key can be found, you will not be able to register your functions or receive events from Inngest.

Tip!

The plugin command adds a script to your package.json to make to easier to launch the Inngest Dev Server.

Simply run:

yarn inngest:dev

Or, you can add manually by adding this script to your application's package.json like

  "scripts": {
    "inngest:dev": "npx inngest-cli@latest dev -u http://localhost:8911/inngest"
  }

Important

Currently these commands only work for RedwoodJS projects with TypeScript.

Releasing

It's made to be released by npm (e.g. npm run release:patch). That way I don't have to worry about yarn v1 vs v3