doxa-maps/documentation/HOWTO-join-the-table.md

How to join the table

You want to build a map. Someone told you there is a repo, a dev server, and a thing called PocketBase, and now you are staring at three of them wondering which one you are supposed to touch.

Short answer: you work on your laptop, you land your work on development, and a shared server shows everyone what landed. main is production: it moves only when a maintainer publishes, and it is what the public sites and every partner embed load. That is the whole shape. The rest of this page is what each of those three is for, and the five commands you actually type.

This page is about working alongside other people. If you want to know how to build a plugin itself — the files, the build, getting it live — read develop-a-plugin-and-see-it-live.md first and come back here when you are ready to share your work.

---

The three places

1. Your laptop — the workshop

This is where you build. Everything is local and fast, and nothing you do here can affect anyone else.

bun install
bun run dev

That is the whole setup. Nothing to configure, no server to reach, no Docker. You get the Plugin Studio, dictation, hot reload on your own edits, and a local database with your own test data. Break it, reset it, fill it with nonsense — it is yours.

If your coding agent runs on a server rather than on your laptop, there is a second way to work — see CLOUD-DEVELOPMENT-ENVIRONMENT.md. Most people do not need it.

2. development — the table

When your work is ready, it goes to development. That is the one branch the whole team lands on, all day. A shared dev server follows it and reloads about every 15 seconds, so the team sees each other's work without anyone sending anyone a zip file. You do not edit on that server. You never need to log into it to do your job.

3. main — production

main is what the public sees: the public build (/cdn), the websites that embed the maps, and every partner's copy-paste snippet all load it. You never push to main. A maintainer publishes by merging development into it once the team's work is checked, and the public build follows within a few minutes.

The rule that makes this work: one plugin folder per person. You edit plugin-designs/<your-plugin>/ and nobody else does. Everything below depends on that.

---

Getting your work onto the table

Three commands, in this order, every time:

git add -A && git commit -m "what you changed"
git pull --rebase origin development
git push origin HEAD:development

If the push is rejected, someone landed first. Run the middle command again and push again. That is not an error — it is the normal case, and it is worth knowing how normal.

We measured it. In a ten-writer stress test at a far faster edit rate than a human works at:

pushes rejected, then retried	95%
merge conflicts	0
retries needed per edit	1.1 average, 3 at worst

Nearly every push got rejected. Not one caused a conflict. That is the one-folder-each rule paying off: you are all pushing to the same branch, so you collide on who goes first — but never on the same lines of code, because you are never in the same file. A rejected push costs you one extra command. It does not cost you an afternoon untangling someone else's work.

If you do hit a real conflict, it means two people edited one file. Stop and talk to the other person; that is a coordination problem, not a git problem.

---

Seeing your teammates' work on your laptop (optional)

By default your laptop only reloads on your edits. If you want teammates' landed work to arrive automatically while bun run dev is running, copy .env.example to .env.local at the repo root and set:

DX_SYNC_REMOTE=origin

That is the only line you need. .env.local is never committed, so it stays yours.

Two things it needs from you, once:

• Be on development. It only fast-forwards the branch it follows, and a fresh clone starts on main, so run git switch development (or clone with -b development).
• Read access to the repo. It fetches with your laptop's own git credentials: a credential helper, or an SSH remote your key can read. Without them nothing is pulled, and the log (and /api/dev-sync) says dev-sync needs git credentials for <remote> rather than failing quietly.

Either a remote name or a full repo URL works. origin is what almost everyone wants. A URL — https://…/your-repo.git — works too and saves you a git remote add; if the repo is private it uses the git credentials your laptop already has. Leave it unset and the whole feature is off.

If you do put a token in the URL (https://user:token@…), it is never written to the log or shown at /api/dev-sync.

Two optional dials, if you want them:

	what it does	default
DX_SYNC_BRANCH	which branch to follow	development (the table)
DX_SYNC_INTERVAL	seconds between checks	5 (minimum 2)

It only pulls when it is completely safe to. All three must be true: you are on that branch, you have no unsaved edits, and you have no local commits. If any one of them is not, it does not touch your files — it tells you instead, in the dev server log:

development is 3 commits ahead … pull when ready

So it cannot surprise you mid-thought. You can also check that any time at /api/dev-sync.

---

The database, and the one thing that surprises people

There are three databases. You work against one of the first two — never the third.

Where	What is in it	Who touches it
Your laptop	your own sandbox data	you, freely — this is the default
The team's shared one	the team's shared test data	the team — opt-in, see below
Production	what the public sees	nobody directly

You never publish a database. Not yours, not anyone's. What travels is the shape — the tables and fields — as migration files committed to the repo, in backend/pocketbase/pb_migrations/.

So adding a field is a normal change: you edit, you commit the migration, you push it like any other file, and it goes through review with everything else. A server applies new migrations when it restarts.

Make schema on your laptop, never in the shared server's database screen. PocketBase writes a migration file for every change made in its admin screen. On your laptop that file lands in your checkout, and you commit it. On the shared server it lands in a copy of the repo that is thrown away at the next restart, so the table's database and the repo drift apart.

This is deliberate. A database rule that opens something to the public arrives as a commit someone can read rather than as a setting somebody clicked at midnight. If you have ever inherited a system where the live config did not match the repo, you already know why.

Which one your laptop talks to

By default, your own. You do not configure anything. The first time you run bun run dev it starts a database on your laptop, keeps its data in .pb/, and gives you an admin screen at /api/pb/_/. A fresh clone plus bun run dev is the whole setup — no remote server, no Docker, nothing to sign into.

If your team wants everyone working against the same test data instead, that is opt-in. Add one line to .env.local:

DX_PB_URL=https://<your team's dev server>/pb

You sign in with the same team account you use for everything else — there is no separate password. Ask whoever set up your team for the address. Leave the line out and you stay on your own local one, which is the right place to be while you are finding your feet.

The only other thing here is DX_PB_PORT, which you set only if the log says port 8090 is already in use.

New collections start locked. Your plugin's data is not readable until a migration opens it — deliberately, so nothing is public by accident. That migration is a commit like any other.

---

One more thing to set

Copy .env.example to .env.local. Every line in it is optional — empty means the default, which is the all-local setup described above. You can start with none of them filled in.

The one you will probably want is a Mapbox token, which is the single credential you have to ask the team for:

VITE_MAPBOX_TOKEN=<ask the team>

Leave it empty and the Mapbox-backed maps will not draw; you can also work with the keyless MapLibre provider instead.

---

The five things to remember

1. Build on your laptop. It is fast and it is yours.
2. One plugin folder per person. This is what keeps ten people out of each other's way.
3. pull --rebase, then push to development. A rejected push is normal — 95% of them were, and none became conflicts. Never push to main: that is production.
4. The shared server is for looking, not editing.
5. Schema is a commit, never a click. You never publish a database.

---

When something is wrong

• "Your push was rejected" — normal. git pull --rebase origin development, push again.
• A real merge conflict — two people edited one file. Talk to them; the one-folder rule slipped.
• Your change is not on the shared server — it reloads about every 15 seconds, not instantly. Check your push actually landed: git log origin/development -1.
• The shared server shows an old version of your plugin — you are probably looking at what is on development, not what is on your laptop. Those are different on purpose.
• The public site does not show your change — it shows main (production), which moves only when a maintainer publishes. After a publish, a browser can keep the old maps for up to 5 minutes.