carto-develop-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

基于提示生成一个可用的CARTO + deck.gl应用。只需四个决策——应用类型、框架、认证模型、数据形态——即可组装图层、组件、过滤器、输入框、图例，以及（可选）嵌入式地图Agent。

应用遵循CartoDB/deck.gl-examples蓝图。图层来自

@deck.gl/carto

；数据源、组件、过滤器、

fetchMap

、

query()

来自

@carto/api-client

（在v0.4.0版本中，数据源不再从

@deck.gl/carto

导入——请勿从此处导入）。

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
```
.

若需求是“deck.gl应用”、“CARTO应用”、“地图应用”、“空间仪表板”——请使用此技能。
提供Builder地图ID → 参考
```
fetchmap.md
```
。
故事地图/滚动叙事/叙事地图/导览 → 参考
```
storymap.md
```
（基于下方的React脚手架构建）。
地图对话/嵌入式AI Agent → 参考
```
agentic-variant.md
```
。
在Builder中创作地图 → 参考
```
carto-create-builder-maps
```
。跨组织/配置文件迁移Builder地图 → 参考
```
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

bash

carto auth status --json                  # → apiBaseUrl (from tenant.domain region)
carto connections list --json             # → connectionName (default: carto_dw)

通过CARTO CLI生成环境变量。无需询问用户。 使用

--json

参数并解析结果。

运行以下命令，然后写入

.env

文件：

bash

carto auth status --json                  # → apiBaseUrl（来自tenant.domain区域）
carto connections list --json             # → connectionName（默认值：carto_dw）

One token, ONE grant per source — repeat --connection alongside every --source.

一个令牌对应多个授权——为每个数据源重复使用--connection参数。

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. See [`auth-public-token.md`](references/auth-public-token.md).

Private apps swap the token command for `carto credentials create spa --json` (OAuth) or `carto credentials create m2m --json` (M2M).

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`](../carto-basics)).

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


**一个令牌，多授权**——而非一个表对应一个令牌。`--connection`和`--source`按位置配对，因此每个`--source`都要重复`--connection`。使用`--referers`（复数，CSV格式）；若重复使用`--referer`（单数）会覆盖之前的值。详见[`auth-public-token.md`](references/auth-public-token.md)。

私有应用将令牌命令替换为`carto credentials create spa --json`（OAuth）或`carto credentials create m2m --json`（M2M）。

若`carto`不在`PATH`中或`auth status`执行失败：仅提示一次并停止——打印缺失的命令。请勿转而询问用户。假设用户已安装可用的CLI（参考[`carto-basics`](../carto-basics)）。

仅询问CLI无法获取的信息：**表名**（若不明确）以及以下模糊的应用形态选择。

Decision flow — only ask when truly ambiguous

决策流程——仅在真正模糊时询问

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.
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
```
).
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
```
  )
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/

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
```
.

是否提供了Builder地图ID？ 是 → 参考
```
fetchmap.md
```
。流程结束。 1b. 是否为故事地图形态？ 线索：“故事地图”、“滚动叙事”、“导览”、“场景/章节/幻灯片”、“飞行浏览”。→ 参考
```
storymap.md
```
。仍需选择React脚手架 + 下方的数据源/图层；故事地图是叠加在上方的状态模式，而非独立的脚手架。
演示版还是生产版？ 默认选择原生TS + Vite + MapLibre（参考
```
scaffold-vanilla.md
```
），除非提示中提到“生产”、“认证”、“部署”、“团队”、“多屏幕” → 选择React（参考
```
scaffold-react.md
```
）。仅当明确指定时才选择Vue/Angular（参考
```
scaffold-vue-angular.md
```
）。
认证模型？ 根据提示线索选择；仅当线索冲突时才询问。
- “公开”/“分享”/“嵌入”/无需登录 → API访问令牌（参考
```
auth-public-token.md
```
  ）
- “私有”/“用户登录”/“CARTO登录” → OAuth SPA（参考
```
auth-private-oauth.md
```
  ）
- “SSO”/“Okta”/“Azure AD”/“企业身份提供商” → OAuth + SSO（参考
```
auth-private-sso.md
```
  ）
- “后端”/“ETL”/“CI”/“定时任务” → M2M（参考
```
auth-m2m.md
```
  ）
数据形态？ 从
```
data-sources.md
```
+
```
layers.md
```
中选择数据源/图层配对：点/线/面 → 矢量；H3 → H3；quadbin → quadbin；曲面 → 栅格。通过
```
basemap-and-view.md
```
实现底图与视图状态同步。

然后仅添加用户要求的内容：组件、过滤器、输入框、图例、SQL/工作流、智能对话。参考

recipes/

中的示例。

视觉风格？ 若无风格线索 → 使用Meridian风格的默认主题（简洁、专业、CARTO原生）。若有任何风格线索（“未来感”、“企业风”、指定的设计系统） → 匹配用户描述的自定义主题。无论哪种情况，都要遵循UX布局原则。详见
```
design-and-theming.md
```
。

Always-on guidance

通用指南

apiBaseUrl
comes from

carto auth status --json

(

tenant.domain

region). 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.
One
filters
object is shared by source helpers and widget methods. Mutating it triggers re-fetch on both.
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.

apiBaseUrl
来自

carto auth status --json

（

tenant.domain

区域）。切勿硬编码。

connectionName
默认值为

carto_dw

；通过

carto connections list --json

确认。

公钥令牌必须始终传递
```
--source
```
参数，并将
```
--apis
```
限制为
```
sql,maps
```
。在公开包中绝不能使用
```
imports
```
/
```
lds
```
。
一个
filters
对象由数据源助手和组件方法共享。修改它会触发两者重新获取数据。
在
onViewStateChange
事件中，将视口空间过滤器防抖约300毫秒。
设计——除非用户指定其他审美风格，否则应用Meridian风格的默认主题。UX布局原则（地图为核心、面板规整、渐进式展示）始终适用。详见
```
design-and-theming.md
```
。
切勿自创Logo。仅当用户提供经过验证的PNG/JPG/SVG资产或指向官方来源时，才渲染Logo（CARTO、客户、合作伙伴、第三方品牌）。若无验证资产 → 询问用户，或使用文本标识/完全省略Logo。请勿生成SVG标记、从未经验证的URL获取资源，或替换为相似品牌。即使是知名品牌也需遵循此规则。
最后运行应用。执行
```
npm install && npm run dev
```
并报告访问URL。