Skip to content
You are reading the v0.20 documentation. Go to the latest version (v1.0)

Getting started

Directory structure

The layout of an application created by vukem new, and how the framework module is organised.

Last updated:

An application#

vukem new blog generates:

Text
blog/
├── cmd/app/main.go            func main() { os.Exit(vukem.Main(bootstrap.New)) }
├── bootstrap/
│   ├── app.go                 New(opts...): providers, migrations, seeders, listeners, jobs, schedule, views, routes
│   ├── providers.go           func Providers() []vukem.Provider   (make:provider appends)
│   └── commands.go            func Commands() []vukem.Command     (make:command appends)
├── routes/
│   ├── web.go                 func Web(r *router.Router, app *vukem.App) error
│   └── schedule.go            func Schedule(s *schedule.Schedule, app *vukem.App)
├── app/
│   ├── controllers/           Home, PostController
│   ├── jobs/                  queued jobs + registry.go (make:job appends)
│   ├── listeners/             event listeners + registry.go (make:listener appends)
│   ├── models/                Post (orm.Model)
│   └── requests/              input structs and z schemas
├── database/migrations/       timestamped migrations + registry.go (make:migration appends)
├── resources/
│   ├── resources.go           embeds views and public; disk files in development
│   ├── views/                 layouts/, partials/, posts/, home.html
│   └── public/                css/app.css, js/htmx.min.js (htmx 4.0.0, vendored)
├── storage/                   SQLite database and local data (git-ignored)
├── tests/                     home_test.go, posts_test.go (vukemtest)
├── .env.example               copied to .env with a fresh APP_KEY
└── go.mod

Everything is wired in code you own: bootstrap/app.go lists the providers, migrations, views and routes. Generators edit bootstrap/providers.go, bootstrap/commands.go and database/migrations/registry.go with AST-based codemods; there is no init() registration and no reflection-based discovery. If you restructure those files, generators print the line to add by hand instead.

vukem keeps its build cache in .vukem/ and production builds in bin/; both are git-ignored.

The framework#

The module github.com/AlexGalhardo/vukem is split into small, single-purpose packages. The request context package is named web so it never shadows the conventional ctx context.Context variable.

PackagePurpose
vukem (root)App, options, providers, runners, commands, DefaultMiddleware, Main
config.env loader, Load[T], Secret, APP_KEY
routerServeMux wrapper: groups, names, resources, URL generation
web*web.Ctx: input, responses, redirects, rendering, error handler
errsHTTPError, ValidationError, sentinel errors
middlewarerecover, request id, logger, CORS, static, secure headers, gzip…
zZod-style schemas
session, csrfsessions with flash and old input; cross-origin protection
database, orm, schemaSQLite connections, generic query builder, migrations
view, htmxhtml/template engine; htmx 4 request and response helpers
vukemtestin-process test client and database assertions
cmd/vukemthe CLI
More packagesPurpose
api, ratelimitREST envelopes, query conventions, typed handlers, idempotency keys, deprecation headers; GCRA rate limiting
openapi, apidocsOpenAPI 3.1 generation and validation, TypeScript/Zod codegen, Scalar API reference
queue, queue/queuetest, scheduletyped jobs and drivers, driver conformance suite, cron scheduler
auth, auth/hash, authz, social, signedguards and tokens, password hashing, gates and policies, social login, signed URLs
mail, cache, storage, events, logging/telegrammail transports, cache stores, disks, typed events, Telegram logging
factory, database/dbtestmodel factories, dialect conformance suite
httpclient, webhook, securitySSRF-safe client, webhook signatures, security events
vite, inertiaVite asset tags; Inertia v3 adapter
crypt, i18n, sse, broadcast, uploadencryption, translations, server-sent events, realtime channels, streaming and resumable uploads
admin, devtoolsadmin panel; development dashboard
auth/jwt, auth/totpJWT guard and refresh tokens; TOTP two-factor
drivers/postgres, drivers/mysql, drivers/redis, drivers/mongo, drivers/s3, drivers/websocket, drivers/otel (separate modules)PostgreSQL, MySQL/MariaDB, Redis/Valkey, MongoDB, S3, WebSockets, OpenTelemetry
contrib/graphql, contrib/grpc, contrib/stripe (separate modules)GraphQL server, gRPC on connect-go, Stripe client