titanpl

v4.0.2

Published

10 days ago

Titan Planet is a JavaScript-first backend framework that embeds JS actions into a Rust + Axum server and ships as a single native binary. Routes are compiled to static metadata; only actions run in the embedded JS runtime. No Node.js. No event loop in pr

Titan Planet is a JavaScript/TypeScript-first Backend Framework that compiles your application into a single, high-performance native binary. It embeds it's own Gravity (V8) JavaScript runtime directly into a specialized Rust + Axum server.

TypeScript Precision. JavaScript Simplicity. Native Rust Power. Zero Configuration.

Why Titan?

Titan Planet compiles your JavaScript or TypeScript application into a single native Rust binary.

It embeds a V8 runtime inside a Rust + Axum server — giving you:

⚡ Native-level performance
📦 Single binary deployment
🧠 Strict TypeScript enforcement
🛡 Zero type errors before runtime
🚀 No DevOps configuration required

Start with pure TypeScript. Drop into Rust when you need extreme performance. Titan handles the integration automatically.

🚀 Quick Start

1. Prerequisites

Rust (latest stable): Install Rust [Optional]
Node.js (v18+): Required for CLI and JS tooling.

2. Install CLI

The titanpl CLI is used to create and manage all your new projects and everything related to Titan.

npm install -g @titanpl/cli@latest

3. Initialize & Run

Titan guides you through selecting the perfect architecture for your needs.

titan init my-app

Select your language:

JavaScript (Fast, lightweight)
TypeScript (Strict, typed)

Select your architecture:

Standard (Pure JS/TS)
Rust + JS/TS (Hybrid) (High-performance native actions)

Inside your project:

cd my-app
npm run dev

You'll see the Titan Dev Server spin up:

  ⏣ Titan Planet   v1.0.0   [ Dev Mode ]

  Type:        TS Actions
  Hot Reload:  Enabled
  Env:         Loaded

🚀 Starting Titan Engine...
[Titan] 1 reply route(s) pre-computed
Titan server running at: http://localhost:5100  (Threads: 32, Stack: 8MB, Dev Mode)

⚡ Hybrid Action System

Titan is unique because it allows you to write endpoints in JavaScript, TypeScript, and Rust within the same project.

🔵 TypeScript Actions (`app/actions/hello.ts`)

Fully typed, strict, and auto-compiled.

import { defineAction } from "@titanpl/native";

interface HelloResponse {
    message: string;
    user_name: string;
}

// "defineAction" provides automatic type inference for "req"
export const hello = defineAction((req): HelloResponse => {
    t.log("Handling request with strict types...");

    return { 
        message: "Hello from TypeScript!",
        user_name: req.body.name || "Guest"
    };
});

🟡 JavaScript Actions (`app/actions/hello.js`)

Perfect for business logic, rapid prototyping, and IO-bound tasks.

export const hello = defineAction((req) => {
    t.log("Handling user request...");
    return { 
        message: "Hello from JavaScript!",
        user_id: req.params.id 
    };
});

🔴 Rust Actions (Beta)

Perfect for heavy computation, encryption, image processing, or low-level system access.

Note: The Native Rust Action API is currently in Beta.

use axum::{response::{IntoResponse, Json}, http::Request, body::Body};
use serde_json::json;

pub async fn run(req: Request<Body>) -> impl IntoResponse {
    let result = heavy_computation();
    t.log("Processed 1M records in Rust");
    Json(json!({ "result": result }))
}

Titan automatically detects, compiles, and routes all types.

.ts files are type-checked and compiled with esbuild.
.js files are bundled with esbuild.
.rs files are compiled into the native binary.
All share the same routes.json configuration.

🛡️ Strict Type Safety & Error Logs

Titan prioritizes code quality by enforcing Strict TypeScript logic during development.

If titan dev detects a type error, the server will not run. This ensures you never ship or test broken code.

Sample Error Output

When a type error occurs, Titan pauses execution and provides a clear, actionable log:

[Titan] ❌ TypeScript Error:
app/actions/payment.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.

    10 |    const amount: number = req.body.amount;
    11 |    
  > 12 |    processPayment( "100" ); // Error here
       |    ^^^^^^^^^^^^^^^^^^^^^^^

[Titan] 🛑 Server paused due to type errors. Fix them to resume.

Once fixed, the server automatically resumes.

✨ Core Capabilities

🔌 Unified Runtime API (`t`)

All actions (JS/TS/Rust) have access to the powerful t namespace:

t.fetch(url, options) — High-performance HTTP client
t.log(msg) — Sandboxed, structured logging
t.jwt.sign / verify — Fast JWT operations
t.password.hash / verify — Secure password handling
t.db — Database access

🧩 Extensions System

Extend the runtime with custom Rust engines using Titan Extensions.

titan create ext <name>: Scaffold a new extension.
titan run ext: Test your extension in a lightweight harness.

📦 Building & Deployment

Titan offers a unified build system that packages your JS/TS code, assets, and the native engine into a single, self-contained build/ directory.

1. Production Build

Run this command from your project root:

titan build --release

This will:

Bundle your actions into optimized .jsbundle files.
Extract all required Titan extensions and native libraries to .ext/.
Copy your public/, static/, and other configured assets.
Generate a titan-server executable in the build/ folder.

2. Run the Build

cd build
./titan-server

Your application is now running as a standalone native server.

🐳 Docker Deployment

The titan build --release command is optimized for Docker. Your Dockerfile can be as simple as:

FROM node:20-slim AS builder
WORKDIR /app
COPY . .
RUN npm install --include=optional
RUN npx titan build --release

FROM ubuntu:24.04
WORKDIR /app
COPY --from=builder /app/build .
CMD ["./titan-server", "run", "dist"]

This produces a tiny, high-performance production image with zero node_modules.

🛠 Configuration (`tanfig.json`)

You can customize the build process in your tanfig.json:

{
  "build": {
    "purpose": "deploy",
    "files": ["public", "db", "secrets"]
  }
}

purpose: Use deploy to skip node_modules junctions for the smallest possible footprint.
files: List any extra folders you want included in the build/ output.

To know more read docs 💟 Titan Planet docs: https://titanpl.vercel.app/docs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme