Proposal: modules, a feature-oriented layout for Goravel applications

[protibimbok]

Summary

Goravel applications are laid out by type: app/http/controllers, routes/, database/migrations, resources/views. That works well until an application has several distinct features, at which point one feature is spread over six directories.

I would like to propose first-class modules: a feature lives in one directory (modules/blog/) with its own routes, controllers, migrations, views, translations, config and frontend entries, and the application lists its modules in one file.

// bootstrap/app.go
return foundation.Setup().
    WithMigrations(Migrations).
    WithModules(Modules).
    WithRouting(func() { routes.Web() }).
    WithProviders(Providers).
    WithConfig(config.Boot).
    Create()

// bootstrap/modules.go
func Modules() []modular.Module {
    return []modular.Module{
        &blog.Module{},
        &shop.Module{},
    }
}

Design principles

1. One list. bootstrap/modules.go is the only place modules are named. A directory under modules/ that is not in the list does nothing. Removing a module is deleting its line.
2. One struct. A module is a value implementing modular.Module. What it contributes is detected by type assertion: implement the interface and the behaviour is wired, leave it out and the matching directory is ignored even if it exists.
3. No discovery, no cache. The framework never scans the disk for modules, so there is no manifest to rebuild and nothing that behaves differently in a compiled binary.
4. No new concepts in the drivers. gin and fiber are unchanged. They see more views in the view registry, more routes through route.Router and more global middleware.
5. Opt-in. An application without WithModules behaves exactly as today.

A module

// contracts/modular
type Module interface {
    Name() string // unique, kebab-case: "blog", "blog-posts"
}

Everything else is an optional interface.

modules/blog/
├── module.go
├── providers/service_provider.go
├── routes/{web.go,api.go}
├── http/controllers/blog_controller.go
├── database/{migrations,seeders}/
├── resources/
│   ├── views/index.tmpl       (embedded)
│   ├── js/app.js              (Vite entry)
│   └── css/app.css
├── lang/en/messages.json      (embedded)
└── tests/feature/blog_test.go

package blog

//go:embed resources/views
var views embed.FS

//go:embed lang
var lang embed.FS

type Module struct{}

func (m *Module) Name() string { return "blog" }

func (m *Module) ServiceProviders() []foundation.ServiceProvider {
    return []foundation.ServiceProvider{&providers.ServiceProvider{}}
}
func (m *Module) Routes(router route.Router)    { routes.Web(router) }
func (m *Module) ApiRoutes(router route.Router) { routes.Api(router) }
func (m *Module) Migrations() []schema.Migration {
    return []schema.Migration{&migrations.M20261106000000CreatePostsTable{}}
}
func (m *Module) Config() map[string]any { return map[string]any{"per_page": 10} }
func (m *Module) Views() fs.FS           { sub, _ := fs.Sub(views, "resources/views"); return sub }
func (m *Module) Translations() fs.FS    { sub, _ := fs.Sub(lang, "lang"); return sub }
func (m *Module) ViteEntries() []string  { return []string{"resources/js/app.js"} }

The module's name namespaces what it contributes:

Thing	Name
View resources/views/index.tmpl	ctx.Response().View().Make("blog/index.tmpl", …)
Translation lang/en/messages.json	facades.Lang(ctx).Get("blog/messages.title")
Config	facades.Config().GetInt("modules.blog.per_page")
Vite entry resources/js/app.js	{{ vite "@blog/app.js" }}

A module is a package of the application's Go module. It has no go.mod of its own, and its directory is derived from its Go package path, so there is nothing to configure per module.

Capabilities

Interface	Method	Wired as
foundation.ProvidesServices	ServiceProviders() []foundation.ServiceProvider	joins the provider repository with the WithProviders list
modular.ProvidesConfig	Config() map[string]any	config.Add("modules.<name>", …)
modular.ProvidesGlobalMiddleware	GlobalMiddleware() []http.Middleware	appended before the application's WithMiddleware callback runs
modular.ProvidesRoutes	Routes(router route.Router)	inside the modular.routes.web group (prefix and middleware from config)
modular.ProvidesApiRoutes	ApiRoutes(router route.Router)	inside the modular.routes.api group (default prefix api)
modular.ProvidesMigrations	Migrations() []schema.Migration	registered with the application's migrations
modular.ProvidesSeeders	Seeders() []seeder.Seeder	seeder.Register
modular.ProvidesCommands	Commands() []console.Command	artisan.Register, subject to WithCommandsFilter and WithCommandHooks
modular.ProvidesJobs	Jobs() []queue.Job	queue.Register
modular.ProvidesEvents	Events() map[event.Event][]event.Listener	merged per event with WithEvents
modular.ProvidesSchedule	Schedule() []schedule.Event	schedule.Register
modular.ProvidesViews	Views() fs.FS	View.LoadViewsFromFS, names prefixed with <name>/
modular.ProvidesTranslations	Translations() fs.FS	part of app.lang_fs, groups prefixed with <name>/
modular.ProvidesViteEntries	ViteEntries() []string	listed by vite:inputs, built by the plugin
modular.ProvidesViteAlias	ViteAliases() map[string]string	extra @… aliases for Vite and for {{ vite }} / {{ viteAsset }}
modular.ProvidesStatic	Static() map[string]modular.Path	route.StaticFS on the root router
modular.Ordered	Order() int	registration order (default 0, lower first)
modular.Located	Path() string	overrides the derived directory

