Maps & Location

Add geography to your directory — Mapbox-powered location fields, an embedded directory map, and a fullscreen globe whose lighting follows the visitor's time of day.

The map feature turns a flat directory into a geographic one. Submitters pin a location with autocomplete, visitors browse listings on an embedded map or a fullscreen globe, and you control the default look from the admin panel. It's powered by Mapbox GL JS and the Mapbox Search box.

Off by default until you add a token

The map flag ships enabled in config/features.config.ts, but the map only renders once you set NEXT_PUBLIC_MAPBOX_TOKEN. Without a token, map surfaces degrade to a tidy placeholder — nothing breaks. Skip this feature entirely by setting map: false.

What you get

Location on submissions — a Location section in the submit/edit form using the Mapbox Search Box for address autocomplete. Coordinates and a structured address are stored on the listing.
Embedded directory map — a flat "Map" view on the directory that plots every located listing, with marker clustering for dense areas.
Fullscreen globe — an immersive globe whose lightPreset (dawn → day → dusk → night) shifts with each visitor's local clock. A Globe / Flat toggle lets visitors switch projection.
A filter panel — search, category, pricing (All / Free / Freemium / Paid), minimum rating, and country, with a live "N locations shown" count.
Admin control — set the default projection (globe vs. flat) and lighting mode from Design → Map.

Turning it on

Fullscreen globe with clustered project markers and a filter panel — The fullscreen globe — clustered markers by region, a Filters panel (search, category, pricing, rating, country), and a Globe / Flat toggle.

How it fits together

Piece	Where	What it does
`config/map.config.ts`	config	Style, default projection, lighting schedule, initial camera
`NEXT_PUBLIC_MAPBOX_TOKEN`	env	Public Mapbox token (required to render)
`LocationPicker`	`components/forms/`	Address autocomplete in submit/edit
`DirectoryMap`	`components/directory/`	Embedded flat map with clustering
`GlobeExperience`	`components/directory/`	Fullscreen globe overlay
`MapFilterPanel` / `MapDetailPanel`	`components/directory/`	Filter controls + marker popups
`GET /api/projects/map`	`app/api/projects/`	Lightweight feed of every located, live listing
`apps.latitude` / `longitude` / `address_*`	DB	Coordinates + structured address on each listing
`site_settings` key `"map"`	DB	Admin's default projection + lighting

See Map Config for every tunable, and the Schema Overview for the location columns.

The Standard style, globe & lighting

The map uses the Mapbox Standard style (mapbox://styles/mapbox/standard), which supports both globe projection and four light presets — Dawn, Day, Dusk, and Night. In auto lighting mode, the globe resolves a preset from the visitor's local hour using the schedule in map.config.ts, so a visitor in Tokyo and one in New York see different skies at the same moment. Admins can pin a single preset instead.

When the globe shines

The globe is a great hero for local and travel directories — restaurants, coworking spaces, events, city guides. For a global SaaS list where location is incidental, set defaultProjection: 'mercator' (flat map) or leave map: false.

Admin: default projection & lighting

Go to /admin/design → Map tab (the tab only appears when map is enabled). Choose:

Default projection — Globe (fullscreen) or Flat map. Visitors can still toggle.
Lighting — Auto (follows each visitor's time of day) or a fixed preset.

Changes save to the site_settings table (key "map") and apply site-wide without a redeploy. The editor shows a live preview and warns if NEXT_PUBLIC_MAPBOX_TOKEN is missing.

Graceful degradation

Every map surface checks for a token first. With no token set:

The directory map and globe render a styled placeholder instead of a broken canvas.
The submit form's Location section is hidden, so submissions still work.
GET /api/projects/map still responds (the feature flag, not the token, gates the route).

This means you can ship with map: true and add the token later without touching code.

AI Prompt· Set up the map for my niche

My directory is about {your niche, e.g. "specialty coffee shops"}. The map feature is enabled in config/features.config.ts.

Confirm what I need in .env.local for the map to render (the Mapbox token variable).
In config/map.config.ts, recommend a defaultProjection and lighting mode that fit my niche, and explain why.
Tell me where submitters add a location and how to backfill coordinates for listings I import.

Follow the conventions in CLAUDE.md. Don't touch unrelated files.