Installation

This page covers the practical ways to start using jetwarp:

Library users: add an adapter to your existing Go module (chi / gin / echo / fiber / stdlib).
Contributors: clone the repository, run the test suites, and (optionally) build the docs locally.

Requirements

Go 1.26+ (the repository and all submodules are currently go 1.26.0).
A Go module (go.mod) in your application.
If you want to use a framework-backed adapter, you’ll also need that framework’s dependency (for example, codeberg.org/go-chi/chi/v5 when using the chi adapter).

Add jetwarp to your Go project

jetwarp is a multi-module repository. In practice, that means you usually install one adapter module (and it brings in the core module transitively).

Pick the adapter that matches the router you want to run on:

codeberg.org/iaconlabs/jetwarp/adapter/stdlib
codeberg.org/iaconlabs/jetwarp/adapter/chi
codeberg.org/iaconlabs/jetwarp/adapter/gin
codeberg.org/iaconlabs/jetwarp/adapter/echo
codeberg.org/iaconlabs/jetwarp/adapter/fiber

1) Choose an adapter module

If you already know which router you want, install that adapter directly:

# Example: chi
go get codeberg.org/iaconlabs/jetwarp/adapter/chi@v1.0.1

Or, if you prefer the stdlib router:

go get codeberg.org/iaconlabs/jetwarp/adapter/stdlib@v1.0.1

Then tidy your module:

go mod tidy

Note: v1.0.1 is the current stable release. Pin to a specific tag and update intentionally rather than using @latest in production.

2) Import and create a router

In your application, you typically import the adapter package and call New():

import (
    "net/http"

    twchi "codeberg.org/iaconlabs/jetwarp/adapter/chi"
)

func main() {
    r := twchi.New()

    r.HandleFunc(http.MethodGet, "/healthz", func(w http.ResponseWriter, _ *http.Request) {
        _, _ = w.Write([]byte("ok\n"))
    })

    // Always check registration errors before serving traffic.
    if err := r.Err(); err != nil {
        panic(err)
    }

    _ = http.ListenAndServe(":8080", r)
}

(For a more complete example, see the examples/ pages in this book.)

Optional: OpenAPI 3.2 generation

OpenAPI support lives in an optional module:

codeberg.org/iaconlabs/jetwarp/openapi/oas3

Install it like any other module:

go get codeberg.org/iaconlabs/jetwarp/openapi/oas3@v1.0.1
go mod tidy

You can then call oas3.Attach(...) after registering routes to mount /openapi.json and an optional UI.

Contributor setup (developing jetwarp itself)

1) Clone the repository

git clone https://codeberg.org/iaconlabs/jetwarp
cd jetwarp

2) Run tests

Because jetwarp is multi-module, there are two common workflows:

Simple: run tests module-by-module (reliable everywhere).
Workspace: use a go.work workspace so go test ./... sees all modules together.

Simple (module-by-module)

From the repo root:

go test ./...

Then run the same command inside any submodule you touched (for example: adapter/chi, drivers/v1/chi, openapi/oas3, etc.):

(cd adapter/chi && go test ./...)
(cd drivers/v1/chi && go test ./...)
(cd openapi/oas3 && go test ./...)

Workspace (recommended when changing multiple modules)

If you prefer a workspace, create one locally:

go work init .
go work use ./adapter/chi ./adapter/echo ./adapter/fiber ./adapter/gin ./adapter/stdlib
go work use ./drivers/v1/chi ./drivers/v1/echo ./drivers/v1/fiber ./drivers/v1/gin ./drivers/v1/stdlib
go work use ./openapi/oas3 ./openapi/oas3/validate
go work use ./examples/students ./examples/openapi-students ./examples/openapi-scalar-students
go work sync

After that, you can generally run:

go test ./...

If you already have a committed go.work in your checkout, you can skip go work init/use and just run go work sync.

Building the docs locally (mdBook)

The project documentation is built with mdBook. CI currently installs mdBook v0.4.40 and runs:

mdbook build docs

To build the docs locally:

Install mdBook (one way is to use the same approach as CI):

curl -sSL https://codeberg.org/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz \
  | tar -xz --directory /usr/local/bin

Preview in a local server:

mdbook serve docs

Or build the static site:

mdbook build docs

Keyboard shortcuts

jetwarp