vix modules

vix modules manages application modules from the command line. It is used to initialize module support, create module skeletons, inspect modules declared in vix.app, enable or disable modules, and validate module boundaries before the project is built.

This command is about internal application modules, not Vix SDK modules such as vix::orm, vix::requests, or vix::ui. An application module belongs to your project. It can represent a feature such as auth, projects, builds, packages, billing, or logs.

vix modules <subcommand> [options]

Basic workflow

A new module workflow usually starts from the project root.

vix modules init
vix modules add auth
vix modules list
vix modules check
vix build

In a vix.app project, modules are declared in the root manifest. In a classic CMake project, Vix can still create the module layout and CMake targets without requiring the project to move to vix.app.

Subcommands

init                 Initialize module support
add <name>           Create a module skeleton
list                 List modules declared in vix.app
enable <name>        Enable a module in vix.app
disable <name>       Disable a module in vix.app
check                Validate module structure and dependencies

Options

-d, --dir <path>         Project root. Defaults to the current directory.
--project <name>         Override the detected project name.
--name <name>            Explicit module name, useful with generator flags.
--no-patch               Do not patch the root CMakeLists.txt during init.
--patch                  Patch the root CMakeLists.txt during init.
--no-link                Do not auto-link a new module into the main target.
--link                   Auto-link a new module into the main target.
--websocket              Generate a WebSocket application module.
--workflow <name>        WebSocket workflow: attached, standalone, bridge, client.
-h, --help               Show command help.

The project name is used to generate module targets. For a project named api and a module named auth, Vix creates a target and an alias shaped like this:

api_auth
api::auth

Use --project when the detected name is not the prefix you want.

vix modules add auth --project api

Initialize module support

vix modules init prepares the project for application modules.

vix modules init

It creates:

modules/
cmake/vix_modules.cmake

In a CMake project, Vix can patch the root CMakeLists.txt so the module loader is included by the existing build. In a vix.app project, Vix skips root CMake patching because the active CMake input is generated internally.

Use --no-patch when the project has a custom CMake structure and you want to connect the module loader manually.

vix modules init --no-patch

Then add the loader where it belongs in your build.

include(${CMAKE_CURRENT_LIST_DIR}/cmake/vix_modules.cmake)

Add a module

vix modules add <name> creates a new module under modules/<name>/.

vix modules add auth

In a backend-style vix.app project, the generated module is a routed backend module.

modules/auth/
  include/auth/AuthModule.hpp
  include/auth/controllers/AuthController.hpp
  src/AuthModule.cpp
  src/controllers/AuthController.cpp
  migrations/
  tests/test_auth.cpp
  CMakeLists.txt
  vix.module

In a simple C++ or CMake-first project, the generated module is smaller.

modules/auth/
  include/auth/api.hpp
  src/auth.cpp
  tests/test_auth.cpp
  CMakeLists.txt
  vix.module

Module names may contain letters, numbers, underscores, and hyphens. Hyphens are normalized to underscores for generated identifiers.

user-profile -> user_profile

When a generator flag would otherwise use a default name, pass the module name explicitly.

vix modules add live_chat --websocket
vix modules add --websocket --name live_chat

Both commands create modules/live_chat/. The positional name is the shortest form; --name is useful in scripts where generator options are assembled first.

Add a WebSocket module

vix modules add <name> --websocket creates a WebSocket application module. The generated module is declared in vix.app, gets its own vix.module metadata, and can be built through the normal application workflow.

vix modules init
vix modules add live_chat --websocket --workflow attached
vix build
vix run

The generated files follow the chosen module name.

modules/live_chat/
  include/live_chat/LiveChatModule.hpp
  src/LiveChatModule.cpp
  tests/test_live_chat.cpp
  CMakeLists.txt
  vix.module

The WebSocket workflow controls what the module generates.

Workflow	Use case	Runtime module
attached	Run HTTP and WebSocket together in one app.	yes
standalone	Run a WebSocket server owned by the module.	yes
bridge	Bridge application setup to WebSocket setup.	yes
client	Generate client/helper code without runtime.	no

The server workflows generate a module run(...) entry point and use the Vix WebSocket runtime headers. The client workflow intentionally does not generate a runtime run(...) entry point, so it can be enabled without replacing the application runtime.

name = "live_chat"
kind = "websocket.attached"
runtime = true

[websocket]
workflow = "attached"

For backend templates, the generated static home page includes a browser-side WebSocket status panel. It attempts to connect to the development WebSocket endpoint, shows connected or disconnected state, and gives a quick visual check that the generated WebSocket module is running.

Add without linking

By default, in a CMake project, Vix may try to link the generated module into the detected main target. This is useful for simple projects, but custom CMake projects often need manual control.

Use --no-link to create the module without modifying the root build file.

vix modules add auth --no-link

Then link the module manually.

target_link_libraries(my_server PRIVATE api::auth)

