doxa-maps — a JAMstack map bundler for vibe coders

Built by a vibe coder, for vibe coders — for anyone using AI to build maps that reach every people, in every place, for Jesus.

One repo holds all your maps and turns them into embeddable apps with one command.

• One folder, not fifty — every map in one repo, on one shared component library.
• bun run dev → preview every map in a live playground, each with a copy‑paste embed snippet.
• bun run build → each map becomes a self‑contained file: drop it on any site or WordPress, compose several into a single‑page app, or wrap it as a mobile app — same code, every target.

You don't write the code. Point your AI agent at the example maps, describe what you want in plain English, and it builds a new one on the shared library.

⚠️ Maps ship without data — being JAMstack (pure JS), they fetch it (like people groups) from an API at runtime (details).

---

Have you ever dreamed of making maps?

Here's the story. Maybe it's yours too.

You got into building software right as AI made it possible for anyone to write code. And you had a vision: make maps — every map you could imagine — to advance the Kingdom of God, so that every people in every place could hear the gospel of Jesus.

So you started. And it worked… for one map. AI is great at writing a single map — a couple thousand lines of code you can embed on a website.

But then you wanted a second map. And a fifth. And a fiftieth. And here's the wall you hit:

• Every new map meant copying the whole thing into a new folder — nothing was reusable.
• Your maps grew past 2,000… 5,000… lines of tangled "spaghetti code."
• You ended up with 50 folders, 50 map projects, scattered across your machine — half of them lost.
• Each one was fragile, glitchy, and difficult to maintain, and harder to form a community around.

If that's you: you built maps for Jesus. I salute you. Those maps have their place. But you were missing one thing — a framework that lets all your maps live in one place and share reusable pieces.

That's what this is. Built for communities of map makers who want to make open source maps that can multiply everywhere.

---

