Setup Inngest in RedwoodJS
npm install inngest-setup-redwoodjsSetup 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 theenvelop-plugin-inngest plugin.
The function command creates stubbed out background, delayed, scheduled and step functions ready
for you to implement.
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.
`
yarn inngest-setup-redwoodjs plugin
yarn inngest-setup-redwoodjs function
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,
`
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.
After running the plugin command, the following files are setup in your RedwoodJS project api
side:
`terminal`
- 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:
`json file="package.json"`
"scripts": {
"inngest:dev": "npx inngest-cli@latest dev -u http://localhost:8911/inngest",
}
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.
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.
`ts
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()
}
})
`
`
yarn inngest-setup-redwoodjs function
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.
To launch the SDK Dashboard, visit:
`
http://localhost:8910/.redwood/functions/inngest
Here, you can see which functions have be been found and registered.
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 inapi/src/functions/inngest.ts.
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.
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"
}
Currently these commands only work for RedwoodJS projects with TypeScript.
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