The alias target is the recommended target name to use from the rest of the project.

List modules

vix modules list reads the module declarations from vix.app.

vix modules list

It shows the module name, enabled state, kind, path, filesystem status, and dependencies.

A modern module declaration looks like this:

[module.auth]
enabled = true
path = "modules/auth"
kind = "backend"
depends = []

The [module.<name>] format is preferred because it can describe the module state, path, kind, and dependency list. Older manifests that use modules = [...] can still be read, but new projects should use section-based declarations.

Enable a module

vix modules enable <name> marks an existing module declaration as active in vix.app.

vix modules enable auth

The command updates the module section.

[module.auth]
enabled = true
path = "modules/auth"
kind = "backend"
depends = []

An enabled module participates in the generated application build. For routed modules, it can also be included in the generated module registration bridge.

Disable a module

vix modules disable <name> keeps the module declared but removes it from the active application wiring.

vix modules disable auth

The command updates vix.app.

[module.auth]
enabled = false
path = "modules/auth"
kind = "backend"
depends = []

Disabling a module does not delete its files. The module can remain in the repository while being excluded from the current application build. This is useful for unfinished features, migrations, or temporary removals.

Check modules

vix modules check validates the module layer.

vix modules check

The check command is meant to catch structural problems before the build reaches more confusing compiler or generated-file errors. In a vix.app project, it checks that declared modules exist, enabled modules have the required files, dependencies are declared, enabled modules do not depend on disabled modules, and dependency cycles are not present.

It also checks module boundaries. Public headers should not include private implementation files from src/, and cross-module includes should be backed by explicit target dependencies.

For backend modules, it also checks route prefix conflicts declared in vix.module.

It also checks the new module dependency metadata: a module that declares registry packages should declare the link targets it needs, and a module that declares dependency links should also declare the registry packages that provide them.

vix modules check
vix build

For a stronger local validation, run:

vix modules check
vix check --tests --run

Working with vix.app

In a vix.app project, the root manifest is the source of truth for the active module graph.

[module.auth]
enabled = true
path = "modules/auth"
kind = "backend"
depends = []

[module.projects]
enabled = true
path = "modules/projects"
kind = "backend"
depends = [
  "auth",
]

When projects depends on auth, the dependency should be visible in the manifest. If the module also uses headers or symbols from auth, the module target should express that build dependency as well.

target_link_libraries(api_projects
  PUBLIC
    api::auth
)

The manifest describes the application architecture. CMake describes the build relationship. Both should agree.

Registry packages that belong to one module are declared in the module manifest rather than in vix.app. Use vix add --module for that workflow.

vix add gk/jwt@^1.0.0 --module auth

This updates modules/auth/vix.module with both the registry package and the CMake link target. The root vix.lock is still refreshed from the effective application dependency graph, including enabled module dependencies.

Working with CMake

A project does not need to be fully generated by Vix to use vix modules. Existing CMake projects can use the module system to add a clear feature layout while keeping their current build design.

vix modules init
vix modules add auth

For simple projects, automatic patching and linking may be enough. For custom CMake projects, prefer manual integration.

vix modules init --no-patch
vix modules add auth --no-link

Then connect the loader and target yourself.

include(${CMAKE_CURRENT_LIST_DIR}/cmake/vix_modules.cmake)

target_link_libraries(my_server PRIVATE api::auth)

This keeps Vix responsible for the module skeleton and conventions, while the existing CMake project remains responsible for the final build shape.

Public and private convention

Modules follow a simple public/private convention.

modules/<name>/include/<name>/...  public headers
modules/<name>/src/...             private implementation

Code outside the module should include public headers.

#include <auth/api.hpp>

It should not include private files from another module’s src/ directory.

#include "../../auth/src/AuthStore.hpp"

When another module needs functionality from auth, expose the needed type or function through a public header, then declare the dependency.

target_link_libraries(api_projects
  PUBLIC
    api::auth
)

This is the main architectural contract behind vix modules.

Common examples

Initialize modules in the current project:

vix modules init

Create a module:

vix modules add auth

Create a module in another project directory:

vix modules add auth --dir ./api

Create a module with an explicit project prefix:

vix modules add auth --project api

Create a module without changing root CMake files:

vix modules add auth --no-link

List modules declared in vix.app:

vix modules list

Disable and enable a module:

vix modules disable auth
vix modules enable auth

Validate the module layer:

vix modules check

When to use this command

Use vix modules when a project needs feature boundaries inside one C++ application. It is useful for backends that grow into features such as authentication, projects, builds, packages, logs, billing, and deployment logic. It is also useful in existing CMake projects that want a consistent modules/<name>/ layout without changing the whole build system.

A small project does not need to become modular immediately. Add modules when a feature has enough responsibility to deserve its own directory, public interface, implementation, tests, and dependency boundary.

Related pages

• Application Modules
• CLI Workflow
• Using with vix.app
• Using with CMake
• Dependencies and Checks