The first time I deployed a working ArcGIS SDK app in under 10 minutes, I assumed I'd gotten lucky. By the fifteenth time, I accepted it was a repeatable pattern.
This is that pattern.
What "thin HTML" means
A single index.html file that:
- Imports libraries via CDN (no npm, no build step)
- Contains all CSS and JavaScript inline
- Authenticates via AGOL OAuth, reads AGOL data, renders the result
- Has no backend, no server, no database
Usually 150–400 lines. Opens in any browser. Runs. The security model is entirely OAuth and AGOL layer permissions — there is nothing else to secure.
The 8-minute sequence
Minutes 0–3: Describe and generate
Describe the tool you need in Claude:
"ArcGIS JS SDK 4.29, single HTML file, no npm. Show a choropleth of disaster chapter boundaries colored by volunteer count from Feature Layer [ITEM_ID]. Dark basemap, click popup with chapter name and count, legend bottom-left, AGOL OAuth login with client ID [CLIENT_ID]."
What comes back is a complete HTML file. Not a snippet. A file that opens in a browser.
Minutes 3–4: Test and adjust
Open the file in Chrome. The OAuth flow runs. The map loads. If anything needs adjusting:
"The popup is showing the raw field name VOLUNTEER_COUNT — change the label to 'Active Volunteers' and format the number with commas."
One more response. Updated file.
Minutes 4–6: Push to GitHub
mkdir my-tool && cd my-tool
cp ~/Downloads/index.html .
git init && echo ".env" >> .gitignore
git add . && git commit -m "init"
gh repo create my-tool --public --source=. --push
Minutes 6–8: Connect to Vercel
vercel --prod
Vercel detects the static file, deploys, returns a URL. That URL is live. HTTPS. Global CDN. No server to maintain.
Why Vercel over GitHub Pages
Both are free. Both serve static files. The difference is the URL.
franzenjb.github.io/my-tool reads as a personal project.
my-tool.vercel.app reads as a product.
Same code. Different perception. In organizations that evaluate tools by how they look before they look at what they do — which is most organizations — this matters more than it should.
Vercel also gives you preview deployments. Every push to a branch gets its own URL. Share my-tool-fix-popup.vercel.app with a stakeholder for review before merging. GitHub Pages doesn't do this.
The CLI setup
I run everything through Ghostty terminal with cmux for window organization. Named panes per active project, persistent across sessions. The mental overhead of context-switching between projects drops to near zero when each has its own terminal pane I can return to without re-orienting.
The three CLIs I use on every project:
gh repo create project-name --public --source=. --push
vercel --prod
vercel env add VARIABLE_NAME
I use Claude almost exclusively as the knowledge layer on top of the CLI. The exact flag for a Vercel command, the ArcGIS Python API syntax, the OAuth URL construction — I stopped looking these up months ago. I describe what I need, get the command, run it. The terminal is no longer a place I go to search. It's a place I go to execute.
Updating a deployed app
After the initial deploy, updates are one command:
# Edit index.html via Claude — describe the change, get the updated file
git add index.html
git commit -m "fix: popup label formatting"
git push
Vercel auto-deploys on every push. The production URL reflects the change within 30 seconds. No pipeline. No build step. Push and it's live.
Embedding anywhere
Once a tool has a Vercel URL, it embeds in everything:
Experience Builder: Embed widget, URL with ?arcgis-auth-origin=https://experience.arcgis.com. The EB session credential passes into the iframe — no second login.
SharePoint: iframe web part. Same URL.
Teams: Tab app. Add the URL as a tab in a relevant channel.
Confluence: HTML macro. Same URL.
One tool. One URL. Embeds everywhere. Zero redeployment per new embed location.
What this costs
Infrastructure: $0 for public repos on Vercel Free. $20/month for Vercel Pro (private repos, team features).
Time: 8 minutes for first deploy. 30 seconds for updates. Zero time for server maintenance, because there is no server.
These numbers aren't theoretical. They come from actual tools built for Red Cross disaster operations, donor analytics, and field team support — tools that would have taken days through the normal process.
The pattern is stable. Every project runs the same sequence. Every project benefits from every previous project's refinements. That compounding is real.
Related: OAuth Without the Pain — Security First — Building Tools That Assume Breach