Vodka

__/\\\________/\\\_______/\\\\\_______/\\\\\\\\\\\\_____/\\\________/\\\_____/\\\\\\\\\____        
 _\/\\\_______\/\\\_____/\\\///\\\____\/\\\////////\\\__\/\\\_____/\\\//____/\\\\\\\\\\\\\__       
  _\//\\\______/\\\____/\\\/__\///\\\__\/\\\______\//\\\_\/\\\__/\\\//______/\\\/////////\\\_      
   __\//\\\____/\\\____/\\\______\//\\\_\/\\\_______\/\\\_\/\\\\\\//\\\_____\/\\\_______\/\\\_     
    ___\//\\\__/\\\____\/\\\_______\/\\\_\/\\\_______\/\\\_\/\\\//_\//\\\____\/\\\\\\\\\\\\\\\_    
     ____\//\\\/\\\_____\//\\\______/\\\__\/\\\_______\/\\\_\/\\\____\//\\\___\/\\\/////////\\\_   
      _____\//\\\\\_______\///\\\__/\\\____\/\\\_______/\\\__\/\\\_____\//\\\__\/\\\_______\/\\\_  
       ______\//\\\__________\///\\\\\/_____\/\\\\\\\\\\\\/___\/\\\______\//\\\_\/\\\_______\/\\\_ 
        _______\///_____________\/////_______\////////////_____\///________\///__\///________\///__

A modern Go web framework focused on developer experience, full-stack workflow, and rapid iteration.

Vodka is a lightweight and high-performance HTTP framework for Go that combines clean routing, middleware chaining, authentication utilities, validation support, and a powerful CLI for building modern full-stack applications.

Unlike traditional Go frameworks that focus only on request handling, Vodka heavily emphasizes developer experience and fast iteration.

Demo

Project Scaffolding

CLI Demo

Full Stack Workflow

Workflow

Features
Why Vodka
Prerequisites
Installation
Quick Start
Generated Backend Structure
Minimal API Example
Using Vodka for APIs
Core Concepts
Middleware
Validation
Authentication
SPA Support
Production Build
Roadmap
Contributing
License

Features

Feature	Included
Radix Tree Routing	✅
Middleware Chaining	✅
Route Groups	✅
JSON Binding	✅
Request Validation	✅
JWT Validation Helpers	✅
Bearer Auth Middleware	✅
Vite + React Scaffolding	✅
SPA Serving	✅
Panic Recovery Middleware	✅
Logger Middleware	✅
CORS Middleware	✅
Context Storage	✅
HTML Template Rendering	✅

Why Vodka?

Vodka combines:

⚡ Fast backend iteration
⚛️ React + Vite integration
🧩 Lightweight routing
🔐 Authentication helpers
✅ Validation support
🚀 Developer-first workflow

without requiring heavy configuration or excessive boilerplate.

Prerequisites

Make sure the following tools are installed before using Vodka:

Go 1.24+
Node.js 20.19+ or newer
npm

Verify installation:

go version
node -v
npm -v

Installation

Install the Vodka CLI

go install github.com/DevanshuTripathi/vodka/cmd/vodka@latest

Make sure your Go bin directory is added to your system

PATH

Linux / macOS

export PATH=$PATH:$(go env GOPATH)/bin

Windows

Add the following directory to Environment Variables:

%USERPROFILE%\go\bin

Quick Start

Create a Full-Stack App

vodka create <project-name> [location] [--minimal]

Basic usage:

vodka create my-app

You can also specify a target directory to scaffold the project into:

vodka create my-app /path/to/parent-dir

The project will be created at

<location>/<name>

(e.g.

/path/to/parent-dir/my-app

). If no location is provided, the current directory is used.

vodka create my-app --minimal
vodka create my-app /path/to/dir --minimal

This generates:

A Go backend powered by Vodka
A React + Vite frontend
Preconfigured development workflow
SPA support for production deployments

Generated Project Structure

my-app/
├── controllers/
├── routes/
├── frontend/
├── main.go
├── go.mod
└── vodka.config.json

Install Frontend Dependencies

After scaffolding the project, install frontend dependencies manually:

cd my-app

cd frontend
npm install

cd ..

Start Development Mode

vodka run dev

This starts:

Vite frontend dev server
Vodka backend server
Concurrent frontend/backend workflow

Generated Backend Structure

Vodka organizes backend code into simple and clean layers.

backend/
├── controllers/
│   └── ping.go
├── routes/
│   └── routes.go
├── main.go
└── go.mod

controllers/

Contains request handlers and business logic.

func Pong(c *vodka.Context) {
	c.String(200, "Pong!")
}

routes/

Registers API routes.

app.GET("/ping", controllers.Pong)

main.go

Bootstraps the Vodka engine and middleware configuration.

app := vodka.DefaultRouter()

routes.Setup(app)

app.Run(":8080")

Minimal API Example

package main

import (
	"log"

	"github.com/DevanshuTripathi/vodka"
)

func main() {
	app := vodka.DefaultRouter()

	app.GET("/ping", func(c *vodka.Context) {
		c.JSON(200, vodka.M{
			"message": "pong!",
		})
	})

	if err := app.Run(":8080"); err != nil {
		log.Fatal(err)
	}
}

Test the API

