Step 1 — Install & set up

1. Install

npm install @ubhub/maps maplibre-gl

maplibre-gl (v4–v6) renders the map; skip it if you only call the API. Works with the Next.js App Router (tested with Next.js 16) and React 18 or 19.

2. Get an API key

Create a key in your dashboard and allow basemap (map), geocode (search) and route (routing).

3. Add the key and a server route

API keys are secrets, and the API refuses browser calls from other sites. The key lives on your server; the browser calls a small route that adds it. Store the key first:

UBHUB_API_KEY=geo_your_key_here

import { createUbHubHandler } from "@ubhub/maps/next";

// Reads process.env.UBHUB_API_KEY from .env.local automatically.
// Same as: createUbHubHandler({ apiKey: process.env.UBHUB_API_KEY })
export const { GET } = createUbHubHandler();

createUbHubHandler() reads process.env.UBHUB_API_KEY from .env.local for you — that is the whole wiring from your .env to the code. Pass createUbHubHandler({ apiKey: process.env.UBHUB_API_KEY }) to be explicit or read a different variable. Restart next dev after editing .env.local.

It forwards only /v1/geocode, /v1/route and the basemap files; anything else returns 404. In production, gate it with createUbHubHandler({ authorize }).

Calling the API directly in server code (route handlers, server actions) uses the same variable: new UbHubGeo({ apiKey: process.env.UBHUB_API_KEY! }). The browser never sees it — client code goes through the route above.

4. Import the styles

// app/layout.tsx (import global CSS once)
import "maplibre-gl/dist/maplibre-gl.css";
import "@ubhub/maps/styles.css";