Vegaa

A modern Node.js framework that makes backend development simple and fast

📚 Full Documentation → | 🚀 Quick Start | 💡 Examples | 🔗 Express Compatibility

---

📖 Table of Contents

• Why Vegaa?
• Installation
• Quick Start
• Core Concepts
  • Automatic Parameter Injection
  • Smart Parameter Grouping
• Express Middleware Compatibility
• Middleware System
  • Global Middleware
  • Route-Specific Middleware
• Built-in Plugins
• Features
• Performance
• CLI & Templates
• Documentation
• Links & Resources

---

🎯 Why Vegaa?

Vegaa makes Node.js backend development simpler without sacrificing performance.

The Problem with Traditional Frameworks

In Express, you constantly repeat yourself:

app.get('/user/:id', (req, res) => {
  const user = req.user           // Extract from req
  const id = req.params.id        // Extract from params
  res.json({ user, id })          // Manually send response
})

The Vegaa Solution

Just declare what you need — Vegaa handles the rest:

route('/user/:id').get((user, id) => ({ user, id }))

No manual extraction. No req/res juggling. Just clean, readable code.

Express Compatibility Without Compromise

Need Express middleware? Use it seamlessly:

enableExpressCompat(vegaa)
vegaa.useExpressMiddleware(helmet())
route('/users/:id').get((id) => ({ userId: id }))  // Still clean!

Vegaa's DNA stays intact — minimalism and context integration, with Express middleware support when you need it.

---

📦 Installation

📚 Installation Guide →

Option 1: Start with Templates (Recommended)

Get started instantly with pre-configured templates:

npx vegaa-cli create my-app
# or
npx vegaa create my-app

Choose from 5 production-ready templates! See CLI section for details.

Option 2: Manual Installation

npm install vegaa

Requirements: Node.js 18 or higher

---

🚀 Quick Start

📚 Full Getting Started Guide →

Create your first API in under 30 seconds:

import { vegaa, route } from 'vegaa'

// Define a simple route
route('/ping').get(() => ({ message: 'pong' }))

// Start the server
await vegaa.startVegaaServer()

Visit http://localhost:4000/ping and you'll see:

{
  "message": "pong"
}

That's it! You just built your first API endpoint.

---

💡 Core Concepts

📚 Learn more about Core Concepts →

1. Automatic Parameter Injection

Vegaa automatically provides values based on parameter names:

// Route parameters are automatically available
route('/users/:id').get((id) => {
  return { userId: id }
})

// Multiple parameters work too
route('/users/:userId/posts/:postId').get((userId, postId) => {
  return { userId, postId }
})

How it works: Vegaa reads your function parameters and injects the matching values automatically.

2. Smart Parameter Grouping

For routes with request bodies (POST, PUT, PATCH), Vegaa groups data to avoid naming conflicts:

route('/users/:id').post((params, body) => {
  return {
    userId: params.id,      // Route parameter
    userData: body          // Request body
  }
})

• params → Route parameters (:id, :postId, etc.)
• body → Request body data
• query → Query string parameters
• Any middleware values you define

---

🔗 Middleware System

📚 Learn more about Middleware →

Middleware is the heart of Vegaa — it creates reusable logic that flows through your app.

Global Middleware

Runs for all routes in your application:

// Authentication middleware
vegaa.middleware(async () => {
  return { user: { id: 1, name: 'John' } }
})

// Logging middleware
vegaa.middleware((pathname) => {
  console.log('Request:', pathname)
})

// Now ALL routes have access to 'user'
route('/profile').get((user) => {
  return { message: `Welcome ${user.name}!` }
})

Route-Specific Middleware

Runs only for specific routes:

route('/admin/:id')
  .middleware((params) => {
    // Only runs for /admin/:id
    if (params.id !== '1') {
      throw new Error('Unauthorized')
    }
    return { access: 'granted' }
  })
  .get((params, access) => {
    return { adminId: params.id, access }
  })

Chaining Middleware

Middleware can build on each other — values flow automatically:

vegaa.middleware([
  async () => ({ user: { id: 1, name: 'Bob' } }),
  async (user) => ({ greeting: `Hello ${user.name}` }),
  async (user, greeting) => ({ log: `${greeting} [User ${user.id}]` })
])
route('/welcome')
  .middleware(async (user, greeting) => ({ log: `${greeting} [User ${user.id}]` }))
  .middleware(async (log) => ({ timestamp: new Date().toISOString() }))
  .get((greeting, log, timestamp) => ({ greeting, log, timestamp }))

