Shunya v0.2.0

A batteries-included, opinionated Node.js backend framework — built for clarity, not chaos.

Shunya is a production-grade backend framework for Node.js, designed with a strong mental model, sensible defaults, and a clear separation of concerns.

It is inspired by frameworks like Spring Boot, but built natively for the Node.js ecosystem — without the fragmentation, boilerplate, and dependency sprawl commonly found in Express-based stacks.

✨ Why Shunya?

Modern Node.js backends often suffer from:

• Too many third-party libraries for basic needs
• Weak or inconsistent defaults
• Boilerplate-heavy setup
• Blurred boundaries between HTTP, business logic, and data access
• Ad-hoc error handling and logging

Shunya exists to fix that.

It provides a cohesive, opinionated foundation so you can focus on building your application, not assembling infrastructure.

🧠 Core Philosophy

Shunya is built on a few non-negotiable principles:

• Opinionated by default Good defaults > endless configuration.

• MVC is mandatory Clear boundaries between:

  • Controllers (HTTP)
  • Services (business logic)
  • Models (data access)

• Framework owns the hard parts HTTP lifecycle, errors, logging, configuration — not your app.

• Explicit > Magic No hidden globals. No invisible behavior.

• Escape hatches included Opinionated does not mean restrictive.

🏗️ What Shunya Is

• A Node.js backend framework
• MVC-first
• Batteries-included
• TypeScript-native
• Designed for real production systems

🚫 What Shunya Is Not

• A thin wrapper over Express
• A micro-library collection
• A frontend framework
• A “configure everything yourself” toolkit

🧩 Architecture Overview

At a high level, a Shunya application looks like this:

HTTP Request
   ↓
Middleware Pipeline
   ↓
Controller (HTTP only)
   ↓
Service (business logic)
   ↓
Model (data access)
   ↓
Response

Errors, logging, timing, and configuration are handled centrally by the framework.

🛠️ Example

⚠️ This is design-stage API and may evolve.

import { Shunya } from 'shunya.js';
import { Router } from 'shunya.js/router';

const app = Shunya.create();

const router = new Router({ prefix: "/api" });

router.get("/hello", (req, res) => {
  res.json({ message: "Hello, Shunya!" });
});

app.use(router.routes());

app.listen(3000, () => {
  console.log("Shunya server running on http://localhost:3000");
});

Shunya applications are intentionally boring to read — because boring code scales.

🔩 Built-In Capabilities (Planned)

Shunya follows a core + first-party modules approach.

Core (v0)

• HTTP server & request lifecycle
• Async-safe middleware system
• Centralized error handling
• Typed configuration system
• Structured logging & observability
• MVC auto-wiring

First-Party Modules (Post v0)

• Validation
• Authentication (JWT)
• Security headers & CORS
• Rate limiting
• File uploads

🧪 Project Status

🚧 Early development (design → core runtime)

• Public API still stabilizing
• No production release yet
• Focused on correctness and clarity over speed

This project is being built intentionally and transparently, with long-term maintainability in mind.

🎯 Goals

• Be architecturally clean
• Be a framework people can reason about
• Avoid over-engineering
• Stay honest about trade-offs

📚 Documentation

Documentation will be added progressively as the framework stabilizes.

Planned docs:

• Philosophy & mental model
• Request lifecycle
• Middleware system
• Error handling
• Configuration
• MVC patterns

🧑‍💻 Motivation

Shunya is built by someone who has:

• Used Express extensively
• Felt the pain of assembling backend stacks
• Chosen clarity over cleverness

This is a learning project — but not a toy.

🪷 Why the name Shunya?

Shunya (शून्य) means zero or emptiness — not as absence, but as pure potential.

Shunya aims to give you a clean, quiet foundation from which real systems can grow.