Template Customization

Learn how to customize templates to fit your specific needs

Customization Basics

Templates provided by create-vlang-app are designed to be customizable. This guide shows how to adapt generated V projects — from module layout and tooling to dependencies and environment settings.

Project Structure Customization

After scaffolding, reorganize modules to match your domain. Common patterns across CVA templates:

Top-level feature modules

Prefer top-level V modules (health/, greet/) — nested src/features/ paths do not import cleanly in V.

v.mod at the root

Keep module name, version, and dependencies in v.mod; run v install after edits.

docs/

Every starter ships a docs/ tree — extend AUTHORING / PROJECT_STRUCTURE instead of duplicating rules in README.

Tests beside modules

Keep *_test.v next to the code under test and run v test ..

Configuration Customization

Templates ship with v.mod, Makefile targets, and fmt/vet defaults you can tune:

Module {
  name: 'my_app'
  description: 'My V application'
  version: '0.1.0'
  license: 'MIT'
  dependencies: []
}

Add VPM dependencies here, then run v install. Growth starters already declare real vsl / vtl / rxv deps.

Dependency Customization

Manage dependencies with VPM after scaffolding:

# Edit v.mod dependencies, then:
v install

# Install a specific module into ~/.vmodules
v install vsl

# Refresh after lock/path changes
v install

For Docker, Postgres, or CI wiring, prefer scaffolding with the matching extension rather than hand-copying fragments.

Adding Extensions After Project Creation

If you want extensions on an existing project, you can manually port the files from cva-templates/extensions or re-scaffold with the desired combination:

Manual integration: Copy the extension's template/ overlay onto your project and reconcile conflicts.
Re-scaffold: Create a fresh project with the same template plus extensions, then migrate your application modules.
Git branch: Apply extension changes on a branch and merge after review.

Note

The CLI applies extensions at scaffold time only. Post-create extension application may be added in future releases.

Template-Specific Customization

Different CVA templates have distinct extension points:

Web Server (vweb/veb)

Routes: Extend the HTTP handlers in the template entrypoint; keep feature modules at the top level.
Data stores: Pair with v-sqlite or v-postgres during scaffold.
Deploy: Add v-docker and github-setup for containers + setup-v CI.

create-vlang-app my-api \
  --template web-server \
  --addons v-docker github-setup v-postgres

Advanced Customization

For deeper changes, adjust runtime configuration and deployment artifacts:

Environment Variables

Use .env locally when an extension provides samples (never commit secrets):

# .env.example (from v-postgres / v-sqlite overlays)
DATABASE_URL=postgres://user:pass@localhost:5432/app
PORT=8080

Docker & Compose

When you scaffold with v-docker, customize Dockerfile, compose files, and health checks for your deployment target. Rebuild with docker compose up --build after changes.

Back to Contributing Advanced Usage