Key Concept: Each middleware receives values from previous middleware automatically. Think of it as a pipeline where data flows downstream.

---

🔌 Built-in Plugins

📚 Learn more about Plugins →

Vegaa comes with powerful plugins that are loaded by default:

Default Plugins (Pre-loaded)

// These are automatically available:
// ✅ jsonPlugin - JSON response helpers
// ✅ bodyParserPlugin - Request body parsing
// ✅ httpClientPlugin - makeRequest() for external APIs

Optional Plugins

CORS Plugin

Enable cross-origin requests:

import { vegaa, corsPlugin } from 'vegaa'

await vegaa.plugin(corsPlugin)

Static File Plugin

Serve HTML, CSS, JavaScript, images:

import { vegaa, staticPlugin } from 'vegaa'

await vegaa.plugin(staticPlugin, {
  root: './public',              // Folder with your files
  prefix: '/assets',             // URL prefix (optional)
  cacheControl: 'public, max-age=3600'
})

// Files in ./public/ → http://localhost:4000/assets/*

Creating Custom Plugins

const loggerPlugin = {
  name: 'logger',
  version: '1.0.0',
  async register(app) {
    app.middleware((pathname) => {
      console.log('→', pathname)
    })
  }
}

await vegaa.plugin(loggerPlugin)

---

✨ Features

🔌 Express Middleware Compatibility

📚 Learn more about Express Compatibility →

Use any Express middleware with Vegaa's minimal API — no compromises:

import { vegaa, route, enableExpressCompat } from 'vegaa'
import helmet from 'helmet'
import cors from 'cors'

// Enable Express compatibility
enableExpressCompat(vegaa)

// Use Express middleware seamlessly
vegaa.useExpressMiddleware(helmet())
vegaa.useExpressMiddleware(cors())
vegaa.useExpressMiddleware('/api', someMiddleware)

// Your Vegaa routes work exactly as before
route('/users/:id').get((id) => ({ userId: id }))

Key Benefits:

• ✅ Use existing Express middleware (helmet, cors, morgan, etc.)
• ✅ Maintains Vegaa's minimal API — no req/res juggling
• ✅ Express middleware values flow into Vegaa context automatically
• ✅ Path-specific middleware support
• ✅ Error middleware automatically handled

Example with Real Express Middleware:

import { vegaa, route, enableExpressCompat } from 'vegaa'
import helmet from 'helmet'
import cors from 'cors'
import morgan from 'morgan'

enableExpressCompat(vegaa)

// Security headers
vegaa.useExpressMiddleware(helmet())

// CORS
vegaa.useExpressMiddleware(cors({ origin: 'https://example.com' }))

// Logging
vegaa.useExpressMiddleware(morgan('combined'))

// Your routes remain clean and minimal
route('/api/users').get(() => ({ users: [] }))

Perfect for: Migrating from Express, using popular Express middleware, maintaining existing middleware investments.

---

🔥 Response Types

JSON (Default)

route('/data').get(() => ({ status: 'success', data: [1, 2, 3] }))

HTML

import { route, html } from 'vegaa'

route('/').get(() => html('<h1>Welcome!</h1>'))

Text

import { route, text } from 'vegaa'

route('/health').get(() => text('OK'))

🌐 HTTP Client (External API Calls)

Built-in HTTP client powered by Undici:

route('/posts').get(async (makeRequest) => {
  const data = await makeRequest()
    .url('https://api.example.com/posts/1')
    .get()
    .json()
  
  return data
})

// POST request
route('/create').post(async (makeRequest, body) => {
  return await makeRequest()
    .url('https://api.example.com/posts')
    .post()
    .headers({ 'Content-Type': 'application/json' })
    .body(body)
    .json()
})

Available Methods: .get(), .post(), .put(), .delete(), .headers(), .body(), .json(), .text(), .buffer()

🎁 Custom Decorators

Add custom values available everywhere:

vegaa.decorate('version', '1.0.0')
vegaa.decorate('db', myDatabaseConnection)

route('/info').get((version) => ({ version }))

⚙️ Multi-Core Cluster Mode

Use all CPU cores automatically:

await vegaa.startVegaaServer({
  port: 4000,
  cluster: true  // Enable multi-core mode
})

---

🎓 Complete Example

Here's everything working together with route chaining:

import { vegaa, route, html } from 'vegaa'

// Global auth middleware
vegaa.middleware(async () => ({
  user: { id: 1, name: 'Alice' }
}))

// Multiple routes with method chaining
route('/users/:id')
  .get((id, user) => ({ viewerId: user.id, profileId: id }))
  .post((params, body, user) => ({
    created: true,
    data: body,
    authorId: user.id
  }))
  .delete((id) => ({ deleted: true, userId: id }))

