Create Your First Project

This page shows how to create your first Vix.cpp project.

A single C++ file is useful for experiments:

vix run main.cpp

A project is the next step when the code needs a stable structure, configuration, tests, repeatable commands, and a path toward a real application.

For that, use:

vix new

A Vix.cpp project gives you a clean folder, an application manifest, configuration files, tests, metadata, and a standard command workflow.

Create a simple application

Create a new application project:

cd ~/tmp
vix new hello --app

This creates a minimal runnable Vix application.

The CLI will print the next steps:

next
1  cd hello/    enter project
2  vix build    compile
3  vix run      start app

Enter the project

Move into the generated folder:

cd hello

Run all project commands from inside this directory.

Create local configuration

If the project contains .env.example, create your local .env file:

cp .env.example .env

This is the recommended workflow.

.env.example documents the configuration expected by the project.

.env contains the values used on your local machine.

This keeps environment-specific values outside the source code.

Build the project

Compile the project:

vix build

Expected output shape:

Compiling hello (dev)
  ✔ Configured
  ✔ Built
  ✔ Done in 1.6s

vix build compiles the project without starting the application.

Use it when you want to verify that the project builds successfully.

Run the project

Start the application:

vix run

Expected output shape:

● Vix.cpp   READY   v2.6.0   run
  › HTTP:    http://localhost:8080/
  i Threads: 8/8
  i Mode:    run
  i Status:  ready
  i Hint:    Ctrl+C to stop the server

Open another terminal and test the application:

curl http://127.0.0.1:8080/

Stop the server with:

Ctrl+C

Development mode

For active development, use:

vix dev

Use vix dev when you are editing code and want a development-oriented workflow.

Use vix run when you simply want to start the application.

In practice:

vix build -> compile the project
vix run   -> start the application
vix dev   -> work on the application during development

Generated project structure

A simple application project usually looks like this:

hello/
├── src/
│   └── main.cpp
├── tests/
│   └── test_basic.cpp
├── .env.example
├── .env
├── vix.app
├── vix.json
└── README.md

Some templates may include extra files depending on the selected project type.

What each file does

File or folder	Purpose
src/main.cpp	Main application entry point.
tests/	Project tests.
.env.example	Example configuration shared with the project.
.env	Local configuration for your machine.
vix.app	Application manifest used by Vix.cpp to build the project.
vix.json	Project metadata, tasks, and dependency information.
README.md	Generated project documentation.

This structure is intentionally small. It gives the application enough organization to grow without forcing a complex layout too early.

Open the entry file

Open:

src/main.cpp

A generated application keeps the entry point small.

The exact code may evolve between Vix.cpp versions, but the basic idea stays the same:

#include <vix.hpp>

using namespace vix;

int main()
{
  App app;

  app.get("/", [](Request &, Response &res) {
    res.send("Hello from Vix.cpp");
  });

  app.run();

  return 0;
}

The call to app.run() uses runtime configuration.

For normal applications, keep values such as the server port in .env instead of hardcoding them in the source code.

Configuration

Open:

.env

You may see values such as:

SERVER_PORT=8080
VIX_LOG_LEVEL=info
VIX_LOG_FORMAT=kv

To change the port, edit:

SERVER_PORT=3000

Then run again:

vix run

The source code does not need to change.

This pattern becomes important when the same application moves from local development to CI, staging, or production.

vix.app

The vix.app file describes the application target.

It tells Vix.cpp what to build.

For simple projects, you do not need to write a CMakeLists.txt manually.

The flow is:

vix.app
  -> Vix.cpp generates the internal CMake project
  -> vix build compiles the app
  -> vix run starts the app

This gives the project a small readable manifest while keeping a real native C++ build underneath.

When the build itself becomes complex, the project can move to a normal CMakeLists.txt.

vix.json

The vix.json file stores project metadata, tasks, and dependency information.

Some projects define tasks that you can run with:

vix task <name>

Common examples:

vix task dev
vix task test
vix task ci

The exact tasks depend on the generated template.

Useful project commands

Inside the project folder:

vix build
vix run
vix dev
vix check
vix tests
vix fmt

Command	Purpose
vix build	Compile the project.
vix run	Build if needed and start the app.
vix dev	Start development mode.
vix check	Validate the project.
vix tests	Run tests.
vix fmt	Format source files.

These commands are the basic lifecycle of a Vix.cpp project.

Project templates

The --app template is the simplest way to start.

Vix.cpp also provides templates for more specific project types.

Template	Command	Use when
Application	vix new hello --app	You want a minimal runnable Vix application.
Backend	vix new api --template backend	You want a production-oriented API or backend service.
Web	vix new site --template web	You want server-rendered HTML with Vix templates.
Vue	vix new dashboard --template vue	You want a Vue frontend with a Vix C++ backend.
Game	vix new game --template game	You want a game-oriented Vix project.
Library	vix new mathlib --lib	You want a reusable C++ library.

Getting Started uses --app because it is the smallest project shape.

The other templates are useful when the application has a clearer direction from the beginning.

When to use another template

Use the backend template when you want a backend structure with routes, controllers, middleware, storage, public files, tests, configuration, and production diagnostics from the beginning.

Use the web template when you want HTML rendered on the server with Vix templates.

Use the Vue template when you want a modern frontend and a Vix C++ backend in the same project.

Use the game template when you want a game-oriented runtime structure.

Use the library template when the project should produce reusable C++ code instead of a runnable application.

When to move beyond the simple app

A simple application project is a good starting point, but larger applications need more structure.

Move beyond the minimal app when you need:

• multiple source files
• reusable headers
• route organization
• services or modules
• tests for different components
• static files
• templates
• database access
• production configuration
• packaging
• custom build behavior

At that point, either use a more specific Vix template or introduce a full CMakeLists.txt if the build itself needs advanced control.

Common mistakes

Running commands outside the project

Wrong:

cd ~/tmp
vix run

Correct:

cd ~/tmp/hello
vix run

Run project commands from the project folder.

Forgetting .env

If the project has .env.example, create your local .env:

cp .env.example .env

Do this once after generating the project.

Forgetting to stop the previous server

If port 8080 is already in use, stop the previous server with:

Ctrl+C

Or change the port in .env:

SERVER_PORT=3000

Then run again:

vix run

Editing files but not using development mode

For active development, prefer:

vix dev

Use vix run when you simply want to start the app.

What you should remember

Create a simple application project:

vix new hello --app
cd hello
cp .env.example .env

Build it:

vix build

Run it:

vix run

Develop it:

vix dev

A Vix.cpp project is where a quick experiment becomes a structured application.

Next step

Build your first HTTP server with Vix.cpp.

Next: Your First HTTP Server

For deeper project structures, continue with:

• Application template
• Backend template
• Web template
• Vue template
• Game template
• Library template