React Router

This guide adds Nelkap to a React Router app in framework mode, the successor of Remix. By the end, your app will run a workflow that creates a new user’s profile, waits a day, and sends them a welcome email, and you’ll follow each step in your project. You need a Nelkap project with its endpoint, an API key, and its secret. If you don’t have them yet, follow the first three steps of the quickstart.

Install the SDK

npm install @nelkap/sdk

pnpm add @nelkap/sdk

yarn add @nelkap/sdk

Add your keys

Set your project’s API key and secret as environment variables wherever your app’s server runs:

NELKAP_API_KEY=your-api-key
NELKAP_SECRET=your-project-secret

The SDK reads both values from process.env. The API key lets your app start runs and save steps. The secret lets your app check that each call really comes from Nelkap.

Create your client and your first workflow

Create app/nelkap.server.ts. The .server in its name keeps it, and your keys, out of the browser bundle:

app/nelkap.server.ts

import { Nelkap } from '@nelkap/sdk';

import { createProfile, sendWelcomeEmail } from './activities.server';

export const nelkap = new Nelkap();

export async function onboardUser(userId: string) {
  await nelkap.step.run('profile', () => createProfile(userId));

  await nelkap.step.sleep('1 day');

  await nelkap.step.run('welcome', () => sendWelcomeEmail(userId));
}

nelkap.registerWorkflows([{ name: 'onboardUser', handler: onboardUser }]);

onboardUser is your workflow: an async function that takes the run’s payload, here a user ID.
Each step.run saves what its function returns. When the run picks up after the sleep, the profile step gives back its saved result instead of creating the profile again.
step.sleep pauses the run for a day. Nothing runs in your app during that day.
registerWorkflows tells Nelkap which workflows your app runs, as soon as the file is loaded.

Replace createProfile and sendWelcomeEmail with your own functions.

Add the route Nelkap calls

Nelkap sends POST requests, which React Router passes to a route’s action. A route module with an action and no component is a resource route: it answers with what you return instead of rendering a page.Create the route module:

app/routes/api.nelkap.ts

import { nelkap } from '../nelkap.server';
import type { Route } from './+types/api.nelkap';

export async function action({ request }: Route.ActionArgs) {
  return nelkap.handle(request);
}

Then add it to your routes, at the path of your endpoint:

app/routes.ts

import { type RouteConfig, index, route } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),
  route('api/nelkap', 'routes/api.nelkap.ts'),
] satisfies RouteConfig;

handle checks the secret, answers Nelkap at once, and runs the workflow in the background. If your app checks sign-in on every route, leave /api/nelkap out: handle checks Nelkap’s secret instead.

Deploy and set your endpoint

Deploy your app, so Nelkap can reach the route over the internet. Then edit your project and set its endpoint to the route’s URL, like https://your-app.com/api/nelkap.

Start a run

Start the workflow from any server code. Here, the sign-up route’s action starts it once the user is created:

app/routes/sign-up.tsx

import { redirect } from 'react-router';

import { nelkap, onboardUser } from '../nelkap.server';
import { createUser } from '../users.server';
import type { Route } from './+types/sign-up';

export async function action({ request }: Route.ActionArgs) {
  const user = await createUser(await request.formData());

  await nelkap.run(onboardUser, user.id);

  return redirect('/welcome');
}

run returns as soon as Nelkap has the run, so the sign-up doesn’t wait for the workflow. Its second argument, user.id, is the run’s payload: Nelkap passes it to onboardUser.

Follow your run

Open your project’s runs. The new run shows the profile step with what it returned, then sleeps. A day later, Nelkap calls your route again, the welcome email goes out, and the run completes.

Deploy on Vercel

On Vercel, your function can stop as soon as the response is sent. Pass waitUntil from @vercel/functions to keep the run going after handle answers:

app/routes/api.nelkap.ts

import { waitUntil } from '@vercel/functions';

import { nelkap } from '../nelkap.server';
import type { Route } from './+types/api.nelkap';

export async function action({ request }: Route.ActionArgs) {
  return nelkap.handle(request, { waitUntil: waitUntil });
}

The run then goes on for as long as your function may run. If a call reaches that limit, every step already saved is kept, and Nelkap calls your app again five minutes later to go on from there.

Get started

Concepts

Frameworks

Guides

Deploy on Vercel

​Deploy on Vercel

Deploy on Vercel