andurel

Andurel - Rails-like Web Framework for Go

Andurel is a comprehensive web development framework for Go. It prioritizes development speed. Inspired by Ruby on Rails, it uses just enough conventions to let you build full-stack web applications incredibly fast.

Join the discord here

Platform Support

Andurel currently supports Linux and macOS only. Windows is not supported at this time.

If you'd like to help bring Windows support to Andurel, please see issue #382 - contributions are welcome!

Why Andurel?

Development speed is everything. Andurel eliminates boilerplate and lets you focus on building features:

• Instant Scaffolding - Generate complete CRUD resources with one command
• Live Reload - Hot reloading for Go, templates, and CSS with andurel run powered by Shadowfax
• Type Safety Everywhere - Bun for SQL, Templ/Vue for HTML, Go for logic
• Batteries Included — Echo, Datastar, background jobs, sessions, CSRF protection, telemetry, email support, authentication, optional extensions (docker, aws-ses, css-components)
• Two DI Modes — Choose manual wiring for simplicity or uberfx for declarative dependency injection with go.uber.org/fx
• Two Frontend Options — Server-rendered HTML with Templ + Datastar for hypermedia interactivity, or Inertia SPA with Vue 3 + Vite for a reactive single-page app
• Production Build — One command (andurel build) to compile everything: Templ, Tailwind CSS, Vite assets, and Go binary
• Just enough Convention - Convention over configuration is great to a certain point. Andurel provides just enough sensible defaults that just work and get out of your way.
• PostgreSQL-Backed - Built on PostgreSQL with River job queues, pgx driver, and UUID support

The core philosophy around resource generation in andurel, is that it should be a one-time operation that creates everything you need for a fully functional CRUD interface. After that, you can modify and extend the generated code as needed but it's yours to manage going forward.

Core Technologies

• Echo - High-performance HTTP framework
• Tailwind CSS - Utility-first CSS framework
• Bun - Type-safe SQL ORM and query builder
• Templ - Type-safe HTML templates
• Datastar - Hypermedia-driven frontend interactivity (RC6)
• River - PostgreSQL-backed background jobs and workflows
• OpenTelemetry - Built-in observability
• PostgreSQL - Powerful open-source database with pgx driver and native UUID support
• Shadowfax - Andurel-specific app runner
• go.uber.org/fx - Dependency injection framework (optional, --di uberfx)
• gonertia - Inertia.js Go adapter (optional, --inertia vue)
• Vue.js - Progressive JavaScript framework (optional, via Inertia)
• Vite - Next-generation frontend build tool (optional, via Inertia)

Quick Start

Installation

go install github.com/mbvlabs/andurel@v1.0.0-beta.4

Create Your First Project

Andurel gives you choices when creating a new project:

# Create a new project with defaults (PostgreSQL + Tailwind CSS + manual DI)
andurel new myapp

# Add extensions for additional features:
andurel new myapp -e docker              # Add Dockerfile for containerization
andurel new myapp -e aws-ses             # Add AWS SES email integration

# Choose dependency injection approach:
andurel new myapp --di uberfx            # Use uber-go/fx for declarative DI

# Choose your frontend approach:
andurel new myapp --inertia vue          # Inertia SPA with Vue 3 + Vite

# Combine options:
andurel new myapp --di uberfx --inertia vue -e docker

cd myapp

# Sync tools
andurel tool sync

# Configure environment
cp .env.example .env

# Note: you need to edit .env with your database details

# Install NPM dependencies (only if using --inertia vue)
npm install

# Apply database migrations
andurel database migrate up

# Run the development server (with live reload)
andurel run

Your app is now running on http://localhost:8080

Database Lifecycle Commands

Andurel provides commands to manage your database lifecycle:

# Create the configured database
andurel database create                    # Requires .env to be filled out with DB credentials

# Drop the configured database (prompts for confirmation)
andurel database drop
andurel database drop --force              # Allow dropping system databases

# Drop and recreate the database
andurel database nuke
andurel database nuke --force              # Allow nuking system databases

# Full rebuild: drop, recreate, migrate, and seed
andurel database rebuild
andurel database rebuild --force           # Allow rebuilding system databases
andurel database rebuild --skip-seed       # Skip seeding after migrations

Generate Your First Resource

# Create a migration and add the columns you need. Resource generation requires
# an `id` primary key (uuid/serial/bigserial/string-supported types). `created_at`
# and `updated_at` are optional but recommended.
andurel database migrate new create_products_table

# Create a complete resource with model, controller, views, and routes
andurel generate scaffold Product

This single command creates everything you need for a full CRUD interface: model, factory, controller, views (Templ or Vue), and resource routes.

CLI Commands

andurel new — Create a new project

Scaffolds a complete Andurel project with the given name.

andurel new (alias: n) [project-name] [flags]

andurel generate — Code generation

Generate models, controllers, and scaffolds from your existing database migrations.

