Documentation
Vodka Documentation
Learn how to build modern Go applications with Vodka using guides, examples, middleware documentation, and full-stack workflows.
Features
Why Vodka?
Vodka combines fast backend iteration with a modern full-stack workflow without the configuration overhead of heavier frameworks.
Fast backend iteration
Built-in hot reload watches your .go files and restarts instantly.
React + Vite integration
Scaffold a full-stack app with frontend and backend together.
Lightweight routing
Radix Tree router delivers fast route matching.
Auth helpers built in
Bearer auth and JWT helpers included out of the box.
Struct-tag validation
Declare validation rules and let Vodka handle the rest.
Developer-first defaults
Minimal boilerplate and sensible defaults.
Installation
Prerequisites
Make sure the following tools are installed before using Vodka:
- Go 1.24 or newer
- Node.js 20.19 or newer
- npm
go version node -v npm -v
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 this directory to your Environment Variables:
%USERPROFILE%\go\bin
Quick Start
Create a new Vodka project and start developing immediately.
vodka new my-app cd my-app vodka dev
Your application will be available at:
Demo
Project Scaffolding
Full Stack Workflow
Project Scaffolding
Vodka can generate full-stack applications with frontend and backend configured out of the box.
vodka new my-app --template react
Generated Structure
my-app/ ├── controllers/ ├── routes/ ├── frontend/ ├── main.go ├── go.mod └── vodka.config.json
Minimal API Example
Create a simple API endpoint with Vodka in just a few lines.
package main
import (
"github.com/DevanshuTripathi/vodka"
)
func main() {
app := vodka.DefaultRouter()
app.GET("/ping", func(c *vodka.Context) {
c.JSON(200, vodka.M{
"message": "pong!",
})
})
app.Run(":8080")
}Test the API
curl http://localhost:8080/ping
Response
{
"message": "pong!"
}Core Concepts
Engine
The Engine is the central router and application instance that handles requests and middleware.
app := vodka.DefaultRouter()
Context
Context provides helpers for requests, responses, JSON handling, query parameters, and middleware communication.
c.JSON(200, vodka.M{
"message": "hello",
})Middleware
Middleware allows you to run logic before and after request handlers.
app.Use(vodka.Logger())
app.Use(vodka.Recovery())
app.GET("/", handler)Custom Middleware
func Logger() vodka.HandlerFunc {
return func(c *vodka.Context) {
c.Next()
}
}Request ID Middleware
Generate a unique ID for every request and track it across logs and services.
app := vodka.DefaultRouter()
app.Use(mixers.RequestID())
app.GET("/api/users", func(c *vodka.Context) {
requestID, _ := c.Get("request-id")
c.JSON(200, vodka.M{
"request_id": requestID,
})
})Benefits
- Track requests across services
- Improve debugging
- Correlate logs easily
Validation
Validate incoming request data using struct tags before processing.
type CreateUserRequest struct {
Name string `validate:"required"`
Email string `validate:"required,email"`
}
if err := c.Validate(&req); err != nil {
return err
}Authentication
Protect routes and verify user access using middleware.
app.Use(AuthMiddleware())
app.GET("/dashboard", DashboardHandler)Authentication middleware can validate JWTs, sessions, API keys, or custom credentials before allowing access.
Templates
Start quickly with preconfigured project templates.
vodka new my-app --template react vodka new my-app --template vue vodka new my-app --template svelte
Templates include frontend tooling, routing, build configuration, and development workflows.
Template Rendering
Vodka supports Go's native html/template package for server-side rendering.
app := vodka.DefaultRouter()
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 Features
- Load templates using glob patterns
- Render dynamic data
- Works with Go's html/template
- Hot reload during development
SPA Support
Serve Single Page Applications directly from your Vodka backend.
app.Static("/", "./frontend/dist")
app.NoRoute(func(c *vodka.Context) {
c.File("./frontend/dist/index.html")
})This enables React, Vue, Svelte, and other SPA frameworks to work seamlessly with backend routes.
Additional Information
Performance
Vodka uses a Radix Tree router optimized for fast route matching, low memory usage, and efficient middleware execution.
Production Build
Build your frontend with Vite and deploy the backend using Vodka for a complete production-ready setup.
Philosophy
Fast development workflow, minimal boilerplate, strong developer experience, and practical defaults.
Contributing
Contributions, issues, and feature requests are welcome. Feel free to open issues or submit pull requests.
License
Vodka is released under the MIT License and is free to use in personal and commercial projects.
Community
Join discussions, share feedback, and help improve the Vodka ecosystem.
Roadmap
Upcoming improvements planned for the Vodka ecosystem.