carto-develop-app

carto-develop-app

Generate a working CARTO + deck.gl app from a prompt. Four decisions — app type, framework, auth model, data shape — then assemble layers, widgets, filters, inputs, a legend, and (optionally) an embedded map agent.

Apps follow the CartoDB/deck.gl-examples blueprint. Layers from @deck.gl/carto; data sources, widgets, filters, fetchMap, query() from @carto/api-client (sources left @deck.gl/carto in v0.4.0 — don't import them from there).

Access path. This is a CLI-path skill: scaffolding and running an app needs a real shell and dev environment (npm, Vite), and no MCP tool generates an app — so this can't run on sandboxed chat hosts (Claude.ai, ChatGPT). Only the credential/discovery steps have MCP equivalents: over an OAuth MCP session, mint tokens with manage_api_access_tokens, OAuth/M2M clients with manage_oauth_clients, and discover map/workflow IDs with read_maps / read_workflows. Everything else needs the shell. Path detection: `carto-basics/references/access-paths.md`.

When to use

• "deck.gl app", "CARTO app", "map app", "spatial dashboard" — use this skill.
• Builder map ID supplied → `fetchmap.md`.
• Storymap / scrollytelling / narrative map / guided tour → `storymap.md` (composes on top of the React scaffold below).
• Chat-with-map / embedded AI agent → `agentic-variant.md`.
• Authoring maps in Builder → `carto-create-builder-maps`. Migrating a Builder map across orgs / profiles → `cross-profile-copy.md`.

Operating mode — autonomous by default

Generate the env via the CARTO CLI. Don't interview the user. Pass --json and parse.

Run, then write .env:

carto auth status --json                  # → tenant_id (region) → apiBaseUrl
carto connections list --json             # → connectionName (default: carto_dw)

# One token, ONE grant per source — repeat --connection alongside every --source.
carto credentials create token --json \
  --connection <connectionName> --source <fully.qualified.table.A> \
  --connection <connectionName> --source <fully.qualified.table.B> \
  --apis sql,maps \
  --referers 'http://localhost:5173*,<production-origin>*'

One token, many grants — not one token per table. --connection and --source pair positionally, so repeat --connection for every --source. Use --referers (plural CSV); --referer (singular) overwrites if repeated. Referers are wildcard-matched against the browser's full page URL, so end each pattern with * (a bare http://localhost:5173 won't match the http://localhost:5173/ browsers actually send). --apis and grants are independent: maps covers sources/layers, sql covers query(), and a *QuerySource needs its query in the grant — see `auth-public-token.md`.

Private apps swap the token command for carto credentials create spa --json (OAuth) or carto credentials create m2m --json (M2M). Hosted apps need no credential at all: skip the token step and follow `auth-hosted.md`.

If carto isn't on PATH or auth status fails: say so once and stop — print the missing command. Don't fall back to interviewing. Assumes a working CLI (`carto-basics`).

Only ask what the CLI can't answer: table name (if not obvious) and ambiguous app-shape choices below.

Decision flow — only ask when truly ambiguous

1. Builder map ID supplied? Yes → `fetchmap.md`. Done.

1b. Storymap shape? Cues: "story map", "scrollytelling", "guided tour", "scenes/chapters/slides", "fly through". → `storymap.md`. Still pick the React scaffold + sources/layers below; storymap is a state pattern layered on top, not a separate scaffold.

1. Demo or production? Default to vanilla TS + Vite + MapLibre (`scaffold-vanilla.md`) unless the prompt says "production", "auth", "deploy", "team", "multi-screen" → React (`scaffold-react.md`). Vue / Angular only if explicitly named (`scaffold-vue-angular.md`).
2. Auth model? Pick from prompt cues; ask only if cues conflict.

• "public" / "share" / "embed" / no login → API access token (`auth-public-token.md`)
• "private" / "users log in" / "CARTO login" → OAuth SPA (`auth-private-oauth.md`)
• "SSO" / "Okta" / "Azure AD" / "corporate IdP" → OAuth + SSO (`auth-private-sso.md`)
• "backend" / "ETL" / "CI" / "scheduled" → M2M (`auth-m2m.md`)
• "hosted on CARTO" / "internal tool" / "for my team" / "no infrastructure" / carto app deploy → CARTO-hosted, viewer token at runtime (`auth-hosted.md`). Needs the Hosted Apps flag; not for anonymous access.

1. Data shape? Source/layer pair from `data-sources.md` + `layers.md`: points/lines/polygons → vector; H3 → H3; quadbin → quadbin; surfaces → raster. Wire the basemap and view-state sync via `basemap-and-view.md`.

Then layer in only what was asked for: widgets, filters, inputs, legend, SQL/workflows, agentic chat. Recipes in `recipes/`.

1. Visual style? No style cues → Meridian-inspired default (clean, professional, CARTO-native). Any style cue ("futuristic", "corporate", a named design system) → custom theme matching the user's description. Either way, apply the UX layout principles. See `design-and-theming.md`.

Always-on guidance

• `apiBaseUrl` is https://<tenant_id>.api.carto.com, with tenant_id (the region, e.g. gcp-us-east1) from carto auth status --json. tenant_domain is the organization's own domain (e.g. clausa.app.carto.com) and carries no region. apis.baseUrl in https://<tenant_domain>/config.yaml is authoritative (self-hosted included). Never hard-code.
• `connectionName` defaults to carto_dw; confirm via carto connections list --json.
• Public tokens must always pass --source and limit --apis to sql,maps. Never imports / lds in a public bundle.
• Complex analysis is a workflow, not app SQL. Predicting revenue, composite/suitability scores, segmentation, multi-step joins — build it with `carto-create-workflow`; the app then reads its output table or CALLs its procedure via the Workflows API (or, if an embedded agent drives it, invokes it as a published MCP tool). Heavy logic stays server-side; the app passes parameters. See `workflows-and-sql.md`.
• One `filters` object is shared by source helpers and widget methods. Mutating it triggers re-fetch on both.
• Layer z-order is the `layers` array, last = on top — not CSS `z-index`. Restack by changing array position and passing a fresh array (never mutate in place); z-index orders DOM panels, never layers on the shared canvas. See `layers.md`. (Opaque fills hiding basemap labels is a separate, basemap-side question — `basemap-and-view.md`.)
• Debounce viewport spatial filters ~300 ms on onViewStateChange.
• Design — apply the Meridian-inspired default theme unless the user specifies a different aesthetic. UX layout principles (map as hero, panel discipline, progressive disclosure) always apply. See `design-and-theming.md`.
• Never invent logos. Only render a logo (CARTO, customer, partner, third-party brand) when the user supplied a verified PNG / JPG / SVG asset or pointed to an official source. No verified asset → ask the user, or use a text wordmark / omit the logo entirely. Do not generate SVG marks, fetch from unverified URLs, or substitute a similar-looking brand. Applies even to well-known brands.
• End by running the app. Run npm install && npm run dev and report the URL.