Rethinking the Full-Stack Web.
A modern, TypeScript-first, independent full-stack web application framework.

---

Note

Public Alpha Stage

Ranu.js is currently in Public Alpha. Core architecture, routing, rendering, build pipelines, and production server runtimes are fully functional and ready for testing, hobby applications, and community feedback. While APIs are being actively stabilized toward the V1 release, minor breaking changes may occur.

---

What is Ranu.js?

Ranu.js is an open-source, independent JavaScript/TypeScript full-stack web framework designed for building scalable web applications, dynamic dashboards, REST APIs, and modern digital platforms.

Modern web engineering often requires developers to manually stitch together unrelated libraries for routing, rendering, server runtimes, compilation, and cloud deployment. Ranu.js addresses this fragmentation by offering a coherent, unified application platform with explicit execution boundaries, standards-compliant APIs, and complete deployment portability.

---

How Ranu.js Solves Developer Challenges

• Unified Application Architecture: Eliminates tool fatigue by integrating file-based routing, React 19 streaming SSR, static site generation (SSG), client hydration, API routes, middleware, and styling into a single, cohesive framework.
• True Deployment Portability: Designed from the ground up to be hosting-agnostic. Applications build into portable, deterministic artifacts that run identically on self-hosted Node.js servers, Docker containers, virtual machines, or serverless cloud environments via dedicated adapters.
• Explicit Execution Boundaries & Security: Enforces strict compile-time boundaries between client and server code. Modules marked with ranu/server-only prevent accidental exposure of sensitive backend logic, database credentials, or environment secrets to client bundles.
• Web Standards Native: Built directly on top of standard platform primitives (Request, Response, URL, Headers, ReadableStream), ensuring long-term code resilience and minimal framework-specific lock-in.
• Progressive Complexity: Offers zero-configuration simplicity for straightforward applications while providing fine-grained plugin hooks, custom manifests, and runtime controls as system requirements grow.

---

Architectural Differentiation

1. UI-Agnostic Core Engine: While Ranu.js debuts with full React 19 streaming integration, the core runtime, routing engine, and build pipeline are designed to remain UI-neutral, paving the way for multi-UI adapter support.
2. Transparent, Manifest-Driven Builds: Rather than obfuscating output behind complex proprietary bundlers, Ranu.js generates deterministic server bundles, client assets, and structured manifests (.ranu/manifests) that are fully inspectable and auditable.
3. Provider-Neutral Runtime Contracts: The internal server contract abstracts platform differences without imposing specialized cloud constraints, ensuring your infrastructure decisions remain flexible.
4. Resilient Security Defaults: Built-in safeguards including polynomial ReDoS-hardened route matching, automated path traversal defense, and isolated secret handling.

---

Built-in Capabilities

• File-Based Routing:
  • Nested layouts and multi-level hierarchy
  • Parameterized dynamic routes ([id])
  • Catch-all segments ([...slug])
  • Isolated route groups
• Versatile Rendering Engine:
  • React 19 Streaming Server-Side Rendering (SSR)
  • Static Site Generation (SSG) with pre-rendered HTML
  • Client-Side Rendering with seamless hydration
• Backend & Server Primitives:
  • Standard REST API routes (GET, POST, PUT, DELETE, etc.)
  • Composable Request Middleware (authentication guards, rewrites, redirects)
  • Context helpers (cookies(), headers(), redirect(), notFound())
• Developer Experience:
  • Sub-second Hot Module Replacement (HMR) & React Fast Refresh
  • Native TypeScript support with zero configuration
  • CSS & CSS Modules integration
  • Extensible Plugin Architecture (definePlugin())
• Deployment Adapters:
  • Standalone Node.js server production bundle
  • Multi-stage, non-root Docker container templates
  • Cloud serverless adapter (@ranujs/adapter-vercel)

---

Quick Start

1. Automatic Scaffolding

The fastest way to create a new Ranu.js project is using create-ranujs:

# Using npm (recommended — pre-installed with Node.js)
npx create-ranujs@latest my-app

# Or using npm's initializer syntax
npm create ranujs@latest my-app

# Or using alternative package managers
pnpm create ranujs@latest my-app
yarn create ranujs@latest my-app
bun create ranujs@latest my-app

Then navigate to your project and start the development server:

cd my-app
npm install
npm run dev

Open http://localhost:3000 in your browser.

---

2. Manual Setup

If you prefer to configure your application manually:

Install Dependencies

npm install @ranujs/core react react-dom
npm install -D typescript @types/node @types/react @types/react-dom

Configure package.json Scripts

{
  "name": "my-ranu-app",
  "type": "module",
  "scripts": {
    "dev": "ranu dev",
    "build": "ranu build",
    "start": "ranu start",
    "typecheck": "tsc --noEmit"
  }
}

Then start development:

npm run dev

---

3. Project Structure

A standard Ranu.js project follows this file layout:

my-app/
├── app/
│   ├── layout.tsx         # Root layout (wraps all pages)
│   ├── page.tsx           # Home page route (/)
│   ├── about/
│   │   └── page.tsx       # Subpage route (/about)
│   └── api/
│       └── hello/
│           └── route.ts   # Backend API endpoint (/api/hello)
├── public/                # Static assets (images, favicon, etc.)
├── ranu.config.ts         # Framework configuration
├── tsconfig.json
└── package.json

---

4. Creating Your First Application

