---
title: "nuxt-backend/workflows"
description: "Every export of nuxt-backend/workflows, with its signature and where it is defined."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/workflows"
---
# nuxt-backend/workflows

## Interfaces

### WorkflowComponents

Defined in: [src/convex/integrations/workflows.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts)

The component handle `setupWorkflows` reads from your generated `components`
object (the key is picked structurally — pass the whole object).

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="workflow">
        
      </a>
      
       <code>
        workflow
      </code>
    </td>
    
    <td>
      <code>
        WorkflowComponent
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts" rel="nofollow">
        src/convex/integrations/workflows.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### EmailSequenceStep

Defined in: [src/convex/integrations/workflows.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts)

One email in an [defineEmailSequence](#defineemailsequence) drip.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="type-parameter-data">
        
      </a>
      
       <code>
        Data
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="after">
        
      </a>
      
       <code>
        after
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Delay before this step, in milliseconds from the previous one.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts" rel="nofollow">
        src/convex/integrations/workflows.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="email">
        
      </a>
      
       <code>
        email
      </code>
    </td>
    
    <td>
      (<code>
        data
      </code>
      
      ) => | { <code>
        to
      </code>
      
      : <code>
        string
      </code>
      
      ; <code>
        subject
      </code>
      
      : <code>
        string
      </code>
      
      ; <code>
        html?
      </code>
      
      : <code>
        string
      </code>
      
      ; <code>
        text?
      </code>
      
      : <code>
        string
      </code>
      
      ; } | <code>
        null
      </code>
    </td>
    
    <td>
      Build the email for this step — or return <code>
        null
      </code>
      
       to skip it (e.g. the user already activated and the nudge is moot).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts" rel="nofollow">
        src/convex/integrations/workflows.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Type Aliases

### WorkflowStatus

```ts
type WorkflowStatus = 
  | {
  type: "inProgress";
  running: IdsToStrings<Step>[];
}
  | {
  type: "completed";
  result: unknown;
}
  | {
  type: "canceled";
}
  | {
  type: "failed";
  error: string;
};
```

Defined in: node_modules/@convex-dev/workflow/dist/client/index.d.ts:51

Re-exported so consumers can type a `status` query's `workflowId` arg and
cast a stored id back to a [WorkflowId](#workflowid) (it is a branded string).

---

### WorkflowId

```ts
type WorkflowId = string & {
  __isWorkflowId: true;
};
```

Defined in: node_modules/@convex-dev/workflow/dist/types.d.ts:4

Re-exported so consumers can type a `status` query's `workflowId` arg and
cast a stored id back to a [WorkflowId](#workflowid) (it is a branded string).

#### Type Declaration

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        __isWorkflowId
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      node_modules/@convex-dev/workflow/dist/types.d.ts:5
    </td>
  </tr>
</tbody>
</table>

## Functions

### setupWorkflows()

```ts
function setupWorkflows(components, options?): WorkflowManager;
```

Defined in: [src/convex/integrations/workflows.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts)

Configure the [Workflow](https://www.convex.dev/components/workflow)
component for durable, long-running, multi-step functions. Your overrides are
merged onto the package defaults (`DEFAULT_WORKPOOL_OPTIONS`: bounded
parallelism, exponential-backoff retries).

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        components
      </code>
    </td>
    
    <td>
      <a href="#workflowcomponents">
        <code>
          WorkflowComponents
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      { <code>
        workpoolOptions?
      </code>
      
      : <code>
        WorkpoolOptions
      </code>
      
      ; }
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.workpoolOptions?
      </code>
    </td>
    
    <td>
      <code>
        WorkpoolOptions
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Returns

`WorkflowManager`

#### Example

```ts
import { setupWorkflows } from 'nuxt-backend/workflows'
import { components } from './_generated/api'

export const workflow = setupWorkflows(components)

export const exportReady = workflow.define({
  args: { email: v.string(), url: v.string() },
  handler: async (step, { email, url }) => {
    // Email is sent through the `backend` component's email module.
    await step.runMutation(components.backend.email.send, {
      to: email,
      subject: 'Your export is ready',
      text: `Download it here: ${url}`,
    })
  },
})
```

---

### defineEmailSequence()

```ts
function defineEmailSequence<Args>(
   workflow, 
   components, 
   options
): RegisteredMutation<"internal", WorkflowArgs<Args>, WorkflowMutationResult<unknown>>;
```

Defined in: [src/convex/integrations/workflows.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/workflows.ts)

A durable, multi-step email sequence (onboarding drips, cancellation
follow-ups): each step sleeps its `after` delay durably (survives restarts
and deploys via the workflow component), then sends through the backend
component's email module — delivery-tracked like every other transactional
email. Cancel a started sequence with the workflow manager's own
`workflow.cancel(ctx, id)`.

A sequence started with a `userId` follows the account: before each email
it reads the user, ends the sequence when the account is gone (deleted
since sign-up), and hands the step the account's current `email` and
`name` in place of the ones captured when it started.

#### Type Parameters

<table>
<thead>
  <tr>
    <th>
      Type Parameter
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="type-parameter-args">
        
      </a>
      
       <code>
        Args
      </code>
      
       <em>
        extends
      </em>
      
       <code>
        PropertyValidators
      </code>
    </td>
  </tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        workflow
      </code>
    </td>
    
    <td>
      <code>
        WorkflowManager
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        components
      </code>
    </td>
    
    <td>
      <code>
        SequenceEmailComponents
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      { <code>
        args
      </code>
      
      : <code>
        Args
      </code>
      
      ; <code>
        steps
      </code>
      
      : <a href="#emailsequencestep">
        <code>
          EmailSequenceStep
        </code>
      </a>
      
      <<code>
        ObjectType
      </code>
      
      <<code>
        Args
      </code>
      
      >><span>
        
      </span>
      
      ; }
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.args
      </code>
    </td>
    
    <td>
      <code>
        Args
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.steps
      </code>
    </td>
    
    <td>
      <a href="#emailsequencestep">
        <code>
          EmailSequenceStep
        </code>
      </a>
      
      <<code>
        ObjectType
      </code>
      
      <<code>
        Args
      </code>
      
      >><span>
        
      </span>
    </td>
  </tr>
</tbody>
</table>

#### Returns

`RegisteredMutation`<`"internal"`, `WorkflowArgs`<`Args`>, `WorkflowMutationResult`<`unknown`>>

#### Example

```ts
// backend/workflows.ts
export const onboardingSequence = defineEmailSequence(workflow, components, {
  args: { email: v.string(), name: v.string() },
  steps: [
    { after: 24 * 60 * 60 * 1000, email: ({ email, name }) => ({ to: email, subject: `Your first day, ${name}`, text: '…' }) },
    { after: 3 * 24 * 60 * 60 * 1000, email: ({ email }) => ({ to: email, subject: 'Getting the most out of it', text: '…' }) },
  ],
})
// started from auth's onUserCreated:
//   await workflow.start(ctx, internal.workflows.onboardingSequence, { email, name })
```


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.