Capabilities mirror the builder's With* setters only where a service provider cannot do the same job. Validation rules and filters, template functions and runners are registered in the module's service provider Boot, as a package would do today.

Registry

type Registry interface {
    Register(modules ...Module) error
    All() []Module
    Find(name string) (Module, bool)
    Has(name string) bool
    Path(name string) (string, bool)
    Capabilities(module Module) map[string]bool
}

Available as facades.Modular(). The typical use is an optional integration between modules: if facades.Modular().Has("billing") { … }.

Runtime

Application.Build() merges each module's contributions into the step that already handles the application's own. No new boot phase is introduced for providers, events, commands and so on.

Step	Module contribution
WithConfig
configure modules	registry built and bound; modules.<name> config; module translations added to app.lang_fs
service providers Register	application and module providers in one repository, sorted by relationships
global middleware	driver defaults → module middleware → application WithMiddleware
service providers Boot
register module resources	module view filesystems registered under <name>/
view compilation	the driver compiles application, package and module views together
events, commands, schedule, migrations, seeders, jobs	application items first, then modules in order
routes	application WithRouting, then module static prefixes, then each module's web and api groups

Who wins

The application always overrides a module:

Thing	Override
View blog/index.tmpl	put resources/views/blog/index.tmpl in the application
Translation blog/messages.*	put lang/en/blog/messages.json in the application
Global middleware	the application's WithMiddleware callback sees the module middleware and can reorder or replace it
Routes	no override: registering the same method and path twice is a driver error. Move the module with modular.routes.web.prefix.
Vite alias	an alias in vite.config.js wins over a module's

Vite

artisan vite:inputs gains a modules field:

{"inputs":["@blog/app.js","resources/js/app.js"],
 "modules":[{"name":"blog","path":"modules/blog",
             "entries":["modules/blog/resources/js/app.js"]}]}

goravel-vite-plugin reads it. vite.config.js does not change:

• module entries are added to the build input;
• @<name> is aliased to modules/<name>/resources/js, mirroring the existing @ → resources/js;
• with refresh: true, module views, routes and lang files are watched.

Aliases also work in templates:

{{ vite "@blog/app.js" }}
{{ vite "@/app.js" "@blog/app.js" }}

For this the plugin writes its alias table into the manifest (reserved key goravel:aliases) and into the hot file, which becomes JSON ({"url": "…", "aliases": {…}}). The framework resolves the alias, cleans the path and refuses anything that ends outside the project. The plugin applies the same rule, so dev and build resolve to the same file.

Commands

Command	What it does
goravel new <app> --modular	new project, prepared for modules
artisan modular:init	prepares an existing project: config/modular.go, bootstrap/modules.go, .WithModules(Modules) in bootstrap/app.go. Idempotent; prints the manual step when the builder chain cannot be edited safely.
artisan make:module Blog [--api] [--plain] [--order=N] [--force]	scaffolds modules/blog/ and adds it to bootstrap/modules.go
artisan modular:list [--json]	name, path, order, capabilities, Vite entries of each module
artisan modular:publish	see third-party modules below
artisan make:<thing> … --module=blog	every make:* generator writes into the module. make:migration, make:command, make:seeder, make:job and make:provider also register the item on the module struct.

Third-party modules

A module can also come from another Go module (go get github.com/acme/goravel-blog, then add &blog.Module{} to the list). Go code, embedded views and translations work as for any module. The frontend is the difficulty: Vite and Tailwind cannot read files from the Go module cache.

Such a module implements ProvidesSources, and artisan modular:publish (wired to go generate) copies its frontend sources and views to modules/<name>/, committed with the application. vite:inputs fails when that copy is missing or out of date, so a build never ships stale assets silently.

This is the part of the design I am least sure belongs in the first version (see below).

What does not change

• Applications without WithModules.
• gin and fiber.
• The legacy config/app.go + Boot() layout: the registry is not bound there and the modular:* commands refuse with a clear error.
• vite.config.js of existing applications. The JSON hot file is read by the new plugin and the new framework version together; they need to be released in step.

Limits

• A module cannot use the * translation group (lang/en.json); it cannot be namespaced.
• Moving a module means moving its Go package.
• Static files from ProvidesStatic are served as-is. Use a Vite asset for cache-busted URLs.
• An application file lang/en/blog/messages.json replaces the module's group as a whole; keys it omits do not fall back to the module.

1. provider key fix (independent)
2. contracts, registry, WithModules and the Build() merge
3. modular:init, make:module, modular:list
4. Vite: vite:inputs modules and alias resolution (with the plugin PR)
5. --module on the make:* generators
6. third-party modules (modular:publish), if wanted
7. installer --modular, documentation

[protibimbok]

goravel/framework#1613
goravel/vite-plugin#4
goravel/installer#88