Installation

Install the Gonvex CLI and browser SDKs through npm. The self-hosted Go runtime is a separate process or container.

New Project

npm create gonvex@latest my-app

Equivalent package-manager commands:

pnpm create gonvex my-app
yarn create gonvex my-app
bun create gonvex my-app

The current initializer ships one TypeScript template: vite-react. It creates the app locally; pass --runtime-url to provision and connect it to a running runtime in the same command.

Existing Project

npm install @gonvex/client @gonvex/react
npm install --save-dev @gonvex/cli
npx gonvex init

gonvex init copies missing starter files without overwriting existing files:

gonvex/
  schema.go
  messages.go
  _generated/
gonvex.json
.env.local entries
package.json scripts

Recommended scripts:

{
  "scripts": {
    "dev": "gonvex dev -- vite",
    "gonvex:dev": "gonvex dev",
    "gonvex:once": "gonvex dev --once"
  }
}

CLI Distribution

@gonvex/cli exposes the gonvex binary. It scans app-local Go declarations, generates bindings, bundles the backend source, and syncs it to the runtime. The runtime compiles and loads the uploaded Go bundle, so application workstations do not need a local Go toolchain when using a remote or containerized runtime.

Runtime Options

You can use Gonvex in three modes:

Local runtime
  Best for development. Runtime, Postgres, and Valkey run locally.

Self-hosted runtime
  You run Gonvex runtime, landlord database, tenant databases, and optional object storage.

Hosted runtime
  A future managed service. There is no generally available public Gonvex Cloud today.

Environment Variables

A local project typically needs:

GONVEX_PROJECT_ID=prj_2x7k9...
GONVEX_RUNTIME_URL=http://localhost:8080
GONVEX_PROJECT_KEY=gvx_dev_...
VITE_GONVEX_PROJECT_ID=prj_2x7k9...
VITE_GONVEX_URL=http://localhost:8080
VITE_GONVEX_WS_URL=ws://localhost:8080/ws

The runtime needs landlord database configuration, tenant database connections, and a reachable VALKEY_URL (or REDIS_URL). Valkey is mandatory: startup fails before serving traffic when the variable is unset or the connection cannot be established. Application code should not hardcode tenant database URLs directly.

Local development services can be started from the monorepo with:

make services

This starts Postgres and Valkey from infra/docker-compose.dev.yml. File storage is optional. If your app uses file APIs, attach any S3-compatible storage provider. For local testing only, this repo includes an example MinIO service:

make storage

Vite also needs a public WebSocket URL for the browser bundle:

VITE_GONVEX_WS_URL=ws://localhost:8080/ws

For a remote self-hosted runtime:

VITE_GONVEX_WS_URL=wss://gonvex.example.com/ws

Generated Files

Generated files belong in:

gonvex/_generated/

Frontend code imports from there:

import { api } from "./gonvex/_generated/api";

Do not edit generated files manually.