Nearmark

Deploy your own location-aware heritage walking guide.

Nearmark is an open-source platform for building a mobile, map-based history guide to a place – a queer-history trail, an arts walk, a pub crawl, an architecture tour, anything tied to locations in a city. Visitors open it in their phone browser (or install it as an app), explore a live map, and unlock illustrated, narrated stories as they walk – either following a guided tour or wandering in discovery mode, where stories pop up when they get near a site.

It comes with a simple admin backoffice so a non-technical team can manage all the content themselves – no code, no spreadsheets.

---

What this is

• A public mobile web app (PWA) – live OpenStreetMap map, story cards with photos, audio narration, before/after photo sliders, guided tours and proximity discovery. Installable to the home screen and works offline.
• An admin backoffice (/admin) – add and edit locations and tours, upload photos and audio, drag-to-reorder stops, publish/draft, manage editors. Fully keyboard- and screen-reader-accessible (WCAG 2.1 AA).
• A backend on Supabase – Postgres database, email/password admin auth, and file storage, all protected by row-level security.
• Search-engine-friendly out of the box – because the app itself is client-rendered, each deployment also serves crawlable, server-rendered pages per stop (/place/<slug>) and tour (/tour/<slug>) with Open Graph + JSON-LD, plus a live /sitemap.xml and /robots.txt. Verify the domain in Google Search Console (set VITE_GSC_VERIFICATION) and submit the sitemap.

Built with Vue 3 + Vite. Hosted free on Vercel. One codebase serves two pages: the public app (index.html) and the admin (admin.html, served at /admin).

This repository is the platform. The branding, copy, content and integrations all come from configuration – so you can stand up your own instance without editing component code.

Deeper reference: docs/FSD.md is the functional specification – features, data model, and architecture in one place.

---

Prerequisites

You'll need (all have free tiers):

• Node.js 20+ and npm – to run and build the app locally.
• A Supabase account – the backend (database, admin login, file storage).
• A Vercel account – to host the live site. (Any static host works; Vercel is the documented path.)
• A GitHub account – to fork the repo and connect it to Vercel for auto-deploys.

You do not need to be a senior engineer. If you can copy files, paste values into a form, and run a couple of commands, you can deploy this. The steps below assume you're a developer setting it up on behalf of an organisation.

---

Setup in 5 steps

1. Fork the repo

Fork this repository to your own GitHub account, then clone your fork:

git clone https://github.com/YOUR-USERNAME/nearmark-app.git
cd nearmark-app
npm install

2. Create a Supabase project

1. In supabase.com, create a new project. Pick a region near your audience and save the database password somewhere safe.
2. Open Project Settings → API and copy two values for step 4: the Project URL and the publishable (anon) key.

3. Run the schema + migrations

In the Supabase dashboard, open the SQL Editor, then paste-and-run, in order:

1. schema.sql – tables, security policies, the media storage bucket
2. seed.sql – (optional) example rows; skip it if you'll add your own content
3. Every migration-*.sql file in numerical order – migration-002-… through the highest-numbered one. Each is small, additive and idempotent (add column if not exists), so run them all to bring the schema up to date; re-running is harmless. The last one, migration-041-data-api-grants.sql, grants the Data API roles access to the tables (required: since 2026-10-30 Supabase no longer does this automatically).

Running a client on the shared core? Any time you git pull new features, check for new migration-*.sql files and run them in each Supabase project – a missing column shows up as a "Save failed" in the admin.

Adding a new table in a migration? Grant it, or the Data API can't reach it (since 2026-10-30). schema.sql sets alter default privileges so tables created after it inherit the grants automatically; if a project predates that, add explicit grants in the migration (grant select on public.your_table to anon; + full CRUD to authenticated, service_role) — see migration-041-data-api-grants.sql for the pattern.

Then create your first admin user: Authentication → Users → Add user → Create new user, set an email + password, and tick Auto Confirm User. Keep "Allow new users to sign up" turned off so only people you invite can reach the admin.

Branded invite emails (optional). By default invites come from "Supabase Auth". To send them from your app instead, paste the branded templates and configure custom SMTP — see supabase/email-templates/.

4. Set your .env

Copy the example and fill it in:

cp .env.example .env

At minimum set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY (from step 2). Everything else is optional – set VITE_APP_NAME, colours and copy to brand the app for your organisation. See the Configuration reference below. Run it locally to check:

npm run dev      # public app → http://localhost:5173/   admin → /admin.html
npm run size     # build, then check the JS bundle against its size budget (gzipped)

npm run size fails if the bundle grows past the budget in scripts/check-bundle-size.mjs — a guard against a heavy dependency or a lost code-split creeping in. Wire it into CI to enforce it automatically.

This is the beginning of the README. Read the rest at the original. Read the full README ↗