> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# Nitro

> Install and configure Workflow DevKit in your Nitro application

This guide shows you how to install Workflow DevKit in a Nitro project.

<Steps>
  <Step title="Install dependencies">
    Install the `workflow` package:

    <CodeGroup>
      ```bash npm theme={null}
      npm install workflow
      ```

      ```bash yarn theme={null}
      yarn add workflow
      ```

      ```bash pnpm theme={null}
      pnpm add workflow
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure Nitro">
    Add the Workflow module to your Nitro config:

    ```typescript nitro.config.ts theme={null}
    import { defineConfig } from 'nitro';

    export default defineConfig({
      modules: ['workflow/nitro'],
      serverDir: './server',
    });
    ```

    The Workflow module automatically:

    * Adds the Rollup transform plugin to process workflow directives
    * Builds workflow bundles during development and production
    * Generates route handlers at `.well-known/workflow/v1/*`
    * Supports hot module replacement in development

    ### Configuration Options

    You can configure the TypeScript plugin:

    ```typescript nitro.config.ts theme={null}
    export default defineConfig({
      modules: ['workflow/nitro'],
      workflow: {
        typescriptPlugin: true,  // Enable TypeScript IntelliSense
      },
    });
    ```
  </Step>

  <Step title="Enable TypeScript support (Optional)">
    The TypeScript plugin can be enabled via Nitro config (shown above) or directly in `tsconfig.json`:

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "workflow"
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## How it works

The Nitro integration:

* **Transform plugin**: Uses `@workflow/rollup` to transform workflow and step functions
* **Build hooks**: Builds workflows during `build:before` and supports HMR via `dev:reload`
* **Route generation**: Creates virtual handlers for workflow endpoints:
  * `/.well-known/workflow/v1/webhook/:token` - Webhook handling
  * `/.well-known/workflow/v1/step` - Step execution
  * `/.well-known/workflow/v1/flow` - Workflow execution
  * `/.well-known/workflow/v1/manifest.json` - Manifest (when `WORKFLOW_PUBLIC_MANIFEST=1`)
* **Vercel integration**: Automatically generates Vercel functions when deploying with `preset: 'vercel'`
* **Externalization**: Excludes generated workflow bundles from dev reloads for better performance

## Example workflow

```typescript server/workflows/order-processing.ts theme={null}
import { sleep } from "workflow";

export async function processOrder(orderId: string) {
  "use workflow";

  const order = await fetchOrder(orderId);
  await validatePayment(order);
  await sleep("5m");
  await shipOrder(order);

  return { orderId, status: "shipped" };
}

async function fetchOrder(orderId: string) {
  "use step";
  console.log(`Fetching order ${orderId}`);
  return { id: orderId, amount: 99.99 };
}

async function validatePayment(order: { id: string; amount: number }) {
  "use step";
  console.log(`Validating payment for order ${order.id}`);
}

async function shipOrder(order: { id: string; amount: number }) {
  "use step";
  console.log(`Shipping order ${order.id}`);
}
```

## Triggering workflows

Start workflows from API routes:

```typescript server/api/orders.post.ts theme={null}
import { start } from 'workflow/api';
import { defineEventHandler } from 'h3';
import { processOrder } from '../workflows/order-processing';

export default defineEventHandler(async (event) => {
  const { orderId } = await readBody(event);
  await start(processOrder, [orderId]);
  return { message: "Order processing started" };
});
```

## Development

Run the development server:

```bash theme={null}
nitro dev
```

The Workflow module will:

* Build workflows on startup
* Watch for changes and rebuild automatically
* Provide HMR for workflow files

## Production

Build for production:

```bash theme={null}
nitro build
```

For Vercel deployment, the module automatically:

* Generates Vercel function configurations
* Sets up queue triggers for workflow execution
* Configures retry policies

## Advanced usage

### Exposing the manifest

Set the `WORKFLOW_PUBLIC_MANIFEST` environment variable to expose the workflow manifest:

```bash theme={null}
WORKFLOW_PUBLIC_MANIFEST=1 nitro dev
```

The manifest will be available at `/.well-known/workflow/v1/manifest.json`.

### Using with other frameworks

The Nitro integration is used internally by:

* **Express**: Via custom routes configuration
* **Fastify**: Via custom routes configuration
* **Hono**: Via custom routes configuration
* **Nuxt**: Via the Nuxt module which wraps Nitro

## Next steps

<CardGroup cols={2}>
  <Card title="Core Concepts" href="/concepts/workflows-and-steps">
    Learn about workflows and steps
  </Card>

  <Card title="API Reference" href="/api-reference/integrations/nitro">
    View the full Nitro API reference
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.