VPKG Workflow Guide

Overview

The VPKG workflow follows a natural progression:

1. Search -- Find the right package for your needs
2. Inspect -- Review what a package provides before installing
3. Install -- Add the package to your project
4. Use -- Run package actions and aliases to scaffold code
5. Verify -- Run the doctor to make sure everything is healthy
6. Manage -- Remove, sync, and maintain packages over time

Let's walk through each step with practical examples.

Step 1: Search for Packages

Before installing anything, find out what is available. The search command lets you look for packages by keyword.

# Search by keyword
vandor vpkg search http

# Search for database-related packages
vandor vpkg search database

# Search for caching
vandor vpkg search cache

# Search for background jobs
vandor vpkg search async

The search results show package names, tiers (official, verified, community), and short descriptions. This gives you a quick sense of what is out there before committing to anything.

Step 2: View Package Details

Once you find a package that looks promising, use info to see the full picture.

vandor vpkg info @official/http-humachi

This shows you:

• Description -- What the package does
• Tier -- Official, verified, or community
• Version -- Current release version
• Dependencies -- What Go modules it brings in
• Actions -- Commands the package provides (like adding handlers or middleware)
• Files -- What gets copied into your project

Reviewing this output before installing helps you understand exactly what will change in your project. No surprises.

# Check out other packages before deciding
vandor vpkg info @official/entgo
vandor vpkg info @official/redis-cache
vandor vpkg info @official/asynq

Step 3: Install a Package

When you are ready, install with vpkg add. The package code gets copied directly into your project -- you own it completely.

# Install the HTTP server package
vandor vpkg add @official/http-humachi

Here is what happens behind the scenes:

1. The package template is fetched from the registry
2. Code is rendered and copied into your project (under internal/transport/ or internal/infrastructure/)
3. Go dependencies are added to your go.mod
4. Configuration templates are created in config/
5. The package is recorded in your lockfile

You can install multiple packages in one go:

# Set up a full web API stack
vandor vpkg add @official/http-humachi @official/entgo @official/atlas

Typical Project Setups

Web API:

vandor vpkg add @official/http-humachi
vandor vpkg add @official/entgo
vandor vpkg add @official/atlas

Web API with caching and background jobs:

vandor vpkg add @official/http-humachi
vandor vpkg add @official/entgo
vandor vpkg add @official/atlas
vandor vpkg add @official/redis-cache
vandor vpkg add @official/asynq

Background worker with scheduled tasks:

vandor vpkg add @official/entgo
vandor vpkg add @official/atlas
vandor vpkg add @official/asynq
vandor vpkg add @official/runner-go-cron

API with observability:

vandor vpkg add @official/http-humachi
vandor vpkg add @official/entgo
vandor vpkg add @official/observability

Step 4: Use Package Actions

This is where things get interesting. Packages do not just install library code -- they also provide actions. Actions are commands that a package exposes for scaffolding, code generation, or other operations specific to that package.

You run actions through vpkg exec:

# Add a new HTTP handler using the http-humachi package
vandor vpkg exec official/http-humachi add-handler

# Add a new database schema using the entgo package
vandor vpkg exec official/entgo add-schema

# Run Atlas migration diff
vandor vpkg exec official/atlas migrate-diff

Using Aliases

Typing out the full vpkg exec command every time gets tedious. That is why Vandor supports aliases -- project-level shortcuts for commonly used actions.

# Instead of the full command:
vandor vpkg exec official/http-humachi add-handler

# Use the alias:
vandor add:http-handler

Aliases are defined in your project configuration and map directly to vpkg exec commands. They make your workflow feel natural and fast.

Some common aliases you might see in a project:

# HTTP handler scaffolding
vandor add:http-handler

# Database schema creation
vandor add:schema

# Migration management
vandor migrate:diff
vandor migrate:up

Practical Example: Adding a Feature

Let's say you want to add a "Create Product" endpoint to your catalog context. Here is the flow:

# 1. Add the use case to your domain
vandor add usecase catalog create_product

# 2. Scaffold an HTTP handler for it
vandor add:http-handler

# 3. If you need a new database schema
vandor add:schema

# 4. Generate Ent.go code
vandor vpkg exec official/entgo generate

# 5. Create a migration
vandor vpkg exec official/atlas migrate-diff

# 6. Sync the generated wiring code
vandor sync all

# 7. Start developing
vandor dev:app

Your domain logic is yours to write. The infrastructure scaffolding is handled by the packages.

Step 5: Run the Doctor

After installing packages or when something is not working right, run the doctor. It inspects your project and reports issues.

# Diagnose problems
vandor vpkg doctor

The doctor checks things like:

• Are all installed packages properly wired?
• Are required configuration values present?
• Are Go module dependencies in sync?
• Are there missing or broken generated files?

If the doctor finds issues, it tells you exactly what is wrong and how to fix it. Or you can let it fix things automatically:

# Auto-fix detected issues
vandor vpkg doctor --fix

Step 6: Remove a Package

If you no longer need a package, remove it cleanly:

vandor vpkg remove @official/redis-cache

This removes the package files from your project and updates the lockfile. However, it does not automatically remove code that depends on the package -- you will need to clean up imports and usages manually.

Step 7: Sync from Lockfile

When you clone a project or pull changes from a teammate who added new packages, use sync to bring your local project in line with the lockfile.

# Sync all packages from the lockfile
vandor vpkg sync

This ensures your local project has all the package code that the lockfile says it should have. It is similar to running npm install after pulling someone else's package-lock.json.

You can also sync the broader project state:

# Sync everything -- packages, generated wiring, etc.
vandor sync all

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

Package Tiers

Not all packages are equal. Vandor uses a tier system to help you assess quality and trust:

For production projects, start with official packages. They are designed to work together and are tested as part of the Vandor release process.

Common Patterns

Starting a New Project from Scratch

# Create the project
vandor new --module github.com/acme/myapp --tidy auto

# Add your business contexts
vandor add context catalog identity order

# Add use cases
vandor add usecase catalog create_product list_products
vandor add usecase order create_order

# Install infrastructure
vandor vpkg add @official/http-humachi @official/entgo @official/atlas

# Scaffold handlers
vandor add:http-handler

# Run the doctor to make sure everything is connected
vandor vpkg doctor

# Start developing
vandor dev:app

Adding Infrastructure to an Existing Project

# Install the package
vandor vpkg add @official/redis-cache

# Check that everything is healthy
vandor vpkg doctor

# If needed, auto-fix configuration
vandor vpkg doctor --fix

# Sync wiring code
vandor sync all

# Continue developing
vandor dev:app

Debugging a Broken Build

# First, run the doctor
vandor vpkg doctor --fix

# Sync all generated code
vandor sync all

# Make sure Go dependencies are clean
go mod tidy

# Try building again
go build ./cmd/app

Next Steps