Skip to main content

​
Installation

npm install @workflow/vite

​
Usage

Import and use the hot update plugin in your Vite configuration:
vite.config.ts
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.
​
options
object
required
Plugin configuration options.
​
options.builder
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:
// Direct instance
{ builder: myBuilder }

// Lazy getter
{ builder: () => getBuilder() }
​
options.enqueue
(fn: () => Promise<void>) => Promise<void>
Optional build queue function to prevent concurrent builds.If not provided, builds will run directly without queuing.Example:
import { createBuildQueue } from '@workflow/builders';

const enqueue = createBuildQueue();

workflowHotUpdatePlugin({
  builder: myBuilder,
  enqueue,
})

​
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

vite.config.ts
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

vite.config.ts
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us