// External API call
route('/external').get(async (makeRequest) => {
  return await makeRequest()
    .url('https://api.example.com/data')
    .get()
    .json()
})

// HTML page
route('/').get(() => html('<h1>Welcome to Vegaa!</h1>'))

await vegaa.startVegaaServer({ port: 4000 })

---

🚀 Performance

Vegaa is built for speed while maintaining clean code.

Benchmark Results

Test Environment: MacBook M3, macOS 26, Node v24.3 Tool: autocannon -c 100 -d 300 http://localhost:4000/ping

Framework	Requests/sec	Latency	Notes
Vegaa (Cluster)	112,774	0.09ms	Multi-core
Vegaa (Single)	91,488	0.97ms	Single-core
Fastify	79,852	1.01ms	Industry standard
Express	54,339	1.06ms	Most popular

Visual Comparison

Express        ████████████████       54k req/s
Fastify        ████████████████████   79k req/s
Vegaa          ████████████████████████ 91k req/s
Vegaa Cluster  ████████████████████████████ 112k req/s

Result: Vegaa is 25-30% faster than Fastify and 2x faster than Express.

Technology Stack

Component	Technology	Purpose
HTTP Server	Node.js http	Native, low-overhead
Routing	find-my-way	Fast path matching
JSON	fast-json-stringify	Optimized serialization
HTTP Client	undici	High-performance requests
Scaling	Node.js cluster	Multi-core support

---

🧰 CLI & Templates

Vegaa CLI provides 5 production-ready templates to kickstart your project:

Installation & Usage

# Install globally
npm install -g vegaa-cli

# Create new project
vegaa create my-app
# or
npx vegaa-cli create my-app

5 Available Templates

Template	Description	Live Demos
🌱 Minimal	Basic /ping server	StackBlitz • CodeSandbox
🔧 Middleware	Middleware + Dashboard demo	StackBlitz • CodeSandbox
🚀 CRUD	JWT Auth + Swagger Docs	StackBlitz • CodeSandbox
🏗️ Full-Fledge	Production setup (monitoring, admin, etc.)	StackBlitz • CodeSandbox
🐳 Docker	Containerized setup	StackBlitz • CodeSandbox

Try instantly: Launch on your preferred platform — StackBlitz or CodeSandbox — right in the browser, no installation needed!

Quick Commands

cd my-app
npm install
npm start        # Start development server
npm run build    # Build for production

📦 View CLI Documentation

---

📚 API Reference

Creating Routes

route('/path')
  .get(handler)
  .post(handler)
  .put(handler)
  .delete(handler)

Adding Middleware

vegaa.middleware(middlewareFn)              // Global
route('/path').middleware(middlewareFn)     // Route-specific

Express Middleware Compatibility

import { enableExpressCompat } from 'vegaa'
enableExpressCompat(vegaa)

vegaa.useExpressMiddleware(middleware)           // Global
vegaa.useExpressMiddleware('/path', middleware)  // Path-specific

Starting Server

await vegaa.startVegaaServer({
  port: 4000,
  cluster: false
})

---

🗺️ Roadmap

Phase	Features	Status
Core Engine	Context, cluster, plugins	✅ Complete
Dev Tools	CLI, validation, caching	🚧 In Progress
Advanced	WebSockets, Redis, Streaming	🧠 Planned

---

🤝 Contributing

Contributions welcome! Fork the repo, make changes, and submit a PR.

Need help with: Documentation, bug fixes, performance improvements, new plugins

Open an Issue | View Contributing Guide

---

👨‍💻 Author

Sunny Ghodeswar Senior Full-Stack Developer • Pune, India 🇮🇳

GitHub • npm

---

📜 License

MIT License — Free for personal and commercial use

---

📚 Documentation

📖 Visit the Full Documentation Website →

The documentation includes:

• 📘 Getting Started Guide
• 💡 Core Concepts & Examples
• 🔧 Complete API Reference
• 🎯 Interactive Examples with Stackblitz
• 🚀 Advanced Features & Best Practices

---

🔗 Links & Resources

• ⭐ GitHub Repository - Star us!
• 📦 npm Package - Install Vegaa
• 📚 Documentation Website - Full documentation with examples
• 🧰 CLI Tool - Project templates
• 🐛 Report Issues - Bug reports & features

---

⚡ Vegaa — Named for velocity. Engineered for developers.

Built with ❤️ by developers, for developers.

Get Started | Documentation | View Templates | Star on GitHub ⭐