Vorma Documentation

Wave is a Go-based build system for web applications. It manages static asset processing, CSS compilation (via esbuild), file watching, hot reloading, and optional Vite integration for JavaScript/TypeScript.

Key characteristics:

• No external tooling required: Orchestrated entirely from within your Go repository and dependencies.
• Unified Pipeline: Provides both development (with browser refresh and CSS hot reloading) and production (with asset hashing, minification, and critical CSS inlining) modes.
• Versatile: Can be used as a full frontend build tool or as a simple file watcher that restarts a server upon file changes.

Vorma is a full-stack framework for Go that provides a developer experience similar to Next.js, Remix, or TanStack Start. It uses Go for the backend and supports React, Solid, or Preact for the frontend.

Key features include:

• Nested routing
• End-to-end type safety (extending to Link components)
• Parallel-executed route loaders
• Vite integration for full Hot Module Replacement (HMR) during development.

A Task is a fundamental primitive in Vorma. It is a function that takes an input, returns data (or an error), and is guaranteed to run a maximum of one time per unique input value within a specific execution context (e.g., a web request lifecycle).

Key characteristics include:

• Automatic Memoization: Results are cached per input within the context to prevent redundant work.
• Deduplication: If multiple tasks depend on the same sub-task, that sub-task runs only once.
• Type-Safety: Uses Go generics to ensure compile-time safety for inputs and outputs.
• Concurrency Support: Designed to be thread-safe and supports parallel execution via ctx.RunParallel.

import "github.com/vormadev/vorma/kit/tasks"

// A Task is essentially a wrapper around a function with this signature:
// func(ctx *tasks.Ctx, input T) (R, error)

Vorma manages deployment mismatches (skew) through two primary mechanisms:

1. Automatic Safe Hard Reloads: During standard route navigation or route data revalidation, if Vorma detects an outdated build ID, it automatically performs a hard reload. This ensures the client gets the latest HTML, entry module, and CSS without disrupting the user experience.
2. Event Dispatching: During API queries or mutations, where a hard reload might be disruptive, Vorma dispatches a build ID change event instead. This allows developers to handle the update gracefully via addBuildIDListener.

When combined with Vercel Skew Protection, API requests from outdated clients are routed to the correct deployment via the x-deployment-id header, preventing errors during the transition period.

Vorma automatically generates a TypeScript file (conventionally at ./frontend/src/vorma.gen.ts) to provide end-to-end type safety between your Go backend and frontend.

This file includes:

• Loader and action route definitions (inputs, outputs, patterns, and param keys).
• Ad hoc types shared from the backend.
• Extra TypeScript code generated from the Go-based builder (constants, enums).
• App-specific type helpers for links and other features.
• A vormaViteConfig object for use in your vite.config.ts.

You can customize the output path of this file using the Vorma.TSGenOutPath field in your Wave configuration.

Wave is the lower-level build tool used by Vorma. It provides hot reloading without requiring external tool installation.

• Configuration: Use backend/wave.config.json to customize the names and locations of project items. This file can be renamed or moved, provided you point to it when instantiating the Wave instance in Go.
• Development: backend/wave.dev.go handles Wave instantiation for development (using the !prod Go build tag).
• Production: backend/wave.prod.go handles Wave instantiation for production (using the prod Go build tag). In production, static assets are typically embedded into the compiled Go binary for performance.

Vorma provides reactive location data across different UI libraries. While the APIs are identical for React and Preact via a hook, Solid uses a direct accessor to leverage its fine-grained reactivity.

• React/Preact: Use the useLocation() hook from vorma/react or vorma/preact.
• Solid: Use the location accessor from vorma/solid. Note that location is a function that must be called to access properties (e.g., location().pathname).

// React (or Preact)
import { useLocation } from "vorma/react";

function Component() {
	const location = useLocation();
	return <div>Current path: {location.pathname}</div>;
}

// Solid
import { location } from "vorma/solid";

function Component() {
	return <div>Current path: {location().pathname}</div>;
}

Vorma uses nested data loaders tied to URL segments to preload data for routes in parallel. This process occurs in a single request, ensuring that response headers are merged predictably and preventing data drift or inconsistency across different route segments.

Key benefits of this model include:

• Single-request model: All data for the matched route segments is fetched in one go.
• Coalescing/Memoization: Because loaders run within a single request, you can use the vorma/kit/tasks primitive to ensure expensive or repetitive operations (like user authentication checks) only run once per request, even if multiple route segments require them.