vite-plugin-botpress-actions

vite-plugin-botpress-actions

A Vite plugin that transforms modular TypeScript/JavaScript code into self-contained Botpress actions for deployment in Botpress Studio's Execute Card environment.

Features

• 🔍 Auto-discovery - Automatically finds and processes all actions in src/actions/
• 📝 Schema extraction - Generates separate schema files for Botpress registration
• 🔄 Code transformation - Inlines dependencies and extracts function bodies
• 📦 TypeScript & JavaScript - Supports both .ts and .js files
• 🎯 Deno-compatible - Outputs code ready for Botpress's Deno runtime

Installation

npm install --save-dev vite-plugin-botpress-actions
# or
pnpm add -D vite-plugin-botpress-actions

Usage

Add the plugin to your vite.config.js or vite.config.ts:

import { defineConfig } from 'vite';
import { botpressActionsPlugin } from 'vite-plugin-botpress-actions';

export default defineConfig({
  plugins: [
    botpressActionsPlugin({
      // Optional configuration
      actionsDir: 'src/actions',    // default
      schemasDir: 'src/schemas',    // default
      sharedDir: 'src/shared',      // default
      outputDir: 'dist',             // default
      extensions: ['ts', 'js']      // default
    })
  ]
});

How It Works

The plugin performs a three-pass build process:

• Analyzes all actions to map schema usage
• Generates individual schema files in dist/schemas/
• Transforms action code into self-contained function bodies in dist/actions/

Input Structure

src/
├── actions/
│   ├── myAction.ts       # Action implementations
│   └── anotherAction.js
├── schemas/
│   └── shared/           # Reusable schemas
│       └── common.ts
└── shared/               # Utility functions
    └── helpers.ts

Output Structure

dist/
├── actions/
│   ├── myAction.ts       # Function body only (paste into Execute Card)
│   └── anotherAction.js
└── schemas/
    ├── myActionInputSchema.ts    # Action-specific schemas
    └── shared/
        └── common.ts             # Shared schemas

Action Format

Actions must follow this structure:

// src/actions/myAction.ts
import { z } from '@bpinternal/zui';
import { helperFunction } from '../shared/helpers.ts';

// Define schemas
const inputSchema = z.object({
  name: z.string()
});

const outputSchema = z.object({
  message: z.string()
});

// Export async function (name doesn't matter)
export async function myAction(input: z.infer<typeof inputSchema>) {
  const result = helperFunction(input.name);
  return { message: result };
}

Configuration Options

Option	Type	Default	Description
actionsDir	string	'src/actions'	Directory containing action files
schemasDir	string	'src/schemas'	Directory containing schema files
sharedDir	string	'src/shared'	Directory containing shared utilities
outputDir	string	'dist'	Output directory for built files
extensions	string[]	['ts', 'js']	File extensions to process
inlinePackages	object	{ nanoid: '...' }	External packages to inline

Botpress Runtime

Actions run in a secure, sandboxed Deno environment with these pre-installed libraries:

• axios - HTTP client
• _ (Lodash) - Utility library
• luxon - Date/time manipulation
• z/zui - Zod validation (@bpinternal/zui)
• client - Botpress Client (when enabled in bot settings)
• zai - Botpress AI utilities (@botpress/zai)

Don't import these in your actions - they're globally available.

License

MIT