Configuration (ranu.config.ts)

import { defineConfig } from '@ranujs/core/config';

export default defineConfig({
  server: {
    port: 3000,
  },
});

Root Layout (app/layout.tsx)

Every application must define a root layout to wrap page content:

import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Ranu.js App</title>
      </head>
      <body>
        <main>{children}</main>
      </body>
    </html>
  );
}

Index Page (app/page.tsx)

export default function HomePage() {
  return (
    <div>
      <h1>Welcome to Ranu.js</h1>
      <p>A modern full-stack web framework.</p>
    </div>
  );
}

API Endpoint (app/api/hello/route.ts)

Create server-side REST endpoints using standard Web Response primitives:

export async function GET() {
  return Response.json({
    status: 'ok',
    message: 'Hello from Ranu.js API!',
    timestamp: new Date().toISOString(),
  });
}

---

5. CLI Commands Reference

Ranu.js provides an intuitive CLI for everyday development:

Command	Description	Default Port / Flags
ranu dev	Starts local development server with Fast Refresh & HMR	http://localhost:3000 (-p, --port, -H, --host)
ranu build	Compiles production server, client bundles, and manifests	Generates .ranu/ production directory
ranu start	Launches optimized standalone Node.js production server	Runs production build on configured port

---

Official Examples

The repository includes standalone reference applications demonstrating idiomatic Ranu.js patterns:

Example	Description	Key APIs & Highlights
examples/hello-world	Minimal baseline application	Root layout, page routing, defineConfig
examples/routing	Nested file-based routing	Multi-level layouts, static subpages, custom 404
examples/dynamic-routing	Parameterized route patterns	[id], [category]/[productId], [...slug]
examples/ssr	Dynamic Server-Side Rendering	render = 'server', request headers, runtime context
examples/ssg	Static Site Generation	render = 'static', pre-rendered HTML generation
examples/api-routes	Backend REST API endpoints	GET, POST, Response.json(), body parsing
examples/middleware	Request interception & guards	Route protection, auth redirects, URL rewriting
examples/client-components	Interactive React 19 hydration	Client state, useRouter(), usePathname(), useSearchParams()
examples/full-stack-dashboard	Complete full-stack reference	SSR dashboard, SSG about, API metrics, client widgets
examples/deployment-node	Standalone Node.js server	Multi-stage production Dockerfile, non-root container
examples/deployment-vercel	Serverless cloud deployment	@ranujs/adapter-vercel, Vercel Build Output API v3
examples/plugin-basic	Extensible plugin architecture	definePlugin(), build lifecycle hooks, config customization

To run any example locally:

cd examples/<example-name>
pnpm install
pnpm dev

---

Documentation

Explore the comprehensive Ranu.js Documentation Hub for detailed tutorials, architectural overviews, and API references:

• Getting Started: Overview • Installation • Project Structure • First Application
• Developer Guides: Routing & Layouts • Data Fetching & APIs • Authentication • Databases • Styling • AI Engineering • Deployment
• API Reference: CLI Commands • Configuration Schema • React APIs • Server & Runtime APIs
• Ecosystem & Plugins: Plugin Specification • Cloud Storage • Verified Providers
• Security Guarantees: Compiler Boundaries • Security Policy

---

Future Vision & Roadmap

The long-term vision of Ranu.js extends beyond a conventional frontend layer. The objective is to cultivate a self-sustaining, full-stack application ecosystem:

• Integrated Application Primitives: Built-in conventions for data access layers, background workers, scheduled jobs, and session management.
• Multi-Runtime Ecosystem: Deployment adapters for edge environments, Cloudflare Workers, AWS Lambda, Fastly Edge, Deno, and Bun.
• Community-Driven Open Governance: Transparent RFC processes, community roadmaps, and vendor-neutral development.

Release Milestones

[ Pre-Alpha ] ✅ Completed (Core bootstrap & Phase 0–32)
      │
      ▼
[ Public Alpha ] 📍 Current Stage
      │  • Community validation & real-world feedback
      │  • API ergonomics stabilization & RFC review
      │  • Edge-case bug resolution & developer tooling refinement
      ▼
[ Beta Stage ]
      │  • Public API freeze
      │  • Feature completeness across target matrix
      │  • Production readiness hardening
      ▼
[ Release Candidate (RC) ]
      │  • Zero blocking defects
      │  • End-to-end security & performance verification
      ▼
[ Ranu.js 1.0.0 (General Availability) ] 🚀
      • Production LTS commitment

---

Monorepo Development

Prerequisites

• Node.js >= 22.0.0
• pnpm >= 11.0.0

Setup & Workflow

# Clone the repository
git clone https://github.com/hoslift/ranu.js.git
cd ranu.js

# Install dependencies across all packages
pnpm install

# Build all workspace packages
pnpm build

# Run comprehensive test suite
pnpm test

# Type check all packages
pnpm typecheck

# Lint and format
pnpm lint
pnpm format:check

---

Contributing

Contributions are warmly welcomed! Please read our Contributing Guide and review our Code of Conduct before submitting a pull request.

---

💖 Sponsors & Backers

Ranu.js is an independent open-source framework created and maintained by Hoslift. Generous support from individuals and organizations helps sustain continuous development, security audits, and ecosystem maintenance.

---

Contributors

---

License

Ranu.js is open-source software licensed under the MIT License.
Maintained by Hoslift.