Wayfarer — a personal travel journal

Wayfarer is a colourful web app for keeping track of the places you have been, and for dreaming about the next ones. Add a country and a city (plus an optional date, a short note and photos) and the country lights up on a world map, with a progress ring showing how much of the world you have covered. An Explore tab uses your passport to show where you can travel easily. It works in English and French, in light and dark mode, on desktop and phone.

Live demo: https://wayfarer-travel-journal.vercel.app

Features

Your journal

• Interactive world map that highlights every country you have visited; click any country to add a place to it
• Add, edit and delete places (city with suggestions per country, date, short note)
• "My places" list, plus counters for countries, cities and memories
• World progress ring: the share of the world's countries you have visited
• Dream list (wishlist): mark countries you want to visit; they show in a second colour on the map, can be added from Explore, and become a normal place with one click on "I went!"
• Search bar for countries and cities (accent-insensitive, English or French); type-to-search country fields everywhere
• Photos (signed-in accounts): up to 5 pictures per place, shown as thumbnails and in a full-screen gallery. Pictures are shrunk in your browser (their hidden GPS data is removed) and stored privately
• Share and friends (signed-in accounts): pick a username, then choose what others see (your map and countries always; your cities and dream list if you allow it). Friends you accept always see it, and anyone with your link /u/your-username can too if you turn that on. Photos, notes and dates are never shared on your page. Add friends by username and open their map from the Friends tab
• Photo permission: a friend can ask to see your photos; you allow or decline, and you can revoke it at any time. Only allowed friends can see them (never link visitors), and their photo links expire after 10 minutes
• Profile (signed-in accounts): an avatar button in the top bar opens your profile card, where you set a display name and pick an initial, a fun sticker or an uploaded photo

Explore

• Passport checker: pick your passport and the map shows where you can go visa-free, with a visa on arrival, with an e-visa, or only with a visa
• Schengen residence permits: say you hold a residence permit from a Schengen country and the other Schengen countries show as accessible for up to 90 days in any 180
• Near me: use your device location (it never leaves your browser) or pick the country you are in to see the closest easy destinations with distances, and add any country to your journal

Everywhere

• English and French: follows your browser language, with an EN/FR toggle that remembers your choice
• Light and dark mode: follows your device setting, with a toggle that remembers your choice
• Phone friendly: hamburger menu, touch-sized controls, smooth animations (they respect "reduce motion")
• Installable: add Wayfarer to your phone's home screen and it opens full screen like an app, with its own icon
• Works instantly with no account: your journal is saved in your browser
• Optional account (email + password): your journal is saved in the cloud and follows you across devices
• Private by design: each account can only ever read and change its own data

Tech stack

• Next.js (App Router) with React and TypeScript
• Supabase for accounts, the database (Postgres with row-level security) and private file storage
• react-simple-maps and world-atlas for the map
• flag-icons for flags
• passport-index-dataset for visa rules (see "Visa data")
• Hosted on Vercel

How it works

Situation	Where your data is stored
Not signed in	Places and dream list in your browser (localStorage). Nothing leaves your device. Photos and profile need an account.
Signed in	Places in the travel_entries table, photos in entry_photos plus a private storage bucket, display name, avatar and dream list in your account profile.

If you used the app before signing in, Wayfarer offers to import your browser journal into your new account the first time you sign in.

Sharing note: other people never read your tables directly. They only get what the get_shared_profile function in supabase/social.sql returns (the countries you visited, plus cities and dream list if you allow them), and only if you are their friend or you turned the link on.

Security note: the NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY is meant to be public (it ships to the browser). What keeps data private is the row-level security in supabase/schema.sql and supabase/photos.sql, which only let a user touch rows and files that belong to them. Never put a service_role or sb_secret_... key in this project.

Project structure

src/
  app/page.tsx              Main screen: overview, my places, add/edit form
  app/auth/callback/        Handles the link in the confirmation email
  app/u/[handle]/           Public page of a shared journal
  components/               WorldMap, Explore, SearchBox, CountryPicker, WorldProgress,
                            AccountDialog, AccountMenu, ProfileEditor, photo components, toggles
  lib/                      Countries, cities, visa and Schengen rules, search, translations
                            (messages.ts), photo and avatar helpers
  lib/supabase/             Supabase clients (browser + server) and env helpers
  proxy.ts                  Keeps signed-in sessions fresh (Next.js proxy)
public/icons/               App icon (home screen)
public/visa/                Visa data, one small file per passport
supabase/schema.sql         Places table and security rules
supabase/photos.sql         Photos table, private storage bucket and their rules
supabase/social.sql         Usernames, friendships and the functions that control what others see
supabase/photo-access.sql   Permission for friends to see your photos

---

Install it on your phone

Open the live site, then:

