Scripting

Allows the execution of JavaScript files using a built-in interpreter

Technology

goja
Golang
Project Forge

This module provides server-side JavaScript execution capabilities for Project Forge applications using the Goja JavaScript runtime.

Features

Installation

Add this module to your project configuration, by using the UI or editing project.json directly:

1
2
3
{
  "modules": ["filesystem", "scripting"]
}

Usage

Service Setup

Create a new scripting service in your application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import (
    "your-app/app/lib/filesystem"
    "your-app/app/lib/scripting"
)

// Create filesystem service pointing to script directory
fs := filesystem.NewService("./data")

// Create scripting service with filesystem and script path
scriptService := scripting.NewService(fs, "scripts")

Web Interface

Access the scripting interface at /admin/scripting to: - List all available scripts - View script content and execution results - Create and edit scripts - Run scripts and view output - Test example functions automatically

JavaScript Environment

Each script runs in an isolated JavaScript VM

Example Testing

Scripts can include automated test examples that will be executed when viewing the script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Your script functions
function greet(name, title) {
  return `Hello ${title} ${name}!`;
}

function calculate(a, b, operation) {
  switch(operation) {
    case 'add': return a + b;
    case 'multiply': return a * b;
    default: return 0;
  }
}

// Test examples - will be automatically executed
const examples = {
  "greet": [
    ["Alice", "Dr."],
    ["Bob", "Mr."],
    ["Carol", "Prof."]
  ],
  "calculate": [
    [5, 3, "add"],
    [4, 7, "multiply"],
    [10, 2, "divide"]
  ]
};

The examples object maps function names to arrays of parameter sets. Each parameter set will be passed to the function and the results displayed in the web interface.

Script Management

Scripts are stored as .js files in the configured directory. The service provides methods to:

Error Handling

Scripts are executed in isolated VMs with comprehensive error handling: - Syntax errors are caught during script loading - Runtime errors are captured and displayed - VM isolation prevents scripts from affecting each other

API Endpoints

When included in a Project Forge application, the module provides these routes:

Security Considerations

Source Code