prea

README

A modular web framework for Go.
Documentation · Tutorial · CLI reference

---

Preá splits an application into preás: small modules, one per feature, each with its own handler, service, repository and model. You declare the pieces, and Preá wires them together, checks the wiring when the app starts and serves them over HTTP.

var Module = &core.Module{
	Name: "task",
	Providers: []any{
		Repository{},
		Service{},
		Handler{},
	},
}

type Service struct {
	Repo *Repository `inject:""` // filled in when the app starts
}

Status: pre-alpha (v0.0.x). The API still changes between versions.

Highlights

• Preás and components. Group a feature in one folder and ask for what you need with inject:"". A missing or ambiguous dependency stops the app at startup, never in production.
• Configuration with profiles. config/application.yaml plus one file per profile (dev, prod, tests), with secrets from the environment.
• Database from your models. Struct tags describe the schema. Preá generates migrations from them, applies them and gives every model a ready-made repository.
• A CLI for the whole cycle. Create, generate, run with hot reload, test, migrate and build.

Quick start

You need Go 1.26 or newer, and PostgreSQL if your app uses a database.

# Install the CLI
curl -fsSL https://raw.githubusercontent.com/prea-framework/prea/main/install.sh | sh

# Create a project with a database and run it with hot reload
prea new todo --with-db
cd todo
cp .env.example .env    # set DATABASE_URL and TEST_DATABASE_URL
prea dev

curl localhost:8000/health
curl -X POST localhost:8000/item -H 'Content-Type: application/json' -d '{"name": "first"}'

The Quick start explains each step, and the tutorial builds a complete todo API.

Modules

Preá is a set of Go modules. A project created by prea new depends on the root one, which brings the others.

Module	What it has
github.com/prea-framework/prea	prea.Run and prea.Test: start or test an app from its configuration
.../core	preás, the HTTP server, middlewares, HTTP security, errors and responses
.../di	the dependency injection container
.../database	repositories, queries, transactions, schema and migrations (PostgreSQL)
.../config	configuration files, profiles and .env
.../security	JWT and password hashing
.../logger	leveled, structured logs
.../cmd/prea	the prea CLI

Contributing

Preá is young, and the contributing guide explains how to run the tests and send a change.

The name

A preá is a small rodent from the Brazilian Northeast, where Preá was born. Meet the preá.

License

MIT

Documentation

Overview

Package prea runs a Preá app: it loads the config of the active profile, opens the database, applies the migrations and serves the modules. The app's main only passes what it declares:

prea.Run(prea.Config{Modules: preas.Modules, Middlewares: preas.Middlewares, Security: preas.Security})

Index

• func Run(cfg Config)
• func Test(t testing.TB, cfg Config) http.Handler
• type Config
• type Logging

Functions

func Run

func Run(cfg Config)

Run starts the app and serves until SIGINT or SIGTERM; a startup error is logged and exits the process with code 1. With PREA_MIGRATE set (by prea migrate) it runs that migrations command instead of serving.

func Test

func Test(t testing.TB, cfg Config) http.Handler

Test builds the app like Run, with the tests profile (config/application-tests.yaml), and returns its handler for httptest:

app := prea.Test(t, prea.Config{Modules: []*core.Module{Module}})
app.ServeHTTP(w, httptest.NewRequest("GET", "/health", nil))

It runs from the project root, the nearest directory with a go.mod above the test's, so config/ and migrations/ are found from any package. The app and the database close when the test ends.

Types

type Config

type Config struct {
	Modules     []*core.Module
	Middlewares []any
	Security    core.Security // Security.TrustedProxies, when nil, comes from server.trusted_proxies
	Logging     Logging
}

Config is what the app declares in code. The rest comes from config/application.yaml and the active profile:

• server.port and server.mode, required;
• server.read_header_timeout, read_timeout, write_timeout, idle_timeout, shutdown_timeout, max_header_bytes and trusted_proxies, with defaults;
• database.url (without it the app has no database), database.schema and database.migrations;
• security.jwt.secret, checked at startup only when set (apps build security.Jwt with NewJwt using the same value).

type Logging

type Logging struct {
	Level  string `yaml:"level"`  // debug | info | success | warn | error
	Format string `yaml:"format"` // text | json
}

Logging configures the logs. An empty field comes from logging.level or logging.format in the config, then the default: info, text.