curl http://localhost:8080/ping

Response:

{
  "message": "pong!"
}

Using Vodka for APIs

Create a Go Module

mkdir backend-app

cd backend-app

go mod init app

go get github.com/DevanshuTripathi/vodka

Run Backend Server

vodka

Vodka automatically:

Watches
```
.go
```
files
Rebuilds your backend
Restarts the server instantly

Core Concepts

Engine

vodka.Engine

is the central router and application instance.

It uses a Radix Tree-based routing architecture for fast request matching and low overhead.

app := vodka.DefaultRouter()

Context

vodka.Context

wraps Go's

http.Request

and

http.ResponseWriter

into a clean and ergonomic API.

JSON Response

c.JSON(200, vodka.M{
	"message": "hello",
})

Query Parameters

name := c.Query("name")

URL Parameters

id := c.Param("id")

Bind JSON

var user User
c.BindJSON(&user)

Error Handling

c.Error(400, errors.New("invalid request"))

Middleware

Vodka middleware is simply a

vodka.HandlerFunc

func(*vodka.Context)

Middlewares can:

Modify requests
Attach values to context
Authenticate users
Log requests
Recover from panics
Handle errors

Middlewares are registered using:

app.Use(...)

or:

group.Use(...)

How Middleware Works

Each incoming request is wrapped in a

*vodka.Context

and the framework builds a handler chain.

The chain includes:

Group middlewares
Route middlewares
Final route handler

c.Next()

continues execution to the next middleware or handler.

If you omit

c.Next()

, the request chain stops immediately.

Custom Middleware Example

func RequestTimer() vodka.HandlerFunc {
	return func(c *vodka.Context) {
		start := time.Now()

		c.Next()

		latency := time.Since(start)

		log.Printf(
			"[RequestTimer] %s %s %v",
			c.Request.Method,
			c.Request.URL.Path,
			latency,
		)
	}
}

func main() {
	app := vodka.DefaultRouter()

	app.Use(
		vodka.Logger(),
		vodka.Recovery(),
		vodka.ErrorHandler(),
	)

	app.Use(RequestTimer())

	api := app.Group("/api", AdminOnly())

	api.GET("/dashboard", func(c *vodka.Context) {
		userRole, _ := c.Get("user_role")

		c.JSON(200, vodka.M{
			"role": userRole,
		})
	})
}

Request ID Middleware

Track requests across your logs using automatic request ID generation. Every request gets a unique ID that's automatically added to response headers and stored in the context.

app := vodka.DefaultRouter()

// Add request ID middleware — generates unique ID for each request
app.Use(mixers.RequestID())

app.GET("/api/users", func(c *vodka.Context) {
	requestID, _ := c.Get("request-id")
	log.Printf("[%v] Fetching users", requestID)
	c.JSON(200, vodka.M{"users": []string{"Alice", "Bob"}})
})

// Client receives: X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Custom Header Name

Use a different header name if needed (context key is always

"request-id"

app.Use(mixers.RequestIDWithHeader("X-Correlation-ID"))

Template Rendering

Vodka supports Go's native

html/template

package for server-side HTML rendering.

Basic Usage

app := vodka.DefaultRouter()

// Load all templates from templates folder
app.LoadHTMLGlob("templates/*.html")

app.GET("/user", func(c *vodka.Context) {
    c.HTML(200, "user.html", vodka.M{
        "name": "John Doe",
        "email": "john@example.com",
    })
})

## Template Files

Create a templates/user.html file:

```html
<!DOCTYPE html>
<html>
<head>
    <title>User Profile</title>
</head>
<body>
    <h1>Hello, {{.name}}!</h1>
    <p>Email: {{.email}}</p>
</body>
</html>  ```

## Methods
LoadHTMLGlob(pattern string) error - Load templates using glob pattern

LoadHTMLFiles(files ...string) error - Load specific template files

c.HTML(code int, name string, data interface{}) - Render HTML template

Templates work seamlessly with Vodka's hot-reload in development mode.


# Validation

Vodka supports request validation using struct tags.

```go
type User struct {
	Email    string `validate:"required,email"`
	Password string `validate:"min=8"`
}

Authentication

Vodka includes built-in Bearer authentication middleware and JWT validation helpers.

You can also provide custom validation logic:

app.Use(vodka.BearerAuth(contextKey, func(token string) (any, bool) {
	return validateToken(token)
}))

Full-Stack SPA Support

Projects generated using

vodka create

come with SPA serving preconfigured.

app.ServeSPA("./frontend/dist")

If a route does not match an API endpoint, Vodka automatically serves the frontend application.

This enables seamless React Router support in production.

Performance

Vodka uses a Radix Tree router optimized for:

Fast route matching
Low memory overhead
Efficient middleware execution

Production Build

Build Frontend

cd frontend
npm run build

Build Backend

vodka

Philosophy

Vodka is designed around a few core ideas:

Fast development workflow
Minimal boilerplate
Strong developer experience
Clean APIs
Modern full-stack integration
Practical defaults

Roadmap

More middleware packages
Enhanced validation system
Improved benchmarking suite
Expanded CLI tooling
Testing utilities

Contributing

Contributions, issues, and feature requests are welcome.

If you find bugs or have suggestions, feel free to open an issue or submit a pull request.

License

MIT License