Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Run your first Durable Job from TypeScript.

​
Prerequisites

  • Node.js 18 or newer
  • A StackShift API key

​
Workflow

1
Install the SDK.
2
Create a StackShift client.
3
Enqueue a job with an idempotency key.
4
Register a handler and expose an invocation route.
5
Run 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. 
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. 
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. 
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

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 }
})

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.

Using Queues

Use queues for background execution, retry policy, delayed jobs, and concurrency control.

Observability

Inspect each job run through status, attempts, logs, payload, result, errors, and timeline.