andurel generate (alias: g) model NAME [flags]
andurel generate view (alias: v)
andurel generate controller (alias: c) NAME [action ...] [flags]
andurel generate scaffold (alias: s) NAME [flags]
andurel generate job (alias: j) NAME [flags]
andurel generate email (alias: e) NAME

generate model — Creates a model from a database migration, or updates an existing one. Fields, types, and timestamps are read from the migration automatically.

generate controller — Creates a controller for a resource. With no actions, or with any standard CRUD action (index, show, new, create, edit, update, destroy), it uses the resource templates and generates the standard CRUD controller, views, and routes. Non-CRUD actions add empty controller methods and matching empty components to views/<name>_resource.templ; custom action routes are not generated yet.

generate view — Generates Go code from .templ template files (runs templ generate).

generate scaffold — Convenience command that runs generate model + generate controller with full CRUD actions (index, show, new, create, edit, update, destroy). By default generates Templ views; use --vue for Inertia Vue SFC views.

andurel fmt — Format source files

Formats Go and Templ source files in the project.

andurel fmt (alias: f) [flags]

Runs go fmt ./..., golines -w -m 100 ., and templ fmt on views/ and email/ directories.

andurel database — Database management

Manage the full database lifecycle.

andurel database (aliases: d, db)
andurel database create
andurel database drop [--force]
andurel database nuke [--force]
andurel database rebuild [--force] [--skip-seed]
andurel database seed
andurel database migrate (aliases: m, mig)

database migrate subcommands:

andurel build — Production build

Build the application binary and compile all assets for production deployment.

andurel build [--version]

Runs Templ generation, minifies Tailwind CSS, installs NPM dependencies and builds Vite assets (if using Inertia), downloads Go dependencies, and compiles a static Linux binary.

andurel run — Development server

Starts the development server with live reload (powered by Shadowfax).

andurel run (alias: r)

andurel console — Database console

Opens an interactive database console (usql) using connection details from .env.

andurel console (alias: c)

andurel tool — Project tools and binaries

Manage CLI tools and binaries used by your project. Tools are defined in andurel.lock and downloaded to bin/.

andurel tool (alias: t)
andurel tool sync
andurel tool set-version <tool> <version>
andurel tool dblab (alias: d)
andurel tool mailpit (alias: m)

andurel extension — Project extensions

Add and list optional framework features.

andurel extension (aliases: ext, e)
andurel extension add (alias: a) [extension-name]
andurel extension list (alias: ls)

Available extensions: docker, aws-ses, css-components.

andurel llm — LLM documentation

Outputs comprehensive framework documentation for AI assistants. Supports topic-specific subcommands:

andurel llm (alias: l)
andurel llm controllers (alias: c)
andurel llm models (alias: m)
andurel llm views (alias: v)
andurel llm router (alias: r)
andurel llm hypermedia (alias: h)
andurel llm jobs (alias: j)
andurel llm config (alias: cfg)

andurel upgrade — Framework upgrade

Upgrade framework-managed files and tool versions to the latest.

andurel upgrade (alias: up) [--dry-run]

Commit or create a branch before upgrading — this command modifies files in place.

andurel doctor — Project diagnostics

Run comprehensive diagnostic checks (Go version, config, code quality, code generation).

andurel doctor (alias: doc) [--verbose]

Alias Reference

Project Structure

Andurel generates a complete project based on your chosen options. Below is the default structure, followed by what changes with each option.

Default (Manual DI + Tailwind CSS)

