Temporal Workflows Webpack Plugin

Webpack plugin for automatic bundling of Temporal workflows using @temporalio/worker.

Why do you need this?

Temporal workflows require special bundling via bundleWorkflowCode because they:

• Run in an isolated V8 isolate
• Cannot use Node.js APIs directly
• Must be deterministic

Typically, developers handle this manually through separate npm scripts. This plugin integrates the bundling process directly into your webpack build pipeline.

Features

• ✅ Automatic bundling of workflows during project build
• ⚡ Watch mode with incremental rebuilds
• 🎯 Full support for all BundleOptions from @temporalio/worker
• 🔧 Flexible configuration - global and per-workflow options
• 📦 TypeScript typings out of the box
• 🚀 Zero config for simple cases

Installation

Prerequisites: This plugin requires @temporalio/worker to be installed in your project.

# Install the plugin as a dev dependency
npm install --save-dev temporal-workflows-webpack-plugin

# If you don't have @temporalio/worker yet, install it as well
npm install @temporalio/worker

# or with yarn
yarn add -D temporal-workflows-webpack-plugin
yarn add @temporalio/worker

# or with pnpm
pnpm add -D temporal-workflows-webpack-plugin
pnpm add @temporalio/worker

Quick Start

// webpack.config.js
const TemporalWorkflowsPlugin = require('temporal-workflows-webpack-plugin');

module.exports = {
  // ... your webpack config
  plugins: [
    new TemporalWorkflowsPlugin({
      defaultOutputDir: './dist/workflows',
      workflows: [
        { workflowsPath: './src/workflows' }
      ]
    })
  ]
};

This will create ./dist/workflows/workflows.js with all workflows from ./src/workflows.

Usage

Basic Configuration

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  workflows: [
    { 
      workflowsPath: './src/workflows/orders',
      name: 'order-workflows' 
    },
    { 
      workflowsPath: './src/workflows/payments',
      name: 'payment-workflows'
    }
  ]
})

With Temporal Bundler Options

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  
  // Global options apply to all workflows
  globalBundleOptions: {
    ignoreModules: ['some-problematic-module'],
    workflowInterceptorModules: ['./src/workflow-interceptors']
  },
  
  workflows: [
    { 
      workflowsPath: './src/workflows/critical',
      name: 'critical',
      // Local options override global ones
      bundleOptions: {
        webpackConfigHook: (config) => ({
          ...config,
          optimization: { minimize: true }
        })
      }
    }
  ]
})

TypeScript

import TemporalWorkflowsPlugin, { 
  TemporalWorkflowsPluginOptions 
} from 'temporal-workflows-webpack-plugin';
import { Configuration } from 'webpack';

const config: Configuration = {
  plugins: [
    new TemporalWorkflowsPlugin({
      defaultOutputDir: './dist/workflows',
      workflows: [
        { workflowsPath: './src/workflows' }
      ]
    } as TemporalWorkflowsPluginOptions)
  ]
};

API

TemporalWorkflowsPluginOptions

| Option | Type | Required | Description | |--------|------|----------|-------------| | defaultOutputDir | string | ✅ | Default directory for output files | | workflows | WorkflowBundleConfig[] | ✅ | List of workflows to bundle | | globalBundleOptions | Omit<BundleOptions, 'workflowsPath'> | ❌ | Global options for all workflows |

WorkflowBundleConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | workflowsPath | string | ✅ | Path to entry file with workflows | | name | string | ❌ | Output file name (without .js) | | outputPath | string | ❌ | Full path to output file | | bundleOptions | Omit<BundleOptions, 'workflowsPath'> | ❌ | Bundler options for this workflow |

BundleOptions (from @temporalio/worker)

See the full list of options in Temporal documentation.

Main options:

• ignoreModules - modules to exclude from bundle
• webpackConfigHook - function to modify webpack config
• workflowInterceptorModules - paths to workflow interceptors
• payloadConverterPath - path to custom payload converter
• failureConverterPath - path to custom failure converter

Examples

Simple Project

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  workflows: [
    { workflowsPath: './src/workflows' }
  ]
})

Multiple Workflows

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  workflows: [
    { workflowsPath: './src/workflows/orders', name: 'orders' },
    { workflowsPath: './src/workflows/payments', name: 'payments' },
    { workflowsPath: './src/workflows/notifications', name: 'notifications' }
  ]
})

With Module Ignoring

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  globalBundleOptions: {
    ignoreModules: ['bull', 'amqplib', 'ioredis']
  },
  workflows: [
    { workflowsPath: './src/workflows' }
  ]
})

With Custom Webpack Config

new TemporalWorkflowsPlugin({
  defaultOutputDir: './dist/workflows',
  workflows: [
    { 
      workflowsPath: './src/workflows',
      bundleOptions: {
        webpackConfigHook: (config) => ({
          ...config,
          resolve: {
            ...config.resolve,
            alias: {
              ...config.resolve?.alias,
              '@utils': path.resolve(__dirname, 'src/utils')
            }
          }
        })
      }
    }
  ]
})

How It Works

1. Build mode: When running webpack (webpack build), the plugin bundles all specified workflows
2. Watch mode: When files change (webpack watch), the plugin determines which workflow is affected and rebuilds only that one
3. Output: A separate .js file with bundled code is created for each workflow

Troubleshooting

Module cannot be used in workflow

If you see an error like "Cannot use module X in workflow":

globalBundleOptions: {
  ignoreModules: ['problematic-module']
}

Need source maps

Source maps are enabled by default in Temporal bundler.

Workflow not rebuilding in watch mode

Make sure webpack is properly tracking changes in your workflow files.

Compatibility

• Node.js: >= 18.0.0
• Webpack: ^4.0.0 || ^5.0.0
• @temporalio/worker: ^1.0.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Created with ❤️ for the Temporal community