@abdallemo/routegen-client

End-to-end type-safe routing for Go 1.22+ and TypeScript.

This is the frontend client for go-route-gen. It provides a strictly-typed Axios wrapper that consumes route definitions generated directly from your Go standard library (net/http) handlers.

Get tRPC-style type safety across the network boundary without switching to a heavy backend framework.

Features

• Strict Route Matching: TypeScript won't let you request a route that doesn't exist in your backend.
• Path Parameter Validation: Automatically detects {id} segments in your Go routes and requires them as typed arguments in the frontend.
• Global Lifecycle Hooks: Centralized onError and onUnauthorized handling.
• Lightweight: A thin, powerful wrapper around Axios.
• Framework Agnostic: Works with React, Vue, Svelte, or vanilla TS.

Installation

npm install @abdallemo/routegen-client

Note: You also need the Go CLI to generate your route definitions.

Quick Start

1. Initialize the Client

Point the client to the API_ROUTES file generated by the route-gen CLI.

import { GoApiClient } from '@abdallemo/routegen-client'
import { API_ROUTES } from './route' // The file generated by the Go CLI

export const api = new GoApiClient<typeof API_ROUTES>({
  baseURL: 'http://localhost:8080',
  hooks: {
    onError: (message, status) => {
      console.error(`[API Error ${status}]:`, message);
    },
    onUnauthorized: () => {
      // Redirect to login, clear storage, etc.
      window.location.href = '/login';
    }
  }
})

2. Make Type-Safe Requests

The .request() method enforces the method/path string and validates path parameters.

// 1. Static Route
const users = await api.expect<User[]>().request('GET /users')

// 2. Dynamic Route with Path Parameters
// If the Go route is "DELETE /customer/{id}", TS requires the second argument:
await api.expect<void>().request('DELETE /customer/{id}', { id: 101 })

// 3. Post Data
await api.expect<User>().request('POST /users', {}, { name: 'Abdalle' })

Advanced Configuration

Strict Mode vs. Loose Mode

By default, the client is in Strict Mode. It will only allow strings that exist in your API_ROUTES.

If you need to hit external endpoints or routes not yet managed by the generator, you can enable Loose Mode by passing false as the second generic:

// Autocomplete works for internal routes, but arbitrary strings are allowed
const api = new GoApiClient<typeof API_ROUTES, false>({ ... })

Custom Axios Instance

If you have an existing Axios setup with complex interceptors, you can pass it directly:

const api = new GoApiClient<typeof API_ROUTES>({
  axiosInstance: myExistingInstance
})

How it works

The go-route-gen ecosystem bridges the gap between Go 1.22's new routing patterns and modern TypeScript frontends. By scraping your Go AST for METHOD /path patterns, it creates a union type of all available endpoints, ensuring your frontend is always in sync with your backend handlers.

License

MIT © Abdallemo