FAQ

Frequently Asked Questions

Answers to the most common questions about Vandor, organized by topic.

Vandor is a core-first Go backend framework built around Domain-Driven Design principles. It generates project scaffolding where your business domain is the center of the architecture, and infrastructure (HTTP servers, databases, caches, queues) is added incrementally through the VPKG package system.

The key idea: start with your domain logic, add infrastructure later. Your project grows with your requirements, not ahead of them.

Is Vandor a framework or a scaffolding tool?

It is a scaffolding tool with framework-level opinions about project structure. Vandor generates code into your project that you own completely. There is no Vandor runtime -- once your Go binary is compiled, it runs on its own without the Vandor CLI.

Think of it like shadcn/ui, but for Go backends. The code lives in your repo, you can read it, modify it, and debug it like any other Go code you wrote yourself.

Is Vandor production ready?

The framework design is stable and follows well-established patterns (DDD, hexagonal architecture, dependency injection with Uber FX). The 8 official packages are being actively validated. Vandor generates standard, idiomatic Go code -- so even if Vandor itself changes, the code in your project does not depend on it at runtime.

What Go version does Vandor require?

Go 1.24 or higher.

go version
# Should output go1.24 or higher

Core Concepts

What is a context?

A context represents a business capability -- a meaningful area of your domain that contains related logic, entities, and use cases. It is the primary organizational unit in a Vandor project.

Good contexts: catalog, identity, order, billing, shipping, notification

Bad contexts (too granular, table-focused): user, product, order_item, address

The rule of thumb: if you would describe it as "what the business does" rather than "what the database stores", it is probably a good context.

vandor add context catalog identity order

What is the difference between a use case and a service?

A use case (application/) is an application-level workflow. It is the entry point from your transport layer (HTTP handler, job processor, etc.) into your domain logic. Examples: CreateProduct, PlaceOrder, AuthenticateUser.

A domain service (core/service/) contains pure domain logic that is reusable across multiple use cases. It has no infrastructure dependencies. Examples: PriceCalculator, OrderValidator, InventoryChecker.

# Use case -- an application workflow
vandor add usecase catalog create_product

# Domain service -- reusable domain logic
vandor add service catalog price_calculator

How does sync work?

Vandor uses your filesystem as the source of truth. When you run vandor sync, it reads the current directory structure (your contexts, use cases, services) and regenerates the wiring files (*_gen.go). These generated files contain the Uber FX module definitions that wire everything together.

# Sync everything
vandor sync all

# Check what would change without applying
vandor sync --check

Only *_gen.go files are overwritten during sync. Your hand-written business logic is never touched.

VPKG (Packages)

Why not just use Go modules?

Go modules are great for libraries. But infrastructure setup is more than just importing a package -- it involves configuration, wiring, boilerplate adapters, and project structure decisions.

VPKG copies actual Go source code into your project. This means:

You can read and modify every line of infrastructure code
No hidden abstractions or framework magic
The code is adapted to your project's specific structure
No version conflicts or upgrade surprises at the module level

It is the difference between go get github.com/redis/go-redis (you still need to set up the connection, configuration, health checks, FX module...) and vandor vpkg add @official/redis-cache (all of that is scaffolded for you, ready to use).

What packages are available?

Vandor v0.4 ships with 8 official packages:

Package	What It Provides
`@official/http-humachi`	HTTP server with Chi router and Huma v2
`@official/entgo`	Database ORM with Ent.go
`@official/atlas`	Database migrations with Atlas
`@official/redis-cache`	Redis caching layer
`@official/asynq`	Background job processing with Asynq
`@official/runner-go-cron`	Scheduled tasks with go-cron
`@official/storage-s3`	S3-compatible object storage
`@official/observability`	Logging and tracing with OpenTelemetry

How do I install a package?

vandor vpkg add @official/http-humachi

What are actions and aliases?

Actions are commands that a package provides. They go beyond just installing code -- they let you scaffold specific files, run generators, or perform package-specific operations.

# Run a package action
vandor vpkg exec official/http-humachi add-handler
vandor vpkg exec official/entgo add-schema
vandor vpkg exec official/atlas migrate-diff

Aliases are project-level shortcuts for common actions. Instead of typing the full vpkg exec command, you use a shorter form:

# These are equivalent:
vandor vpkg exec official/http-humachi add-handler
vandor add:http-handler

How do I check if my packages are healthy?

# Run diagnostics
vandor vpkg doctor

# Auto-fix what can be fixed
vandor vpkg doctor --fix

Development Workflow

How do I add HTTP to my project?

vandor vpkg add @official/http-humachi

This copies the HTTP server code (Chi router, Huma v2, middleware, FX module) into your project. Then you can scaffold handlers:

vandor add:http-handler

Do I need Vandor in production?

No. Once your project is built, the Go binary runs completely independently. Vandor is a development-time tool only. Your production deployment is just a standard Go binary.

# Build
go build -o bin/app ./cmd/app

# Deploy and run -- no Vandor needed
./bin/app

How do I run my application?

# Development mode with hot reload
vandor dev:app

# Production mode
vandor run:app

# Or build and run the binary directly
go build -o bin/app ./cmd/app
./bin/app

Can I use Vandor for non-web projects?

Absolutely. Vandor's core-first model means your project starts with no transport layer at all. You can build:

Web APIs -- Add @official/http-humachi
Background workers -- Add @official/asynq
Scheduled jobs -- Add @official/runner-go-cron
CLI tools -- Use just the domain layer, no packages needed
Event processors -- Add relevant packages as needed

The domain layer works without any infrastructure. That is the whole point.

Testing

How does testing work with Vandor?

Your core domain layer has zero infrastructure dependencies. This makes it naturally testable -- you can unit test use cases and services with mock implementations of your repository interfaces.

// Your use case depends on an interface
type CreateProduct struct {
    repo domain.ProductRepository  // Interface, not implementation
}

// In tests, provide a mock
func TestCreateProduct(t *testing.T) {
    mockRepo := &MockProductRepository{}
    useCase := NewCreateProduct(mockRepo)
    // Test pure business logic without a database
}

Integration tests that involve infrastructure (database, HTTP, etc.) are separate from your domain tests. The boundary between core and infrastructure makes this separation clean.

vandor add context catalog identity order

If you prefer the guided experience with prompts and menus, add the -it flag:

vandor add context -it

What is the difference between `vandor new` and the old `vandor init`?

vandor new replaced vandor init in v0.4. It creates a new project with the core-first structure. There is no template or preset selection -- every project starts with the same clean foundation.

vandor new --module github.com/acme/myapp --tidy auto

Still Have Questions?

Check Troubleshooting for common problems
Browse the Guides for practical walkthroughs
Review the CLI Reference for command details
See What's New in v0.4 for the latest changes

FAQ