Documentation

Quick Start

Install the SDK, initialize a client, enqueue a job, add a worker handler, and inspect the run.

Try StackShiftRead the overview

Search Docs

Durable Jobs

Quick Start

Live

Install the SDK, initialize a client, enqueue a job, add a worker handler, and inspect the run.

Goal

Run your first Durable Job from TypeScript.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Install the SDK.
  2. 2Create a StackShift client.
  3. 3Enqueue a job with an idempotency key.
  4. 4Register a handler and expose an invocation route.
  5. 5Run the app and observe the job run in StackShift.

Install the SDK

For TypeScript, install the npm package. For Go, install the public GitHub module with go get.

Install dependencies

npm install @stackshift-cloud/jobs

Initialize the client

The API key is the only required credential. It authenticates the request and scopes Durable Jobs internally, so you can use the SDK from any backend, whether or not that backend is deployed on StackShift.

lib/stackshift.ts

import { StackShift } from '@stackshift-cloud/jobs'

export const stackshift = new StackShift({
  apiKey: process.env.STACKSHIFT_API_KEY!,
  baseUrl: process.env.STACKSHIFT_API_URL,
})

Enqueue a job

Use an idempotency key for any job started from an API request, checkout callback, signup flow, or webhook.

app/api/signup/route.ts

import { stackshift } from '@/lib/stackshift'

export async function POST(request: Request) {
  const body = await request.json()

  const run = await stackshift.queue('emails').enqueue(
    'sendVerificationEmail',
    { userId: body.userId, email: body.email },
    {
      idempotencyKey: `verify:${body.userId}`,
      idempotencyTtl: '30d',
      handlerUrl: `${process.env.APP_URL}/api/stackshift/jobs`,
    }
  )

  return Response.json({ runId: run.id, status: run.status })
}

Add a worker handler

jobs.ts

import { stackshift } from '@/lib/stackshift'
import { sendEmail } from '@/lib/email'

stackshift.job<{ userId: string; email: string }>('sendVerificationEmail', async ({ payload, step }) => {
  await step.run('send-email', async () => {
    await sendEmail({
      to: payload.email,
      subject: 'Verify your email',
      template: { name: "verify", userId: payload.userId },
    })

    return { sent: true }
  })

  return { ok: true }
})

app/api/stackshift/jobs/route.ts

import '@/jobs'
import { stackshift } from '@/lib/stackshift'

export async function POST(request: Request) {
  const invocation = await request.json()
  const { status, body } = await stackshift.handleInvocation(invocation)

  return Response.json(body, { status })
}

Run and observe

  • Run your app locally or deploy it to StackShift.
  • Trigger the API route that enqueues the job.
  • Open the Durable Jobs run in StackShift to see status, attempts, logs, payload, and timeline.

Expected result

A job run is queued, invoked, completed, and visible in the Durable Jobs timeline.