Key terms (don't be afraid of these — you can learn each in one search)

New to this? Read this table first. You do not need to memorize it — just know the words exist and where to learn them.

Term	In plain words	Learn more
Vibe coder	Someone who builds with AI writing most of the code. That's who this is for.	—
JAMstack	A way of building where the front end is just JavaScript, APIs, and Markup (HTML/CSS). It runs almost anywhere — including WordPress.	jamstack.org
Bundler	A tool that takes all your code and packs it into a few ready‑to‑ship files. This repo is a bundler for maps.	vite.dev/guide
Build step	The one command (bun run build) that turns your code into those shippable files. Your agent can run it for you.	—
bun	A fast, all‑in‑one replacement for npm (installs packages, runs scripts). We use it here.	bun.sh
node modules	The reusable code packages your project depends on. If you use VUE, and VITE you need Node Modules. It is like installing libraries and dependencies that allow VUE to work. bun install downloads them into your doxa-maps folder on your laptop node_modules/.	bun.sh/docs
Dev server	A local preview website (run this command 'bun run dev' after 'bun install') that updates live as you edit. You run it, it let's you see all the maps in one place so you can give your agents feedback, and see changes almost real time when the agent makes edits. It runs at http://localhost:5173.	—
Vue / React	Popular, well‑supported frameworks for building front ends. This bundler is built on Vue + Vite. You commit to learning one.	vuejs.org
Web component	A custom HTML tag (like <doxa-map>) that works on any page, no framework required. Each of your maps becomes one.	MDN: Web Components
iframe	A safe window that embeds one site inside another. Simple, isolated. Each map comes with iframe support by default	MDN: iframe
Shadow DOM	Lets your map's JavaScript run directly inside the host page (not walled off in an iframe) so it can integrate deeply — while keeping its styles from clashing.	MDN: Shadow DOM
SPA (single‑page application)	One page that composes several maps together in a layout — a whole multi-map site from one build.	MDN: SPA
CDN	A URL that serves a file (JavaScript/CSS) to be fetched and run in a browser. When you use Mapbox, you're loading its CDN. Your built maps are served the same way. JAMstack allows these map frontends to run through a CDN, yes they are that modular! Or, you can run them directly in your site, but CDN allows them to embed via iframe onto partner websites easily with a single URL	MDN: CDN
Minify	The build shrinks your code into compact, hard‑to‑read (but still working) form — smaller and harder to copy.	MDN: Minification
Capacitor	Wraps your maps app into a real iOS/Android apps, or make a SPA ('single-page application' see above) by joining multiple maps together into a layout, and bundling that SPA into IOS/Android easily — same code, no Swift, no Flutter, no React Native.	capacitorjs.com
Lazy loading	Only loads each map when it's actually needed, so a page with many maps stays fast.	web.dev: lazy loading

---

What doxa-maps gives you

• One repository for all your maps. Each map is an application profile in app-profiles/<your-map>/.
• A shared library of reusable, parameterized components (library/ — the map, the legend, the controls, the search bar) so your maps stop duplicating code.
• Room for each map's own custom code — because real maps always have something unique.
• Rapid prototyping. Add a .vue app-profile file, rebuild, and it's live. Build hundreds of maps from one library.
• Your agent's happy place. Everything's in one folder, so your AI agent has all the context it needs to build the next map from the examples already here. Give your agent the proper context and it will have what it needs to make new maps. The only limit is our fear of new architecture, we can learn JAMstack, and see the use cases, and grow in a new framework of software design that is appropriate for open source maps that need to embed everywhere.
  • The Great Commission's Maps Everyone needs to work together to fulfill the great commission, and it will not be possible without maps. Allowing map communities to multiply open source maps that can embed onto all partner sites means doxa-maps is built to solve global mobilization problems, not just a map for centralized website.

---

The parts that make you do a backflip

• One build → many embeddable maps. bun run build turns every map into a self‑contained web component and generates a standalone HTML page for each one.
• Embed anywhere. Drop a map on your own site, a partner church's site, or WordPress — via an iframe (safe and isolated) or via shadow DOM (the map's JavaScript runs directly in the page, for deep integration and advanced features).
• Compose maps into a single‑page app. Put several maps into one layout — a whole multi‑map site — and it lazy‑loads each map so it stays fast even when there are many.
• Turn it into a mobile app. The same code runs as an iOS/Android app via Capacitor — no new language to learn. Design it mobile‑friendly right in your browser (inspect element → switch to a phone aspect ratio), then wrap it.
• Your source stays protected. The build minifies your code — it still runs perfectly, but anyone who grabs it off a partner site gets compact, hard‑to‑read output, not your clean source.
• Update once, everywhere. Serve the built maps from a CDN, and when you rebuild, every partner site that embeds a map picks up the latest version when their cache refreshes.

One codebase → your own map website · embedded on partner sites · WordPress · mobile app · standalone.

---

A word before you decide

This architecture is probably different from what you're used to. Different doesn't mean worse — it means it can make your life better and let you build the maps of your dreams.

So be honest with yourself. If you don't have big dreams about map‑making, this product might not be for you — and that's okay. But if you dream of maps that change the world and carry the gospel to places it has never been, you're going to need more than a vibe‑coded map. You'll need a framework that supports far more components than a typical one‑off map. And you'll need a community.

You can't form a community around spaghetti‑coded maps. You can form one around a shared framework with a reusable library — because then people prototype on the same foundation and build something stronger together, where maps never have to be rewritten from scratch. One problem that hinders the Great Commission, is each worker keeps their maps private source, and don't have a shared map framework to build maps on, with reusable map components in a modern framework like VUE with VITE embeddability support. Doxa-maps aims to meet this open source map gap for a global prayer movement which needs more maps, maps, maps!