myapp/
├── assets/                  # Static assets (served at /assets/)
│   ├── assets.go
│   ├── css/
│   │   └── style.css       # Compiled Tailwind output
│   └── js/
│       ├── datastar_1-0-1.min.js
│       └── scripts.js
├── clients/
│   └── email/
│       └── mailpit.go       # Mailpit email client
├── cmd/
│   └── app/
│       └── main.go          # Application entry point
├── config/
│   ├── config.go            # Main config aggregator
│   ├── app.go               # Sessions, tokens, security
│   ├── auth.go              # Authentication config
│   ├── database.go          # Database connection config
│   ├── email.go             # Email configuration
│   └── telemetry.go         # Logging, tracing, metrics
├── controllers/
│   ├── controller.go        # Base controller setup
│   ├── api.go
│   ├── assets.go
│   ├── cache.go             # Cache control utilities
│   ├── confirmations.go
│   ├── pages.go
│   ├── registrations.go
│   ├── reset_passwords.go
│   └── sessions.go
├── css/
│   ├── base.css             # Tailwind CSS source input
├── database/
│   ├── database.go          # Database connection helper
│   ├── test_helper.go       # Test database setup
│   ├── migrations/          # SQL migration files (goose)
│   └── seeds/
│       └── main.go          # Database seeder
├── email/
│   ├── email.go
│   ├── base_layout.templ
│   ├── components.templ
│   ├── reset_password.templ
│   └── verify_email.templ
├── internal/
│   ├── hypermedia/          # Datastar/SSE helpers
│   │   ├── broadcaster.go
│   │   ├── core.go
│   │   ├── helpers.go
│   │   ├── signals.go
│   │   └── sse.go
│   ├── renderer/
│   │   ├── fragments.go
│   │   └── render.go        # Server-side renderer
│   ├── request/
│   │   ├── context.go
│   │   └── request.go
│   ├── routing/
│   │   ├── definitions.go
│   │   └── routes.go
│   ├── server/
│   │   └── server.go
│   └── storage/
│       ├── psql.go
│       └── queue.go
├── models/
│   ├── model.go
│   ├── errors.go
│   ├── token.go
│   ├── user.go
│   └── factories/           # Model factories for testing
│       ├── factories.go
│       ├── token.go
│       └── user.go
├── queue/
│   ├── queue.go
│   ├── jobs/
│   │   ├── send_marketing_email.go
│   │   └── send_transactional_email.go
│   └── workers/
│       ├── workers.go
│       ├── send_marketing_email.go
│       └── send_transactional_email.go
├── router/
│   ├── router.go            # Main router setup
│   ├── connect_*.go          # Route registration files
│   ├── cookies/
│   │   ├── cookies.go
│   │   └── flash.go
│   ├── middleware/
│   │   ├── middleware.go
│   │   └── auth.go
│   └── routes/
│       ├── api.go
│       ├── assets.go
│       ├── pages.go
│       └── users.go
├── services/
│   ├── authentication.go
│   ├── registration.go
│   └── reset_password.go
├── telemetry/
│   ├── telemetry.go
│   ├── options.go
│   ├── logger.go
│   ├── log_exporters.go
│   ├── metrics.go
│   ├── metric_exporters.go
│   ├── tracer.go
│   ├── trace_exporters.go
│   └── helpers.go
├── views/                    # Templ templates
│   ├── layout.templ
│   ├── head.templ
│   ├── home.templ
│   ├── bad_request.templ
│   ├── confirm_email.templ
│   ├── internal_error.templ
│   ├── login.templ
│   ├── not_found.templ
│   ├── registration.templ
│   ├── reset_password.templ
│   └── components/
├── .env.example
├── .gitignore
├── andurel.lock              # Tool version lock file
├── go.mod
└── go.sum

UberFX Mode (--di uberfx)

When using uberfx, the following files change:

The following files are removed (route registration moves into controllers):

router/connect_*.go    (connect_api_routes, connect_assets_routes,
                        connect_pages_routes, connect_sessions_routes,
                        connect_registrations_routes, connect_confirmations_routes,
                        connect_reset_passwords_routes)

Inertia Vue Mode (--inertia vue)

When using the Inertia SPA frontend, these files are added:

myapp/
├── resources/
│   └── js/
│       ├── app.ts               # Vue + Inertia app entry point
│       └── Pages/
│           └── Welcome.vue      # Home page Vue component
├── views/
│   ├── root.go.html             # Inertia root HTML shell
│   └── (no home.templ — replaced by Vue Welcome page)
├── internal/
│   └── renderer/
│       └── vite.go              # Vite dev/prod manifest resolver
├── vite.config.ts
├── package.json
├── tsconfig.json

The controllers/pages.go uses Inertia rendering instead of Templ, and cmd/app/main.go initializes the Inertia renderer. Run npm install after scaffolding.

Inertia Vue + UberFX (--di uberfx --inertia vue)

Combines the UberFX routing pattern with the Inertia frontend layer. The pages controller uses RegisterRoutes() and renders via Inertia instead of Templ.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run quality checks: go vet ./... and golangci-lint run
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Setup

git clone https://github.com/mbvlabs/andurel
cd andurel
go mod download
go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Tech Stack

Andurel is built on top of excellent open-source projects:

• Echo - High-performance HTTP router and framework
• Bun - Type-safe SQL ORM and query builder
• Templ - Type-safe Go templates
• Datastar - Hypermedia-driven frontend interactivity (RC6)
• River - Fast PostgreSQL-backed job queue and workflows
• OpenTelemetry - Observability framework for logs, traces, and metrics
• pgx - PostgreSQL driver and toolkit
• Tailwind CSS - Utility-first CSS framework
• Cobra - CLI framework

Acknowledgments

Inspired by Ruby on Rails and its philosophy that developer happiness and productivity matter. Built for developers who want to move fast without sacrificing type safety or code quality.

Sites build with Andurel

Here is a collection of sites and projects, I've built with this framework:

• MBV Blog | personal blog
• Master Golang | course platform
• Palantir | open sourced analytics platform (WIP)

If you build something cool with Andurel, let me know and I will add it to the list (or open a PR)!

Author

Created by Morten Vistisen

Feel free to reach out to me on:

• Twitter/X
• Mail

If you have any questions!