Skip to main content

​
Installation

npm install @workflow/astro

​
Usage

Add the workflow integration to your Astro configuration:
astro.config.mjs
import { defineConfig } from 'astro/config';
import { workflow } from '@workflow/astro';

export default defineConfig({
  integrations: [workflow()],
});

​
API

​
workflow()

Astro integration that provides workflow functionality. Takes no arguments and returns an Astro integration object. 
import { workflow } from '@workflow/astro';

​
Configuration Example

astro.config.mjs
import { defineConfig } from 'astro/config';
import { workflow } from '@workflow/astro';

export default defineConfig({
  integrations: [workflow()],
  output: 'server',
});

​
How It Works

The integration automatically:
  1. Local Development:
    • Builds workflows during astro:config:setup hook
    • Adds Vite plugins for workflow transformation and hot module replacement
    • Watches for workflow file changes and rebuilds automatically
  2. Production (Non-Vercel):
    • Uses LocalBuilder to generate workflow bundles
    • Creates routes at .well-known/workflow/v1/
  3. Vercel Deployment:
    • Uses VercelBuilder during astro:build:done hook
    • Generates Vercel Build Output API compatible functions

​
Generated Routes

The integration creates the following API routes:
  • /.well-known/workflow/v1/flow - Workflow execution endpoint
  • /.well-known/workflow/v1/step - Step execution endpoint
  • /.well-known/workflow/v1/webhook/:token - Webhook endpoint
  • /.well-known/workflow/v1/manifest.json - Workflow manifest (when WORKFLOW_PUBLIC_MANIFEST=1)

​
Vite Plugins

The integration adds these Vite plugins:
  1. workflowTransformPlugin (from @workflow/rollup): Transforms workflow directives
  2. workflowHotUpdatePlugin (from @workflow/vite): Enables HMR for workflow files

​
Environment Detection

Automatically detects Vercel deployments via VERCEL_DEPLOYMENT_ID environment variable and uses the appropriate builder.

​
Build Queue

Uses createBuildQueue() from @workflow/builders to prevent concurrent builds during development.

​
Error Handling

Build errors during config setup are logged and re-thrown to properly propagate to Astro, allowing for better debugging of:
  • Invalid workflow files
  • Missing dependencies
  • Configuration issues

Build docs developers (and LLMs) love

Get started for freeTalk to us