SvelteKit

Add Nelkap to a SvelteKit app, from your keys to your first run.

This guide adds Nelkap to a SvelteKit 3 app. 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.

1. Install the SDK

   npm

   npm install @nelkap/sdk
   
2. Add your keys

   Add your project’s API key and secret to .env.local:

   .env.local

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

   Then declare both in src/env.ts, so SvelteKit can give them to your server code:

   src/env.ts

   import { defineEnvVars } from '@sveltejs/kit/env';
   
   export const variables = defineEnvVars({
     NELKAP_API_KEY: {},
     NELKAP_SECRET: {},
   });
   

   Variables are private by default, so they never reach the browser. The API key lets your app start runs and save steps. The secret lets your app check that each call really comes from Nelkap. When you deploy, set the same two variables in your host’s settings. See environment variables in the SvelteKit docs.

3. Write a workflow

   Create src/lib/server/nelkap.ts. Files in a server folder only run on the server, which keeps your keys out of the browser:

   src/lib/server/nelkap.ts

   import {
     NELKAP_API_KEY,
     NELKAP_SECRET,
   } from '$app/env/private';
   import { Nelkap } from '@nelkap/sdk';
   
   import {
     createProfile,
     sendWelcomeEmail,
   } from './activities.js';
   
   export const nelkap = new Nelkap({
     apiKey: NELKAP_API_KEY,
     secret: NELKAP_SECRET,
   });
   
   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 },
   ]);
   

   • The client takes your keys from $app/env/private, where SvelteKit provides them.
   • 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.

4. Add the route

   Create a +server.ts file at the path of your endpoint, and export a POST handler that passes each request to nelkap.handle:

   src/routes/api/nelkap/+server.ts

   import { nelkap } from '#lib/server/nelkap.js';
   
   import type { RequestHandler } from './$types';
   
   export const POST: RequestHandler = ({ request }) =>
     nelkap.handle(request);
   

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

5. Deploy

   Deploy your app with its two environment variables, so Nelkap can reach the route over the internet. Your project’s endpoint must be the route’s exact URL, like https://your-app.com/api/nelkap.

6. Start a run

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

   src/routes/sign-up/+page.server.ts

   import { redirect } from '@sveltejs/kit';
   import { nelkap, onboardUser } from '#lib/server/nelkap.js';
   import { createUser } from '#lib/server/users.js';
   
   import type { Actions } from './$types';
   
   export const actions = {
     default: async ({ request }) => {
       const user = await createUser(await request.formData());
   
       await nelkap.run(onboardUser, user.id);
   
       redirect(303, '/welcome');
     },
   } satisfies Actions;
   

   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.

7. View the 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:

src/routes/api/nelkap/+server.ts

import { waitUntil } from '@vercel/functions';
import { nelkap } from '#lib/server/nelkap.js';

import type { RequestHandler } from './$types';

export const POST: RequestHandler = ({ request }) =>
  nelkap.handle(request, { waitUntil: waitUntil });

The run then goes on for as long as your function may run, which you can raise with the adapter’s maxDuration option. If a call reaches that limit, every step already saved is kept, and Nelkap calls your app again about five minutes later to go on from there.