Flux Events and Scripts

Overview

Flux is Oblax’s event-driven scripting system. Flux scripts are JavaScript functions that execute automatically in response to platform events — a user signs up, a form is submitted, an order is placed. When an event occurs, the platform looks up the associated script, loads it into an embedded JavaScript runtime, and executes it with the event data.

Flux scripts use a key-based identity strategy. Each script is identified by a platform-defined event name that cannot be changed. You choose which events to handle by initializing and enabling scripts for those events.

How Flux Works

The Flux execution pipeline has three stages:

1. Event emission — A platform event occurs (e.g., user.created)
2. Script lookup — The engine finds the script registered for that event
3. Script execution — The engine runs the script in an isolated JavaScript runtime

Event → Script Lookup → JavaScript Execution → Side Effects

Scripts run inside a goja embedded ECMAScript runtime with a configurable timeout. Each invocation creates a fresh runtime, so scripts cannot share state between executions.

Event Keys

Flux scripts are identified by platform-defined event keys. These keys correspond to specific platform events and cannot be modified. You initialize a script for an event key, write the handler logic, and push it to the platform.

Common event keys:

The full list of available event keys is documented in the platform reference.

Script Structure

A Flux script receives two globals:

if (event === 'user.created') {
  const userId = data.userId;
  const email = data.email;
}

Scripts can perform any JavaScript logic — transforming data, calling external APIs, generating content, or triggering side effects through platform services.

Creating Flux Scripts

Use the CLI to initialize a script for a specific event:

obx app flux:scripts init user.created

This creates a local script file with a stub handler:

/app/flux-scripts/flux_on_user_created.js

Edit the file with your handler logic, then push it to the platform:

obx app flux:scripts push user.created

Enabling and Disabling Scripts

Scripts can be enabled or disabled without deleting them. A disabled script remains stored on the platform but does not execute when its event occurs.

obx app flux:scripts disable user.created
obx app flux:scripts enable user.created

Timeout and Safety

Each script execution has a configurable timeout (default: 5000ms). If a script exceeds the timeout, the engine interrupts the runtime and logs an error. Scripts cannot:

• Access the filesystem directly
• Make arbitrary network requests (unless explicitly allowed)
• Share state between invocations
• Access other scripts or their data

Flux and Service Extension

For more complex workflows, you can combine Flux scripts with custom microservices. A Flux script can emit a message to a RabbitMQ queue, which triggers an async service built with obxfw. This pattern lets you offload heavy processing while keeping your Flux scripts lightweight.

Event → Flux Script → RabbitMQ → Async Service → gRPC DOM Service

Where to next