Your first Velocity app in 60 seconds

This is the shortest tutorial we'll publish. Four commands, about a minute, and you'll be looking at a working Velocity app in your browser.

Prerequisites

You need:

• Go 1.26+ — go version should print go1.26 or newer.
• Homebrew — for installing the velocity CLI on macOS or Linux. (Other platforms can build from source; see the installer repo.)
• Bun (recommended) or Node + npm — for the JS side. The installer picks up whichever it finds.

No Docker, no external services to start. The project-local ./vel binary handles the dev server, migrations, and code generation once the project exists.

1. Install the installer

brew install --cask velocitykode/tap/velocity

Verify it landed:

velocity --version

You should see the installed version string. The velocity CLI is project-bootstrap-only; once a project exists, you'll use the project-local ./vel binary for everything else.

2. Scaffold a new project

velocity new acme

acme is the placeholder name we use throughout these tutorials — pick whatever fits your project.

The installer asks three quick questions:

• Project type — Full stack (Inertia + Vite) for the React + Tailwind setup this tutorial uses.
• Database — sqlite for the easiest local default. Postgres and MySQL are available and swap in via env var later.
• Enable Inertia server-side rendering? — N for development. Flip to Y later if you need it.

Use ← / → to toggle, enter to confirm.

Once you've answered, the installer clones the template, configures the Go module, initializes git, installs dependencies, builds the project-local ./vel binary, runs the initial migrations, and prints the next two commands you need:

The whole thing takes well under a minute on a warm machine.

3. Start the dev server

cd acme
./vel serve

This boots the Go backend with hot-module-reload, runs Vite for the frontend in parallel, and prints something like:

[velocity] listening on http://localhost:4000
[vite]     dev server ready in 230ms

4. Open the app

Navigate to http://localhost:4000.

You'll land on the login page. Register an account, log in, and you're on the dashboard. Every primitive Velocity ships — auth, ORM, queues, cache, mail, storage, broadcasting, scheduling — is wired and ready to use.

Find your way around

Here is what velocity new acme produced. The directories you'll touch most are at the top.

acme/
├── main.go               # Bootstrap chain: Providers, Middleware, Routes, Run
├── go.mod
├── .env                  # Local config (DB driver, secrets, etc.)
│
├── routes/
│   └── web.go            # Web routes (the first file you edit)
│
├── internal/
│   ├── app/              # App-level wiring (kernel, middleware stacks, events)
│   ├── handlers/         # HTTP handlers (auth, dashboard, home, health)
│   ├── middleware/       # Custom middleware
│   ├── models/           # ORM models (the starter ships User)
│   └── commands/         # Custom ./vel commands
│
├── config/               # Typed config: app.go, auth.go, crypto.go, view.go
│
├── database/
│   ├── migrations/       # Go migration files
│   ├── factories/        # Model factories for tests and seeds
│   └── database.sqlite   # The local DB after first migration
│
├── resources/
│   ├── js/               # React + TypeScript (app.tsx, pages/, components/, layouts/)
│   ├── css/              # Tailwind entrypoint
│   └── views/            # Server-rendered HTML shell for Inertia
│
├── public/               # Static assets served at the URL root
├── storage/              # File storage default (uploads, logs)
└── vite.config.ts        # Frontend build config

The shortest possible walk-through:

• main.go. The bootstrap chain. Anything you wire (providers, middleware, routes, commands, events) flows through it.
• routes/web.go. Where you'll spend most of the first hour. Add a route, point it at a handler in internal/handlers/.
• internal/handlers/. HTTP handlers. The starter has auth (login, register, logout), dashboard, home, and health.
• internal/models/. Your ORM models. Starts with User. New models go here, scaffolded by ./vel make:model.
• database/migrations/. Schema. Go files, not SQL strings or YAML. New migrations come from ./vel make:migration or ./vel make:model -m.
• resources/js/. The React frontend. pages/ maps 1:1 to the Inertia responses your handlers return: c.Inertia("Posts/Index", props) renders resources/js/pages/Posts/Index.tsx.
• config/. Typed Go config files. Reads from .env at startup, exposes typed values to the rest of the app.

That is the loop. routes/web.go declares the URL. internal/handlers/ runs the logic. internal/models/ talks to the database. resources/js/pages/ renders the response.

What's next

• Add a model. ./vel make:model Post -m scaffolds a model and migration in one shot.
• Add a handler. ./vel make:handler PostsHandler gives you a handler wired to the router.
• Read the docs. vel.build/docs covers the full API surface.

That's it. Four commands, one running app. Velocity gets out of your way after that.