You write zero Rust. TitanPl handles routing, bundling, runtime execution, hot reload, and deployment โ
all powered by Rust under the hood.
%20%26%20Rust%20Tokio-1f2937?style=for-the-badge)
Description
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.
Documentation
Gravity Runtime
Drift
# ๐ Quick Start
### 1. Prerequisites
* **Rust** (latest stable): [Install Rust](https://rust-lang.org/tools/install/) [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.**
```bash
npm install -g @titanpl/cli@latest
```
### 3. Initialize & Run
Titan guides you through selecting the perfect architecture for your needs.
```bash
titan init my-app
```
**Select your language:**
1. `JavaScript` (Fast, lightweight)
2. `TypeScript` (Strict, typed)
**Select your architecture:**
1. `Standard` (Pure JS/TS)
2. `Rust + JS/TS (Hybrid)` (High-performance native actions)
Inside your project:
```bash
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.
| Feature | Status | Notes |
| :--- | :--- | :--- |
| **Standard JavaScript** | โ
Stable | Production Ready |
| **Standard TypeScript** | โ
Stable | Production Ready |
| **Rust + JS (Hybrid)** | ๐งช Experimental | **Dev Only**, Production Under Testing |
| **Rust + TS (Hybrid)** | ๐งช Experimental | **Dev Only**, Production Under Testing |
### ๐ต TypeScript Actions (`app/actions/hello.ts`)
Fully typed, strict, and auto-compiled.
```typescript
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.
```javascript
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**.
```rust
use axum::{response::{IntoResponse, Json}, http::Request, body::Body};
use serde_json::json;
pub async fn run(req: Request) -> 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:
```text
[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 `: 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:
```bash
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
```bash
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:
```dockerfile
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`:
```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**