Installation

• Introduction
• Installing Vuka
• Creating a First Project
  • Starting a Web App
• Everyday Commands
• Setting Up Your Editor
• Rendering UI

Introduction

This page gets the vuka command onto your machine and runs a first program. Vuka needs Go 1.25 or newer.

An app with a frontend or framework islands (Vue, React, Svelte) also needs Node.js 20 or newer and npm 11 or newer (Node.js 24 and newer ship it; on Node.js 20 or 22, npm install -g npm@11).

NOTE

npm 10 fails installing a new app's frontend packages from scratch. The package-lock.json that vuka new writes lets npm 10 install them with npm ci, and vuka warns; adding packages (vuka add island --react) needs npm 11, and vuka stops with E0610 until it's there. vuka doctor shows the npm it finds.

A Vuka project is an ordinary Go module, so once the command is installed you work with the same toolchain, dependencies and editor setup you already use for Go.

Installing Vuka

Install the command with your own Go toolchain:

go install github.com/vuka-lang/vuka/cmd/vuka/v2@latest

Installing with your own toolchain matters: Vuka parses Go with the standard library of the Go that built it, so it understands the same Go you write.

Creating a First Project

A Vuka project is a Go module. Create one:

mkdir hello && cd hello
go mod init hello

Save this as main.vuka, then run vuka mod tidy (it adds the Vuka runtime, the small package holding Result and Option) and vuka run .:

package main

import (
	"errors"
	"fmt"
	"os"
)

func greeting(name string) Result[string] {
	if name == "" {
		return Err(errors.New("who should I greet?"))
	}
	return Ok("Hello, " + name + "!")
}

func main() {
	name := "Vuka"
	if len(os.Args) > 1 {
		name = os.Args[1]
	}
	match greeting(name) {
	case Ok(text):
		fmt.Println(text)
	case Err(e):
		fmt.Println("error:", e)
	}
}

The program uses Result & Option and match, two of the additions Vuka makes to Go.

Starting a Web App

For a web app — pages, sign-in, a database with migrations, tests — vuka new shop makes one that runs; see Getting started with web.

Everyday Commands

These are the commands you use most; each mirrors a go command:

vuka run .	run, like go run
vuka build	build, like go build, and refresh build/
vuka test ./...	test, like go test
vuka mod tidy	go mod tidy, seeing .vuka imports too
vuka explain main.vuka	show what each line becomes in Go

.vuka and .go files live side by side in the same packages and call each other — see Source Files. Dependencies are Go's: go get a module and import it from any .vuka file. See Using Go Code.

Setting Up Your Editor

Install the VS Code extension from editors/vscode and gopls. See Editors.

Rendering UI

A web page is a .vuka.html shape under pages/: package, imports, one struct, decorated hooks and methods in its <script lang="go">, and below it the markup they render.

Pages use [id] names and _layout.vuka.html, and main.go constructs web.New(pages.Routes(), …). See Web getting started.