ClaudeCodeExperienceBuilder

Build custom ArcGIS Experience Builder widgets using Claude Code (This doc was mostly written by Claude too).

This repo contains the documentation, prompts, and reference materials that help Claude Code understand Experience Builder's conventions, APIs, and gotchas — so it can build working custom widgets instead of guessing.

Written about in Episode 53 of Almost Entirely Human. Although this was built for Experience Builder, the techniques (preparing documentation, writing a CLAUDE.md, using Think → Engage → Test) apply to any complex system.

What's in this repo

• CLAUDE.md — Instructions for Claude Code: Experience Builder conventions, import rules, manifest patterns, common errors, and the development workflow
• docs/CustomWidgetDeveloperGuide.md — Deep-dive reference on custom widget development patterns with full code examples
• ExperienceBuilderSetupGuide.md — Step-by-step walkthrough from installing Experience Builder to deploying a finished widget (written by claude code)
• starter-prompt-for-claude-app.md — A prompt template for designing your widget in Claude.ai before handing off to Claude Code

How to set this up

Prerequisites

• Node.js 22 LTS
• ArcGIS Experience Builder Developer Edition 1.19 (download here)
• Claude Code (install here)
• An ArcGIS organizational account (Creator or Professional user type)

Step 1: Clone this repo into your Experience Builder directory

After you've extracted Experience Builder, clone this repo right next to client/ and server/:

cd ArcGISExperienceBuilder
git clone https://github.com/user/ClaudeCodeExperienceBuilder.git

Step 2: Copy files into place

The CLAUDE.md file needs to be in the ExB project root so Claude Code reads it automatically. The docs folder can stay in the cloned repo — CLAUDE.md references it by relative path.

cp ClaudeCodeExperienceBuilder/CLAUDE.md .

Step 3 (Optional): Clone the Esri sample widgets

git clone https://github.com/Esri/arcgis-experience-builder-sdk-resources.git samples

This gives Claude Code ~40 working widget examples to reference.

Final directory structure

ArcGISExperienceBuilder/
├── CLAUDE.md                                  ← Copied to root (Claude Code reads this automatically)
├── ClaudeCodeExperienceBuilder/               ← This repo
│   ├── README.md
│   ├── docs/
│   │   ├── CustomWidgetDeveloperGuide.md      ← Comprehensive patterns & examples
│   │   └── setup-guide.md                     ← Full setup walkthrough
│   └── starter-prompt-for-claude-app.md       ← Prompt template for the design phase
├── samples/                                   ← (Optional) Esri sample widgets
│   └── widgets/
│       ├── starter-widget/
│       └── ...40+ more samples
├── client/
│   ├── your-extensions/
│   │   ├── manifest.json
│   │   └── widgets/                           ← Your custom widgets end up here
│   └── ...
├── server/
│   └── ...
└── ...

The process: Think → Engage → Test

Think (Claude.ai or Desktop)

Open a new conversation in Claude and paste the contents of starter-prompt-for-claude-app.md. Then describe the widget you want to build — what it does, what data it uses, what the settings panel should look like. Claude will ask questions and produce a design document.

Read the design document. Edit it, push back, ask for changes. This is the most important step. Save the final version as PLAN.md in your ExB project root.

Engage (Claude Code)

cd ArcGISExperienceBuilder
claude

Tell Claude Code to read the CLAUDE.md, the docs, and your plan, then build progressively — minimal widget first, verify it loads, then layer on features. See the setup guide for the full development loop.

I use a prompt like this:

I want to build a custom Experience Builder widget. Here's my reviewed design plan.

Before starting:
1. Read CLAUDE.md (you should have already)
2. Read docs/CustomWidgetDeveloperGuide.md for detailed patterns
3. Check the compatibility matrix — we're on ExB 1.19, JSAPI 4.34, React 19
4. Watch for JSAPI deprecations in 4.34

Build this progressively:
- Start with a minimal widget that just renders a text input (verify it loads)
- Then add the core filtering logic
- Then add the settings panel
- Then add polish (error handling, loading states, etc.)

The plan is in PLAN.MD

Review the plan, ask questions and then build your plan.

Test (You)

This is where your experience matters. Claude doesn't know what it doesn't know. Test in the browser, check the console, take screenshots of issues, and iterate with Claude Code. The setup guide has a troubleshooting table for common problems.

Contributing

The prompts and documentation are the highest-leverage things to improve. If you find better patterns, fixes for common Claude mistakes, or ways to improve the CLAUDE.md — please open a PR. The more people refine these, the better the results for everyone.

About

Built by Christopher Moravec, CTO at dymaptic. Part of a monthly livestream series where I build AI + GIS projects live. Subscribe to Almost Entirely Human for the weekly newsletter.