Requirements — the one small wall (and it's worth it)

Someone once told me: don't reinvent the wheel — use Vue and Vite instead of hand‑rolling vanilla JavaScript. They were right. So here's the honest deal before you start:

1. Commit to learning Vue or React. This bundler is built on Vue + Vite and supports both patterns. You don't have to master it — but pick one and lean in. (Afraid you can't learn a new architecture? You can. The concepts are one search away — that's what the glossary above is for.)
2. Learn the four basics (your agent can run all of them):
   • bun install — get the dependencies
   • bun run dev — the dev server (live preview)
   • bun run build — the build step (ship it)
   • what node_modules are (the downloaded dependencies)
3. You do not need to write the code. Give your agent access to the example maps in app-profiles/ plus the shared library/, describe your map in plain English, and it builds a new map that reuses the library instead of duplicating spaghetti. The library is for reusable components while the app profiles is for storing custom components that are not reusable, and are specific to that app-profile or map-app. Each map app has custom components that are not reusable and they are not appropriate in the shared library, but if you look at other app-profiles you will see they store their custom components, as well as their main.vue file for the map in the app-profiles folder.

That's the wall. It's small, and everything past it is the maps of your dreams.

---

Quickstart

You need bun installed (bun.lock is committed, so installs are reproducible).

bun install        # download node_modules (one time)

bun run dev        # the playground: http://localhost:5173
                   # every map, clickable, with a copy-paste embed snippet for each

bun run build      # the build step: every app-profiles/<map>/ becomes
                   # public/doxa-maps/<map>/<map>.js  +  a standalone index.html per map

bun run build writes everything into public/doxa-maps/ — that's your output folder. Copy it wherever your site or CDN serves files (for example, a host repo's public/ directory), and your maps are live.

Embed a map

<!-- 1) the map engine (Mapbox shown here) -->
<link  href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>

<!-- 2) your built map + its custom tag -->
<script src="/doxa-maps/my-map/my-map.js"></script>
<doxa-map profile-config='{"profile":"my-map","tk":"pk.eyJ..."}'></doxa-map>

Prefer not to run JavaScript on the host page? iframe the generated page instead: /doxa-maps/<map>/<profile>/index.html. Both snippets are pre‑generated for every map in public/doxa-maps/manifest.json.

---

The data caveat

Read this so nothing surprises you: the maps ship without their data. Because they're JAMstack (pure JavaScript), each map fetches its data — like people‑group information — from an API at runtime. That's what keeps them embeddable everywhere.

Your map data has to come from somewhere. Common sources:

• Joshua Project
• PeopleGroups.org
• A project API. doxa-maps was originally built to serve DX, which runs its own people‑group API (https://pray.doxa.life) covering the unreached people groups these maps were made to pray over. The data source, the map token, and even the map engine (Mapbox ↔ MapLibre) are runtime settings — change them with no rebuild.

---

Docs

Read this	When
docs/why.md	2 min — the problem, the idea, one diagram
docs/tutorial.md	build your first map, step by step (great to hand to your agent)

---

A note from the developer

Bottom line: maps should be open source, they should run everywhere, and no movement of God has ever moved without maps.

You found some really cool maps on the internet, didn't you? On discipleship sites, maybe — maps that inspired you, that made you want to build your own. But the code wasn't available. Or if it was, it wasn't written to run on WordPress, or on your own site, or across your partner churches' websites. It wasn't simple. It wasn't modular. It didn't work the way you needed it to.

That was me too. That's why I built this framework. I love maps — I'm going to build maps until the day I die — because I want to see the Kingdom of God advance to the places it has never been, and I long to see a global movement of map‑makers multiplying maps everywhere.

I want the Great Commission fulfilled in my lifetime, and there is no global movement without map‑making. Look at Scripture: Jerusalem, Judea, Samaria, and the ends of the earth — the book of Acts is a map, all the way to Rome. Where do you find a movement of God without maps at its white‑hot center? Nowhere. So why would we lock our maps away and make them closed source? Why should the power to make a map sit in the hands of a few who never release their code?

It shouldn't. This was built to be open source, to serve movements of God — so the maps can multiply to every device: WordPress, your own site, an embeddable script on Squarespace, mobile, anywhere an embed can run. If we want to put map‑making into the hands of every disciple, we need a framework that lets the maps go, lets them be reusable, and lets a community build them together.

If you have a vision to reach the globe but you've been stuck vibe‑coding an entire platform alone — with no open‑source foundation that runs on your site and your partners' sites — that gap isn't your fault, and you don't have to stay there. You can escape it by adopting a framework that has already been where you are.

Come build the maps of your dreams. Let's reach every people, in every place.

License

Open source. We want this in the hands of every map‑maker on earth — because we want the whole earth to hear the gospel of Jesus. Make all the maps of your dreams. Reach your city. Reach every people, in every place.