• iPhone / iPad (Safari): tap the Share button, then Add to Home Screen.
• Android (Chrome): open the ⋮ menu, then Install app (or Add to Home screen).
• Desktop (Chrome / Edge): click the install icon at the right of the address bar.

The icon lives in public/icons/ (icon.svg is the source) and the app details in src/app/manifest.ts. There is no offline mode yet: the app needs a connection to load.

---

Run it on your computer

You need Node.js (v20 or newer) and pnpm.

git clone https://github.com/Yerima18/wayfarer-travel-journal.git
cd wayfarer-travel-journal
pnpm install
pnpm dev

Open http://127.0.0.1:3000. Without any extra setup the app runs in local mode (places saved in your browser only). To enable accounts, follow the Supabase steps below.

Set up Supabase (accounts and cloud sync)

1. Create a project at supabase.com (the free plan is enough).
2. Get your keys: in your project go to Project Settings → API Keys and copy the Project URL and the publishable key (it starts with sb_publishable_).
3. Add them locally: copy .env.example to .env.local and fill it in:

   NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
   

   .env.local is gitignored, so your keys are never pushed to GitHub.
4. Create the table: open SQL Editor in Supabase, paste the whole content of supabase/schema.sql, and run it. This creates the travel_entries table and the security rules. You only do this once.
5. Enable photos (optional): in SQL Editor, paste and run supabase/photos.sql once. It creates the entry_photos table and a private entry-photos storage bucket, both readable only by their owner.
6. Enable sharing and friends (optional): in SQL Editor, paste and run supabase/social.sql once. It creates the profiles and friendships tables and three functions that decide what a visitor may see.
7. Enable photo sharing with friends (optional): after steps 5 and 6, run supabase/photo-access.sql once. It adds the permission table and the storage rule that lets an allowed friend read your photos.
8. Allow email + password sign-in: Authentication → Providers → Email must be enabled (it is by default).
9. Tell Supabase your site address: Authentication → URL Configuration
   • Site URL: http://localhost:3000 for local work (use your Vercel URL in production).
   • Redirect URLs: add http://localhost:3000/auth/callback.
10. Restart pnpm dev, click Sign in → Create an account, confirm your email, and add a place.

Deploy your own copy on Vercel

1. Fork or push this repo to your own GitHub account.

2. Go to vercel.com/new and import the repository. Keep the Next.js preset.

3. Before deploying, open Environment Variables and add exactly these two (names must match letter for letter):

   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

4. Click Deploy. Vercel gives you a URL like https://your-app.vercel.app.

5. Back in Supabase, Authentication → URL Configuration:

   • set Site URL to your Vercel URL
   • add https://your-app.vercel.app/auth/callback to Redirect URLs

   If you skip step 5, the confirmation link in sign-up emails will not work.

Any later git push to main redeploys automatically. If you change an environment variable in Vercel, trigger a redeploy for it to take effect.

Troubleshooting

Problem	Likely cause and fix
"Account sync is ready to connect" in the sign-in window	The two environment variables are missing or misspelled. Fix them (locally or in Vercel) and redeploy/restart.
Confirmation email link goes to the wrong page or errors	Site URL / Redirect URLs in Supabase do not match your site address (step 9 / step 5 of the Vercel section).
"Sync issue" badge after signing in	The travel_entries table does not exist yet. Run supabase/schema.sql.
"Your photos could not be loaded"	The photos table or bucket does not exist yet. Run supabase/photos.sql.
"Your friends could not be loaded" or the share dialog fails	The sharing tables do not exist yet. Run supabase/social.sql.
Asking a friend for photos fails	The permission table does not exist yet. Run supabase/photo-access.sql.
Places disappear when switching browsers	You are not signed in. Browser-only places stay in that browser; sign in to sync.
Confirmation emails do not arrive	Supabase's built-in email sender is rate-limited on the free plan. Wait a bit, check spam, or turn off "Confirm email" in Authentication → Providers → Email while testing.

Scripts

pnpm dev     # start the dev server
pnpm build   # production build
pnpm start   # run the production build
pnpm lint    # run ESLint

Visa data

Residence-permit rules are only modelled for the Schengen area. Other countries have their own rules for permit holders that are not in the dataset, so they are intentionally not guessed.

The Explore tab uses the open passport-index-dataset (MIT). It was last updated in January 2025, so treat it as a guide and always confirm with the official government or embassy website before booking.

To refresh it, download passport-index-matrix-iso2.csv from that repository and run:

node scripts/build-visa-data.mjs path/to/passport-index-matrix-iso2.csv path/to/folder-with-d3-geo-and-topojson-client

The script writes one small file per passport to public/visa/ and the country centres in src/lib/centroids.json. The last argument is a folder where d3-geo and topojson-client are installed (needed only for the centres).