TitanPL extensions allow developers to extend the Gravity runtime using JavaScript, Rust, Go, WebAssembly, and native system libraries.

Extensions integrate directly into the Gravity runtime and become accessible globally through the t namespace or via explicit imports from that npm package.

TitanPL supports multiple extension architectures optimized for different workloads, ranging from fully sandboxed JavaScript modules to high-performance native runtime integrations.

🚀 Extension Types

TitanPL currently supports four extension categories:

JavaScript Extensions

JS-Only Runtime Extensions

JavaScript extensions run directly inside the Gravity V8 runtime.

They are the simplest extension type and require no native compilation.

Best For

• Utility libraries
• Runtime helpers
• Shared business logic
• Middleware systems
• Lightweight runtime APIs
• Rapid prototyping

Security

JavaScript extensions are fully sandboxed inside Gravity and are always allowed by default.

Create Extension

titan create ext my-ext

Then select: js

Generated Structure

my-ext/
├── index.js
├── titan.json
└── utils/
    └── registerExtension.js

Files

Runtime Registration

JavaScript extensions register themselves onto the global t namespace.

Example:

import { registerExtension } from "./utils/registerExtension.js";


registerExtension("mathx", {
  add(a, b) {
    return a + b;
  }
});

Usage:

import Mathx from 'mathx'

const mathx = new Mathx

mathx.add(5, 2);

Official JS Template

• TitanPL JS Extension Template

WebAssembly Extensions (Experimental)

WASM Runtime Extensions

WASM extensions allow Rust logic to run inside a portable sandboxed execution environment.

TitanPL compiles Rust WASM modules into runtime-loadable .wasm artifacts.

Best For

• Parsers
• Compression systems
• Cryptography
• Data processing
• Portable high-performance logic
• CPU-heavy algorithms

Security

WASM runs sandboxed and requires explicit permission inside tanfig.json.

Create Extension

titan create ext my-ext

Then select: wasm

Build WASM Extension

titan build ext

Requires:

• Rust toolchain
• wasm32-unknown-unknown target

Runtime Output

build/
└── my-ext.wasm

Allow WASM Permissions inside tanfig.json

{
  "extensions": {
    "allowWasm": true
  }
}

WASM Runtime Notes

• Runs isolated from native memory
• Portable across operating systems
• Lower risk than native libraries
• Automatically loaded by Gravity

Native Extensions

Native Rust/C++ Extensions

Native extensions provide direct access to operating system APIs and maximum runtime performance.

TitanPL supports Rust native libraries and C++ runtime modules.

Best For

• Database drivers
• GPU acceleration
• Networking engines
• File system APIs
• Native protocol bindings
• Hardware integrations
• Runtime accelerators

Security

Native extensions are blocked by default.

TitanPL enforces explicit allow-list security through tanfig.json.

Create Native Extension

titan create ext my-native-ext

Then select: native

Build Native Extension

titan build ext

Outputs:

Native Permissions

{
  "extensions": {
    "allowNative": [
      "@titanpl/core",
      "my-native-ext"
    ]
  }
}

Gravity Runtime Architecture

TitanPL executes native extensions outside the primary V8 isolate boundary for runtime stability and crash isolation.

Features

• Native binary verification

• Isolated execution layer

• Runtime permission enforcement

• Crash isolation

• Extension manifest validation

• Learn more about security

Official Native Rust Template

• TitanPL Native Rust Extension Template

Golang Extensions

Go Shared Library Extensions

TitanPL supports Go shared-object extensions through runtime-loadable binaries.

Best For

• Existing Go ecosystems
• Networking tools
• Concurrency-heavy systems
• Performance utilities
• Distributed tooling

Create Extension

titan create ext my-go-ext

Then select: golang

Build Go Extension

titan build ext

Produces:

.dll / .so / .dylib

depending on the target platform.

Official Golang Template

• TitanPL Golang Extension Template

Extension Commands

TitanPL includes a complete extension lifecycle toolkit directly inside the CLI.

titan create ext <name>

Scaffolds a new TitanPL extension package.

Supported Extension Types

Generated Structure

native/      → Native source code
sandbox/     → Extension testing runtime
titan.json   → Extension manifest
index.js     → Runtime registration entrypoint

Example

titan create ext my-ext

titan build ext

Compiles extension runtime binaries.

Supported Targets

• Rust native libraries
• Go shared objects
• WebAssembly modules

Outputs

• .dll
• .so
• .dylib
• .wasm

Example

titan build ext

titan run ext

Launches the Titan Extension Test Harness.

Features

• Minimal TitanPL server
• Isolated Gravity sandbox
• Native extension injection
• Runtime validation
• Local extension linking
• Temporary virtual TitanPl project
• Standalone runtime execution

Sandbox Modes

Example

titan run ext

Security Configuration

tanfig.json

TitanPL uses explicit runtime permissions for all non-JavaScript extensions.

Example:

{
  "name": "my-secure-app",
  "extensions": {
    "allowWasm": true,
    "allowNative": [
      "@titanpl/core",
      "my-custom-native-ext"
    ]
  }
}

Using Extensions

Typed Import Access

import { log, defineAction } from "@titanpl/native";
import "@titanpl/node/globals";
import bcrypt from "bcryptjs";
import Extension from "ext-template";

const demo = new Extension();

export default defineAction((req) => {
  log(demo.hash("hello"));
})

Extension Runtime Flow

Create Extension
      ↓
Build Extension
      ↓
Security Validation
      ↓
Runtime Registration
      ↓
Loaded into Gravity
      ↓
Accessible through t.* or JS import

Recommended Extension Strategy

Summary

• TitanPL supports JS, WASM, Native Rust/C++, and Golang extensions.
• Extensions integrate directly into the Gravity runtime.
• Use titan create ext to scaffold new extensions.
• Use titan build ext to compile runtime binaries.
• Use titan run ext to test extensions inside isolated sandboxes.
• WASM and Native extensions require explicit runtime permissions.
• Extensions become globally accessible through the t namespace or JS import.