> ## 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.

# @workflow/vite

> Vite plugin for Workflow DevKit

## Installation

```bash theme={null}
npm install @workflow/vite
```

## Usage

Import and use the hot update plugin in your Vite configuration:

```typescript vite.config.ts theme={null}
import { workflowHotUpdatePlugin } from '@workflow/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    workflowHotUpdatePlugin({
      builder: myBuilder,
    }),
  ],
});
```

## API

### `workflowHotUpdatePlugin(options)`

Vite plugin that watches for workflow/step file changes and triggers rebuilds during development.

<ParamField path="options" type="object" required>
  Plugin configuration options.
</ParamField>

<ParamField path="options.builder" type="BaseBuilder | (() => BaseBuilder | undefined) | undefined" required>
  Builder instance or a getter function.

  Use a getter function when the builder is created lazily (e.g., in Nitro where it depends on the nitro object).

  **Examples:**

  ```typescript theme={null}
  // Direct instance
  { builder: myBuilder }

  // Lazy getter
  { builder: () => getBuilder() }
  ```
</ParamField>

<ParamField path="options.enqueue" type="(fn: () => Promise<void>) => Promise<void>">
  Optional build queue function to prevent concurrent builds.

  If not provided, builds will run directly without queuing.

  **Example:**

  ```typescript theme={null}
  import { createBuildQueue } from '@workflow/builders';

  const enqueue = createBuildQueue();

  workflowHotUpdatePlugin({
    builder: myBuilder,
    enqueue,
  })
  ```
</ParamField>

## How It Works

The plugin monitors file changes during Vite's HMR (Hot Module Replacement) process:

1. **File Detection**: Watches for changes to `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` files
2. **Pattern Matching**: Scans file content for:
   * `"use workflow"` directive
   * `"use step"` directive
   * `@workflow/serde` imports
   * `Symbol.for('workflow-serialize')` or `Symbol.for('workflow-deserialize')`
3. **Rebuild Trigger**: When patterns are detected, triggers the builder to regenerate workflow routes
4. **HMR Passthrough**: Lets Vite handle normal HMR for the changed file

### Exclusions

The plugin automatically skips:

* Non-JavaScript/TypeScript files
* Generated workflow route files (prevents infinite rebuild loops)
* Files in `.well-known/workflow/` paths

## Integration Examples

### With Custom Builder

```typescript vite.config.ts theme={null}
import { workflowHotUpdatePlugin } from '@workflow/vite';
import { createBuildQueue } from '@workflow/builders';
import { defineConfig } from 'vite';
import { MyBuilder } from './my-builder';

const builder = new MyBuilder();
const enqueue = createBuildQueue();

export default defineConfig({
  plugins: [
    workflowHotUpdatePlugin({
      builder,
      enqueue,
    }),
  ],
});
```

### With Lazy Builder

```typescript vite.config.ts theme={null}
import { workflowHotUpdatePlugin } from '@workflow/vite';
import { defineConfig } from 'vite';

let builder;

export default defineConfig({
  plugins: [
    workflowHotUpdatePlugin({
      builder: () => builder,
    }),
  ],
});
```

## Usage in Other Integrations

This plugin is used internally by:

* `@workflow/astro`
* `@workflow/sveltekit`
* `@workflow/nitro` (via Vite mode)

These integrations typically combine it with `@workflow/rollup` for complete workflow support.


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