doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README: what a fresh reader hit, fixed (V8 fresh-reader test)

Browse source 
A clean clone of development, run with no settings and only the README:
- The drop-in's `bun run build && bun run dropin` stopped at the build, which refuses without
  BUILD_ALLOW=1, so dropin never ran. The built maps are in the repo: the route is now
  `EMBED_BASE_URL=https://your-site bun run tree` then `bun run dropin`, with the one-bundle rebuild for
  changed plugins. Without the tree step the manifests' snippets stay relative and no other site can paste
  them (measured: embedBase "." before, the site's address after, and the snippet's page answered 200).
- smoke:studio checks :5173 by default; when Vite took another port it measured a different server.
  The step now passes the printed URL, and says it drives a headless browser.
- `bun run serve` crashes if 4173 is taken; PORT=<n> works and is now named.
- Vite prints http://127.0.0.1:5173/, not localhost.
- The sync example's branch must exist on the remote; the public repo has only main.
- bun run dev also downloads and starts a local PocketBase on 8090; now said. A copied template keeps
  its element name until renamed as its README says.
This commit is contained in:
Doxa Maps 2026-09-29 08:35:01 +00:00
parent 3575631935
commit 6289d3b969
1 changed files with 16 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
README.md
View file

@ -379,9 +379,15 @@ serves every map: one server, no PocketBase, nothing else to run. Set `dropin.de
`vite.doxa-maps-build-config.json` to your site's `public/` (the default is `../doxa-life/public`), then:
```bash
bun run build && bun run dropin # copies dx-maps/ into your site's public/; the rest of the site is left alone
EMBED_BASE_URL=https://your-site bun run tree # seconds: writes your address into the copy-paste snippets
bun run dropin # copies dx-maps/ into your site's public/; the rest of the site is left alone
```
The built maps are already in the repo, so no build is needed. If you changed a plugin, rebuild just that
one first: `BUNDLE=<name> bun x vite build`. Without `EMBED_BASE_URL`, the pages still work, but the
snippets in `manifest.json` stay relative (`./…`) and other sites can't paste them. `bun run tree` rewrites
the manifests in this repo's `public/`; `git restore public` puts them back after the copy.
This route is proven on DX Life: real pages rendering maps, one server, every production map passing
its embed checks, copy-paste snippets included. Its drop-in branch copies the folder into `public/` and
fills `/research` with the Research Gallery.
@ -703,8 +709,10 @@ cp .env.example .env # optional: paste your pk. token after VITE_MAPB
bun run dev # → open the URL Vite prints: that page is the Plugin Studio
```
No build needed first — the built maps are already in the repo. To start a plugin, copy
`plugin-designs/template-bundle/` to `plugin-designs/<your-map>/`; the studio finds it automatically.
No build needed first — the built maps are already in the repo. `bun run dev` also starts a local
PocketBase on port 8090 for the plugins that use a backend; it is downloaded on the first run. To start a
plugin, copy `plugin-designs/template-bundle/` to `plugin-designs/<your-map>/`; the studio finds it
automatically. Then rename it as its own `README.md` says.
To put the maps on your own site, take [the easiest path: drop-in](#where-the-folder-goes-three-routes).
@ -713,7 +721,7 @@ To put the maps on your own site, take [the easiest path: drop-in](#where-the-fo
The studio is a plugin like any other: `plugin-designs/plugin-studio/plugin-studio.vue`.
1. Run `bun run dev` and open the URL Vite prints (http://localhost:5173/ unless that port is taken) — that page *is* the studio.
1. Run `bun run dev` and open the URL Vite prints (http://127.0.0.1:5173/ unless that port is taken) — that page *is* the studio.
2. Edit `plugin-studio.vue` (or ask your agent to). The page updates as you save.
3. When it looks right, build just the studio and refresh its security hashes:
@ -722,7 +730,8 @@ The studio is a plugin like any other: `plugin-designs/plugin-studio/plugin-stud
bun run fix:sri
```
4. Check it opens every plugin: `bun run smoke:studio` (with `bun run dev` running).
4. Check it opens every plugin, with `bun run dev` running: `bun run smoke:studio -- --url <the URL Vite printed>`.
It drives a headless browser (Playwright's Chromium).
</details>
@ -743,7 +752,7 @@ The studio is a plugin like any other: `plugin-designs/plugin-studio/plugin-stud
| `bun run dev` | The Plugin Studio, updating as you save, at the URL Vite prints |
| `BUNDLE=<name> bun x vite build` | Build one plugin only |
| `BUILD_ALLOW=1 bun run build` | Build everything into `public/dx-maps/` (~4 min; refuses without the flag, to protect a shared project) |
| `bun run serve` | Serve the built output folder — the Plugin Studio is http://localhost:4173/dx-maps/index.html |
| `bun run serve` | Serve the built output folder — the Plugin Studio is http://localhost:4173/dx-maps/index.html (`PORT=<n> bun run serve` if 4173 is taken) |
| `bun run gates:pre` · `bun run gates:post` | The checks that keep `main` working |
| `bun run shots` | Retake these screenshots (`ONLY=<name>` for one) |
@ -767,7 +776,7 @@ branch (an agent on a server, or the whole team), add two lines to `.env.local`
```bash
DX_SYNC_REMOTE=origin # a remote name or a repo URL; a private repo uses your usual git credentials
DX_SYNC_BRANCH=development # the default; main is production and moves only on a publish
DX_SYNC_BRANCH=development # the default: your team's shared branch (the public repo has only main)
```
Every few seconds the dev server fetches that branch, fast-forwards your checkout and hot-reloads what