@madebylars.com/mbl-whereabout

Real-time delivery tracking module for Nuxt 4. Shows a driver's live GPS position on a MapLibre map, with optional road snapping via Valhalla.

• ✨  Release Notes

Features

• Driver GPS tracking via useDriverLocation — sends location updates to your server
• Customer real-time map via useOrderTracking + useDeliveryMap — subscribes to Supabase Realtime and updates a MapLibre marker
• Optional road snapping via a self-hosted Valhalla instance
• Peer dependency on @madebylars.com/mbl-auth — reuses your existing Supabase config

Requirements

• @madebylars.com/mbl-auth installed and configured
• maplibre-gl >=4.0.0 installed
• A Supabase project with Data API enabled (Settings → API → Data API)

Quick Setup

npm install @madebylars.com/mbl-whereabout maplibre-gl

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@madebylars.com/mbl-auth', '@madebylars.com/mbl-whereabout'],
  css: ['maplibre-gl/dist/maplibre-gl.css'],
  vite: {
    optimizeDeps: { include: ['maplibre-gl', 'cookie'] },
  },
})

Database Setup

Run the following in your Supabase SQL editor:

create table drivers (
  id uuid primary key default gen_random_uuid(),
  user_id uuid,
  name text,
  created_at timestamptz default now()
);

create table orders (
  id uuid primary key default gen_random_uuid(),
  customer_id uuid,
  driver_id uuid references drivers(id),
  status text default 'pending',
  created_at timestamptz default now()
);

create table locations (
  id uuid primary key default gen_random_uuid(),
  order_id uuid references orders(id) unique,
  driver_id uuid references drivers(id),
  lat double precision not null,
  lng double precision not null,
  accuracy float,
  snapped_lat double precision,
  snapped_lng double precision,
  updated_at timestamptz default now()
);

Note: If you enable Row Level Security on locations, add a SELECT policy for your users — without one the client-side map query will silently return no rows.

Usage

Driver page — send GPS updates

<script setup lang="ts">
definePageMeta({ driverTracking: true })
</script>

The plugin auto-starts GPS tracking when the page mounts and stops it on leave. The orderId is read from route.params.orderId.

You can also control it manually:

const { start, stop, isTracking, error } = useDriverLocation()
await start('order-uuid')

Customer page — live map

<template>
  <div id="delivery-map" style="width: 100vw; height: 100vh;" />
</template>

<script setup lang="ts">
const route = useRoute()
const { driverLocation } = useOrderTracking(route.params.orderId as string)
useDeliveryMap('delivery-map', { driverLocation, zoom: 15 })
</script>

Road Snapping (optional)

Start a Valhalla instance (a docker-compose.yml is included in this repo for local development), then set:

// nuxt.config.ts
mblWhereabout: {
  valhallaUrl: 'http://localhost:8002',
}

Location updates will be snapped to the nearest road before being stored.

Module Options

| Option | Default | Description | |--------|---------|-------------| | valhallaUrl | http://localhost:8002 | Valhalla road-snapping endpoint | | tileUrl | OpenStreetMap tiles | Map tile URL passed to MapLibre |

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release