README
¶
Twine
A full-stack Go web framework for building server-side rendered applications with Alpine.js.
Features
- Hierarchical Router: Composable routers with middleware inheritance
- Alpine.js-First: Built-in support for Alpine Ajax requests and responses
- Template System: Go's stdlib
html/templatewith component-based architecture - Database Layer: GORM integration with migrations and generic CRUD stores
- Authentication: JWT token generation and validation middleware
- Error Handling: Structured errors with severity levels and stack traces
- Logging: Configurable logging with multiple severity levels
- Static Assets: Embedded static file serving
Installation
Install CLI Tool (Recommended)
go install github.com/cstone/twine/cmd/twine@latest
Or Install Framework Only
go get github.com/cstone/twine
Quick Start
Using the CLI (Easiest)
Create a new project in seconds:
# Create a new project
twine init my-app
# Navigate to project directory
cd my-app
# Run the application
go run main.go
Visit http://localhost:3000 to see your app!
CLI Options
# Custom module path
twine init my-app --module github.com/myuser/my-app
# Custom port
twine init my-app --port 8080
# Minimal setup (no example pages)
twine init my-app --no-examples
# View all options
twine init --help
Manual Setup
If you prefer to set up manually:
1. Create a new project
package main
import (
"context"
"os"
"os/signal"
"syscall"
"github.com/cstone/twine/router"
"github.com/cstone/twine/kit"
"github.com/cstone/twine/server"
"github.com/cstone/twine/template"
)
func main() {
// Load templates
template.LoadTemplates("templates/**/*.html")
// Create router
r := router.NewRouter("")
r.Get("/", Index)
// Initialize server
mux := r.InitializeAsRoot()
srv := server.NewServer(":3000", mux)
srv.Start()
// Graceful shutdown
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
srv.AwaitShutdown(ctx)
}
func Index(k *kit.Kit) error {
data := map[string]any{
"Title": "Welcome to Twine",
}
return k.RenderTemplate("index", data)
}
2. Create templates
<!-- templates/pages/index.html -->
{{define "index"}}
<!DOCTYPE html>
<html>
<head>
<title>{{.Title}}</title>
</head>
<body>
<h1>{{.Title}}</h1>
{{template "button" .}}
</body>
</html>
{{end}}
<!-- templates/components/button.html -->
{{define "button"}}
<button>Click me</button>
{{end}}
3. Configure environment
# .env
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_NAME=myapp
DB_SSLMODE=disable
DB_TIMEZONE=UTC
LOGGER_LEVEL=info
LOGGER_OUTPUT=stdout
LOGGER_ERROR_OUTPUT=stderr
AUTH_SECRET=your-secret-key-here
Core Concepts
Router
The router provides hierarchical routing with middleware inheritance:
r := router.NewRouter("")
// Add middleware
r.Use(middleware.LoggingMiddleware())
// Create sub-router
api := router.NewRouter("/api")
api.Use(middleware.JWTMiddleware())
// Register routes
api.Get("/users", ListUsers)
api.Post("/users", CreateUser)
api.Get("/users/{id}", GetUser)
api.Put("/users/{id}", UpdateUser)
api.Delete("/users/{id}", DeleteUser)
// Mount sub-router
r.Sub(api)
Kit
The Kit wraps http.ResponseWriter and *http.Request for convenient access:
func Handler(k *kit.Kit) error {
// Decode request body
var payload UserPayload
if err := k.Decode(&payload); err != nil {
return err
}
// Get path parameters
id := k.PathValue("id")
// Get context values
userID := k.GetContext("user")
// Return JSON response
return k.JSON(200, map[string]any{
"message": "Success",
})
}
Templates
Templates use Go's stdlib html/template:
// Load templates
template.LoadTemplates("templates/**/*.html")
// Render full page
func Index(k *kit.Kit) error {
return k.RenderTemplate("index", data)
}
// Render partial (for Ajax)
func StatsPartial(k *kit.Kit) error {
return k.RenderPartial("stats-card", stats)
}
// Auto-detect Ajax requests
func Dashboard(k *kit.Kit) error {
// Automatically renders partial if X-Alpine-Request header is present
return k.Render("dashboard", data)
}
Database
GORM integration with migrations and generic CRUD stores:
// Define model
type User struct {
model.BaseModel `gorm:"embedded"`
Name string
Email string
}
// Register migration
func init() {
database.RegisterMigration(
database.NewMigrationBuilder().
Model(&User{}).
Name("User").
Build(),
)
}
// Use CRUD store
store := store.NewCRUDStore[User](database.GORM())
users, err := store.List()
user, err := store.Get(id)
err = store.Create(user)
err = store.Update(user)
err = store.Delete(id)
Middleware
Create custom middleware:
func CustomMiddleware() middleware.Middleware {
return func(next kit.HandlerFunc) kit.HandlerFunc {
return func(k *kit.Kit) error {
// Do something before
err := next(k)
// Do something after
return err
}
}
}
Built-in middleware:
LoggingMiddleware(): Request loggingTimeoutMiddleware(duration): Request timeoutsJWTMiddleware(): JWT validation
Authentication
JWT token generation and validation:
// Generate token
token, err := auth.NewToken(userID, email)
// Validate token (done automatically by JWTMiddleware)
userID, err := auth.ParseToken(tokenString)
// Hash password
hash, err := auth.HashPassword(password)
// Verify password
creds := auth.Credentials{Email: email, Password: password}
err := creds.Authenticate(hashedPassword)
Error Handling
Structured errors with custom handlers:
// Use predefined errors
return errors.ErrNotFound
// Wrap errors
return errors.ErrDatabaseRead.Wrap(err)
// Add context
return errors.ErrDatabaseRead.Wrap(err).WithValue(user)
// Custom error handler
kit.UseErrorHandler(func(k *kit.Kit, err error) {
if e, ok := err.(*errors.Error); ok {
k.RenderTemplate("error", e)
}
})
Alpine.js Integration
Twine is designed to work seamlessly with Alpine.js and Alpine Ajax:
<!-- Full page request -->
<a href="/dashboard">Dashboard</a>
<!-- Alpine Ajax partial request -->
<button x-target="stats" action="/stats">Refresh Stats</button>
<div id="stats">
{{template "stats-card" .}}
</div>
func Stats(k *kit.Kit) error {
stats := getStats()
// Automatically returns partial for Ajax requests
return k.Render("stats-card", stats)
}
Configuration
Configuration is loaded from environment variables and .env files:
cfg := config.Get()
// Database config
dsn := cfg.Database.DSN()
// Logger config
level := cfg.Logger.Level
// Auth config
secret := cfg.Auth.SecretKey
Project Structure
myapp/
├── main.go
├── .env
├── templates/
│ ├── pages/
│ │ └── index.html
│ ├── components/
│ │ └── button.html
│ └── layouts/
│ └── base.html
├── models/
│ └── user.go
├── handlers/
│ └── user.go
├── public/
│ └── assets/
│ ├── css/
│ └── js/
└── migrations/
└── migrations.go
License
MIT
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Documentation
¶
Index ¶
- Constants
- Variables
- func Asset(name string) string
- func Config() *config.Config
- func DB() *gorm.DB
- func FileServerHandler() http.Handler
- func FuncMap() template.FuncMap
- func GetTemplates() *template.Template
- func Handler(h HandlerFunc) http.HandlerFunc
- func HashPassword(password string) (string, error)
- func LoadTemplates(patterns ...string) error
- func Logger() *logger.Logger
- func NewMigrationBuilder() *database.MigrationBuilder
- func NotFoundHandler() http.HandlerFunc
- func ParseToken(tokenString string) (string, error)
- func RegisterMigration(m *database.Migration)
- func RegisterMigrations(ms ...*database.Migration)
- func Reload(patterns ...string) error
- func SetAssetsFS(fs embed.FS)
- func SetTemplates(tmpl *template.Template)
- func UseErrorHandler(h ErrorHandlerFunc)
- type AuthConfig
- type BaseModel
- type CRUDStore
- type CRUDStoreInterface
- type Credentials
- type DatabaseConfig
- type ErrSeverity
- type Error
- type ErrorBuilder
- type ErrorHandlerFunc
- type HandlerFunc
- type Kit
- type LogLevel
- type LoggerConfig
- type Middleware
- type Migration
- type Polymorphic
- type Router
- type Seeder
- type Server
- type Token
Constants ¶
HTTP method constants for route registration.
const ( LogTrace = config.LogTrace LogDebug = config.LogDebug LogInfo = config.LogInfo LogWarn = config.LogWarn LogError = config.LogError LogCritical = config.LogCritical )
Log level constants.
const ( ErrMinor = errors.ErrMinor ErrError = errors.ErrError ErrCritical = errors.ErrCritical )
Error severity constants.
const ( AssetsPath = public.AssetsPath PublicPath = public.PublicPath )
Public asset path constants.
Variables ¶
var ( // General errors ErrNotFound = errors.ErrNotFound ErrDecodeJSON = errors.ErrDecodeJSON ErrDecodeForm = errors.ErrDecodeForm // Database errors (most common) ErrDatabaseRead = errors.ErrDatabaseRead ErrDatabaseWrite = errors.ErrDatabaseWrite ErrDatabaseUpdate = errors.ErrDatabaseUpdate ErrDatabaseDelete = errors.ErrDatabaseDelete ErrDatabaseObjectNotFound = errors.ErrDatabaseObjectNotFound ErrDatabaseConn = errors.ErrDatabaseConn ErrDatabaseMigration = errors.ErrDatabaseMigration // Auth errors (most common) ErrAuthInvalidToken = errors.ErrAuthInvalidToken ErrAuthExpiredToken = errors.ErrAuthExpiredToken ErrAuthInvalidCredentials = errors.ErrAuthInvalidCredentials ErrInsufficientPermissions = errors.ErrInsufficientPermissions ErrAuthMissingHeader = errors.ErrAuthMissingHeader ErrHashPassword = errors.ErrHashPassword ErrGenerateToken = errors.ErrGenerateToken // API errors (most common) ErrAPIRequestPayload = errors.ErrAPIRequestPayload ErrAPIObjectNotFound = errors.ErrAPIObjectNotFound ErrAPIIDMismatch = errors.ErrAPIIDMismatch ErrAPIPathValue = errors.ErrAPIPathValue ErrAPIRequestContentType = errors.ErrAPIRequestContentType // Server errors ErrListenAndServe = errors.ErrListenAndServe ErrShutdownServer = errors.ErrShutdownServer )
Common predefined errors for typical CRUD applications. For specialized errors, import pkg/errors directly.
var AssetsFS = &public.AssetsFS
AssetsFS should be set by the user application using //go:embed.
Example in user's code:
//go:embed assets
var AssetsFS embed.FS
func init() {
twine.AssetsFS = AssetsFS
}
Functions ¶
func FileServerHandler ¶
FileServerHandler returns an HTTP handler for serving embedded static files.
func GetTemplates ¶
GetTemplates returns the current template instance.
func Handler ¶
func Handler(h HandlerFunc) http.HandlerFunc
Handler converts a Kit.HandlerFunc to an http.HandlerFunc.
func HashPassword ¶
HashPassword hashes a password using bcrypt.
func LoadTemplates ¶
LoadTemplates loads all templates from the given glob patterns.
func NewMigrationBuilder ¶
func NewMigrationBuilder() *database.MigrationBuilder
NewMigrationBuilder creates a new MigrationBuilder instance.
func NotFoundHandler ¶
func NotFoundHandler() http.HandlerFunc
NotFoundHandler returns a handler for 404 errors.
func ParseToken ¶
ParseToken validates and parses a JWT token, returning the user ID.
func RegisterMigration ¶
RegisterMigration adds a migration to the database.
func RegisterMigrations ¶
RegisterMigrations adds multiple migrations to the database.
func SetAssetsFS ¶
SetAssetsFS sets the embedded filesystem for static assets.
func SetTemplates ¶
SetTemplates allows users to set a custom template instance.
func UseErrorHandler ¶
func UseErrorHandler(h ErrorHandlerFunc)
UseErrorHandler sets a custom error handler for all Kit handlers.
Types ¶
type AuthConfig ¶
type AuthConfig = config.AuthConfig
AuthConfig holds authentication configuration.
type CRUDStoreInterface ¶
type CRUDStoreInterface[T any] = database.CRUDStoreInterface[T]
CRUDStoreInterface defines the interface for CRUD operations.
type Credentials ¶
type Credentials = auth.Credentials
Credentials holds user authentication credentials.
type DatabaseConfig ¶
type DatabaseConfig = config.DatabaseConfig
DatabaseConfig holds database connection settings.
type ErrSeverity ¶
type ErrSeverity = errors.ErrSeverity
ErrSeverity represents the severity level of an error.
type ErrorBuilder ¶
type ErrorBuilder = errors.ErrorBuilder
ErrorBuilder provides a fluent interface for building errors.
func NewErrorBuilder ¶
func NewErrorBuilder() *ErrorBuilder
NewErrorBuilder creates a new error builder for custom errors.
type ErrorHandlerFunc ¶
type ErrorHandlerFunc = kit.ErrorHandlerFunc
ErrorHandlerFunc is the signature for custom error handlers.
type HandlerFunc ¶
type HandlerFunc = kit.HandlerFunc
HandlerFunc is the signature for Twine handlers that return errors.
func ApplyMiddlewares ¶
func ApplyMiddlewares(h HandlerFunc, middlewares ...Middleware) HandlerFunc
ApplyMiddlewares chains multiple middlewares together.
type LoggerConfig ¶
type LoggerConfig = config.LoggerConfig
LoggerConfig holds logging configuration.
type Middleware ¶
type Middleware = middleware.Middleware
Middleware is the signature for middleware functions.
func Chain ¶
func Chain(middlewares ...Middleware) Middleware
Chain combines multiple middlewares into a single middleware. Useful for composing middlewares in layout files.
func JWTMiddleware ¶
func JWTMiddleware() Middleware
JWTMiddleware validates JWT tokens and auto-redirects on failure.
func LoggingMiddleware ¶
func LoggingMiddleware() Middleware
LoggingMiddleware logs incoming requests.
func TimeoutMiddleware ¶
func TimeoutMiddleware(d time.Duration) Middleware
TimeoutMiddleware adds a timeout to request processing.
type Polymorphic ¶
type Polymorphic = database.Polymorphic
Polymorphic provides fields for polymorphic relationships.
Source Files
Directories