The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Update the data app setup skill and template manifest (#83997)
Timofey Kachalov219b3cd50e23
diff --git a/skills/metabase-data-app-routing/SKILL.md b/skills/metabase-data-app-routing/SKILL.mdindex b78893dbf91..545aaa35da8 100644--- a/skills/metabase-data-app-routing/SKILL.md+++ b/skills/metabase-data-app-routing/SKILL.md@@ -19,11 +19,11 @@ That's the entire surface. **No `react-router` of any version, no `<BrowserRoute## When to use this skill-- The user has a working data-app project — scaffolded from the `data-app-template` repo, so a one-liner `vite.config.ts` (`dataAppConfig()`) and an `src/index.tsx` that exports a factory already exist. The dev preview has no in-project entry: the SDK's dev preset serves it.+- The user has a working data-app project — scaffolded from the data-app template, so a one-liner `vite.config.ts` (`dataAppConfig()`) and an `src/index.tsx` that exports a factory already exist. The dev preview has no in-project entry: the SDK's dev preset serves it.- The user wants the bundle to render different content at different URLs (`/overview`, `/customers/:id`).- **Do not use this skill** to scaffold a project from scratch — it only patches an existing data-app project. If there is no project yet, stop and tell the user to start with a new data-app scaffold before adding routing.-The template already externalizes `@metabase/embedding-sdk-react/data-app` in `vite.config.ts`. You do NOT need to edit `vite.config.ts` to add routing — just edit `src/App.tsx` (and add more component files as needed) per the step below.+`dataAppConfig()` already externalizes `@metabase/embedding-sdk-react/data-app`. You do NOT need to edit `vite.config.ts` to add routing — just edit `src/App.tsx` (and add more component files as needed) per the step below.## Step 1 — Wrap `App.tsx` with `<DataAppRouter>`@@ -182,7 +182,5 @@ function useCustomerIdFromPath(): number | null {| Symptom | Fix ||---|---|| `<DataAppLink>` renders as plain text (no clickable link) on initial load. | The bundle hasn't finished loading and the fallback path is showing. The provider wrap is supplied automatically (the SDK dev preview's `DataAppDevProvider`, or the host's `DataAppProvider`) — don't add `<MetabaseProvider>` inside the app. The fallback resolves to a real link once the bundle is up. |-| URL changes in dev preview but the production iframe shows the bundle re-render itself on every navigation (or routes don't work in prod at all). | `vite.config.ts` got edited and lost `@metabase/embedding-sdk-react/data-app` from `external` / `output.globals`. Restore from the [template](https://github.com/metabase/data-app-template) — without it, Vite inlines the package's implementation into `dist/index.js`, which runs inside the Near Membrane sandbox and breaks React's state batching. || URL changes but UI doesn't. | A `<BrowserRouter>`/`<HashRouter>` is still in the tree. Strip the router library out and use `<DataAppRouter>` / `<DataAppLink>` instead — the Near Membrane interaction with React-18 batching breaks every router that runs its own `setState` inside the bundle. |-| Reload at a deep URL in dev (`localhost:5174/customers/42`) shows a blank page. | Vite's dev server is serving the route as a 404 instead of falling back to `index.html`. Set `appType: "spa"` in `vite.config.ts` (it's the default — only an issue if someone overrode it). || Middle-click on a `<DataAppLink>` does nothing. | The link uses `event.button !== 0` to skip non-left clicks; check you haven't wrapped it in another component that swallows the event. |diff --git a/skills/metabase-data-app-semantic-layer/SKILL.md b/skills/metabase-data-app-semantic-layer/SKILL.mdindex e4d1d6c4de6..767acbd0357 100644--- a/skills/metabase-data-app-semantic-layer/SKILL.md+++ b/skills/metabase-data-app-semantic-layer/SKILL.md@@ -149,7 +149,7 @@ collections/data_apps/<collection>/<name>.yaml a saved question per query, cWrite the YAML in the Metabase representation format. **Before writing or editing any file under `collections/data_apps/`, load the skill for reading and writing Metabase representation YAML** (use skill discovery), and follow it and its format spec for every file there: the collection, cards, and actions. If no such skill is available, install it with `npx skills add metabase/agent-skills/skills --skill metabase-representation-format`; if it still can't be loaded, stop and tell the user instead of writing the files. None of these replaces it: YAML from an earlier app (including files in git history), a search of the spec for one field, or `npm run check-resources` passing, whose schema validation checks the schema, not the format's conventions. Every card and copy is written from what `npm run print-resources` prints, as below; the format skill is how you write it. Never guess a field's shape. Generate every new entity ID with `npx representations generate-entity-id` (`--count <n>` for several), from the app's own dev dependencies; never invent one, reuse one from another app, or keep a source entity's ID on its copy.-1. **Collection.** Once per app, write `collections/data_apps/<collection>.yaml` as a collection named `Data App: <app name>` with `namespace: data-apps`, and put its entity ID in `data_app.yaml` as `collection: <id>`. It must be a root collection of that namespace: no `parent_id`, `personal_owner_id`, `type`, `authority_level`, or `archive_operation_id`, and not `is_remote_synced`, `is_sample`, or `archived`. The pull refuses a manifest without `collection:`, and one whose collection has no file in the repository.+1. **Collection.** Once per app, and before anything else under `collections/data_apps/`, write `collections/data_apps/<collection>.yaml` as a collection named `Data App: <app name>` with `namespace: data-apps`, and put its entity ID in `data_app.yaml` as `collection: <id>`. Scaffolding normally writes it with the manifest: skip this step when `data_app.yaml` already names a collection whose file exists. `print-resources` refuses to run until the manifest names the collection, since it prints the saved questions into it. It must be a root collection of that namespace: no `parent_id`, `personal_owner_id`, `type`, `authority_level`, or `archive_operation_id`, and not `is_remote_synced`, `is_sample`, or `archived`. The pull refuses a manifest without `collection:`, and one whose collection has no file in the repository.2. **Print what the resources are written from.** Every `defineQuery` carries its `savedQuestionEntityId` and every `defineAction` its `copiedActionEntityId` before you print, generated with `npx representations generate-entity-id`: the saved question is printed with the definition's ID, so `print-resources` refuses a query without one and names it. Then `npm run print-resources` (optionally with one file, `npm run print-resources -- queries/revenue.query.ts`) sends the app's definitions to Metabase, using `DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` from the repo-root `.env.local`, and prints, as JSON, everything as serialization writes it, every reference by name or entity ID rather than numeric ID:- `queries`: each definition's `export`, `file`, and `savedQuestionEntityId`, the saved question Metabase writes for it as `entity` (named after the export, in the app's collection, with that entity ID, holding the query the dev preview runs), and the entity IDs of the `metrics` it aggregates;diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.mdindex 6c48ecacd9c..0b28aa99f12 100644--- a/skills/metabase-data-app-setup/SKILL.md+++ b/skills/metabase-data-app-setup/SKILL.md@@ -134,28 +134,7 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th6. **The lockfile and the built bundle must both be committed.** Metabase serves the file at the `path` declared in `data_app.yaml` (the template builds to `dist/index.js`) straight from the committed Git tree, and the lockfile keeps installs reproducible. **Verify with `git status`** after `npm install` and a build: both must appear as committable files.7. `npm run dev` and confirm the preview at http://localhost:5174 renders the starter "Hello, data app" message.8. If the preview hits CORS, add `http://localhost:5174` under Admin → Embedding → Embedded analytics SDK → CORS.-9. **Edit `data_app.yaml`** (it ships with the template, in the app directory). This is the per-app config Metabase reads on sync — one file per app. Its fields, which of them are required, and their rules are defined in the Data App section of the Metabase representation format spec: load the skill for reading and writing Metabase representation YAML (use skill discovery) and follow its spec. If no such skill is available, install it with `npx skills add metabase/agent-skills/skills --skill metabase-representation-format`; if it still can't be loaded, stop and tell the user. Generate the app's entity ID with `npx representations generate-entity-id` (from the app's own dev dependencies, after `npm install`) and fill in the fields for this app; leave `path` as the template ships it unless you change the build output:-- ```yaml- version: 1 # data app contract version — leave as-is (see below)- name: Sales App # display name shown in the admin UI- slug: sales-app # the /apps/<slug> URL- description: Pipeline health and quota attainment by region # optional — see below- path: ./dist/index.js # bundle path, relative to this app's directory — leave as-is unless you change the build output- # allowed_hosts: # optional — external origins the app may fetch/XHR (see below)- # - https://api.example.com- # - https://*.internal.acme.com- entity_id: Xq2v9LbN0mTz4wRk7YsJd # the generated entity id- serdes/meta:- - model: DataApp- id: Xq2v9LbN0mTz4wRk7YsJd- label: sales-app- ```-- Commit it alongside the built bundle (the file `path` points at). It also- gets a `collection:` line, the entity ID of the app's own collection, whose- file is written under the repo's `collections/data_apps/` in Step 5. Never- copy that line from another app.+9. **Fill in `data_app.yaml`**, the template's manifest, now in the app directory. This is the per-app config Metabase reads on sync, one file per app. Its fields, which of them are required, and their rules are defined in the Data App section of the Metabase representation format spec: load the skill for reading and writing Metabase representation YAML (use skill discovery) and follow its spec. If no such skill is available, install it with `npx skills add metabase/agent-skills/skills --skill metabase-representation-format`; if it still can't be loaded, stop and tell the user. Set `name`, `slug`, and `description` for this app, and `entity_id` to an ID from `npx representations generate-entity-id` (from the app's own dev dependencies, after `npm install`). Leave `version` and `serdes/meta` as the template ships them, and `path` too unless you change the build output. `collection` stays empty until item 10. Never copy a value from another app's manifest.**`description`** — optional: a single short sentence saying what the appdoes, shown under its name in the admin UI so admins can tell apps apart at a@@ -191,18 +170,37 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from thmust also permit framing (`X-Frame-Options`/`frame-ancestors`) — many publicsites don't.+10. **Write the app's collection.** Generate its entity ID with+ `npx representations generate-entity-id`, write the collection's file under+ the repo's `collections/data_apps/` (use skill discovery to find the+ data-app guidance on writing the files of an app's collection), and set that+ ID as `collection` in `data_app.yaml`.++### The order of the app's files++An app's YAML is written in this order, and each step needs the one before it:++1. `data_app.yaml`, copied from the template in Step 3 and filled in at item 9.+2. The collection's file under `collections/data_apps/`, named in+ `data_app.yaml` as `collection` at item 10.+3. `npm run print-resources`, once the app has definitions in `queries/` or+ `actions/`. It prints the saved questions into the collection+ `data_app.yaml` names, so it refuses to run until the manifest names one.+4. The remaining files in the collection's directory: a saved question per+ query and copies of the metrics and actions they use, written from what it+ printed.++Scaffolding ends after the second. The last two are part of building the app's+data layer; use skill discovery for that.+## Step 5 — Verify the starter appAt this point the data app exists. Keep this workflow focused on creating theproject scaffold and proving the starter bundle works.1. Run `npm run typecheck`.-2. Write the app's collection: generate an entity ID with- `npx representations generate-entity-id`, write the collection's file under- the repo's `collections/data_apps/`, and add `collection: <id>` to- `data_app.yaml` (use skill discovery to find the data-app guidance on- writing the files of an app's collection). Then run- `npm run check-resources`, which also validates the repository's YAML+2. Run `npm run check-resources`. It fails when `data_app.yaml` names no+ collection or one without a file, and it validates the repository's YAMLagainst the format. It changes nothing in Metabase.3. Run `npm run build`.4. Confirm `git status` shows the app source, lockfile, `data_app.yaml`, thediff --git a/skills/metabase-data-app-setup/template/README.md b/skills/metabase-data-app-setup/template/README.mdindex 96a1d1f5db1..e2e20cf26bb 100644--- a/skills/metabase-data-app-setup/template/README.md+++ b/skills/metabase-data-app-setup/template/README.md@@ -1,125 +1,20 @@# data-app-template-A Metabase **data app** — a single-bundle React app (built with the Embedding-SDK) that Metabase renders inside an isolated, sandboxed iframe at-`/apps/<slug>`.+A Metabase data app: a single-bundle React app, built with the Embedding SDK,+that Metabase serves at `/apps/<slug>` from the Git repository it syncs. This+directory is `data_apps/<slug>/` in that repository. Build and change it with a+coding agent and the Metabase data-app skills.-Data apps are delivered through **Git**: this directory lives at-`data_apps/<slug>/` inside a repository connected to Metabase via remote sync.-You commit the built bundle (`dist/index.js`) and the files of the app's-collection under the repo's `collections/data_apps/`, and on the next-remote-sync import Metabase materializes the app and serves it.--## Develop--```bash-npm install # or yarn / pnpm / bun — no lockfile shipped-cp .env.local.example ../../.env.local # repo root: set DATA_APP_MB_URL + DATA_APP_MB_API_KEY-npm run dev # preview at http://localhost:5174-```--`npm run dev` previews the app against a real Metabase **through the same-Near-Membrane sandbox + CSP rules production uses**, so dev behaves like prod.-Edit anything under `src/` — the preview soft-reloads.--If the dev preview hits CORS, add `http://localhost:5174` under-Admin → Embedding → Embedded analytics SDK → CORS.--## Ship+## Commands```bash-npm run print-resources # prints what the app's collection files are written from, as JSON-npm run check-resources # checks the app's collection files back every definition, then validates the repository's Metabase YAML-npm run build # produces a single dist/index.js-```--The repo's `collections/data_apps/` holds the app's collection, a saved question-per query, and copies of the metrics and actions the app uses, as Metabase YAML:-`<collection>.yaml` beside a `<collection>/` directory of its contents. They are-written from what `npm run print-resources` prints, which Metabase exports for-the app's definitions; `data_app.yaml`'s `collection:` names the collection, and-each definition names its file by entity ID. Only `print-resources` calls-Metabase, with the URL and API key in the repo-root `.env.local`.-Update those files after any change to `queries/` or `actions/`; the check and-the build fail until they match.--Commit `dist/index.js` (the `path` declared in `data_app.yaml`), the app's-collection files, and your source. The app appears at `/apps/<slug>` after-Metabase's next remote-sync import (manual "Pull changes", auto-import, or-startup), which also loads the collection files.--## Upgrading--`data_app.yaml` declares the data-app contract version this app targets. When a-Metabase release bumps that version, the app shows as _Outdated_ in the admin UI-until it is migrated. Migration is its own instructed procedure, installed for-your coding agent by the same command as the other data-app skills; do not edit-`version` by hand.--## What's in the box--```-.-├── data_app.yaml - manifest: version, name, bundle path, allowed_hosts, collection-├── package.json - @metabase/embedding-sdk-react + react/react-dom + Vite toolchain-├── vite.config.ts - one-liner: `export default dataAppConfig()`-├── tsconfig.json-├── queries/ ← every query, as `defineQuery(...)` exports (see its README)-│ └── README.md-├── actions/ ← every action, as `defineAction(...)` exports (see its README)-│ └── README.md-├── src/-│ ├── index.tsx - entry — default-exports a factory returning { component, providerProps }-│ ├── App.tsx - edit this; pure content, no <MetabaseProvider> wrap-│ └── theme.ts - the SDK theme, passed via providerProps-├── .env.local.example-└── .gitignore+npm run dev # preview at http://localhost:5174, in the sandbox Metabase runs apps in+npm run typecheck # type-checks src/ and vite.config.ts+npm run print-resources # prints what the app's collection files are written from, as JSON+npm run check-resources # checks the app's collection files against its definitions, then validates the repository's Metabase YAML+npm run build # builds dist/index.js, the bundle data_app.yaml's path names```-`queries/` and `actions/` are not optional: the query hooks accept only a-`defineQuery(...)` export and `useAction` only a `defineAction(...)` export, and-each definition in those two directories is backed by a file in the app's collection under the repo's `collections/data_apps/`.-Read their READMEs before the first hook call.--The build, dev server, Near-Membrane sandbox, and bundle contract all live in-the SDK behind `dataAppConfig()` — there's no `index.html` or separate dev entry-to edit. Keep `<MetabaseProvider>` out of `App.tsx`: the production host and the-dev preview each provide it in their own realm.--The build output is a single self-contained `dist/index.js` — CSS and assets are-inlined, and React + the SDK are externalized to the host's instances, so the-bundle stays small.--## Calling external APIs (`allowed_hosts`)--A data app runs sandboxed: by default it **can't** `fetch`/XHR anything. To let-it reach an external API, list the origins in `data_app.yaml` under-`allowed_hosts` (supports a `*.` subdomain wildcard):--```yaml-allowed_hosts:- - https://api.example.com- - https://*.internal.acme.com-```--The same allowlist is enforced in both places: `npm run dev` applies it via the-dev server's CSP, and Metabase applies it via the iframe CSP + the membrane-sandbox. The Metabase instance itself is reached through the SDK (not listed-here). A call to any other host fails in dev exactly as it will in production.--### Forms and embeds--`allowed_hosts` also governs native `<form action="…">` submissions and-`<iframe src="…">` / navigations, not just `fetch`.--Prefer a **client-side** form — `<form onSubmit={(e) => { e.preventDefault(); … }}>`-that writes via the SDK (`useAction`) or `fetch` — over a native-`<form action="…">`. A native submit **navigates the sandboxed iframe away** from-your app.--If you do use `<form action="https://…">` (or embed/navigate to a host via an-`<iframe>`), the target host must be in `allowed_hosts`, or the browser blocks it-(`form-action` for submits, `frame-src` for embeds). Note a host you embed or-navigate to must also **allow being framed** (`X-Frame-Options` /-`frame-ancestors`) — many public sites (e.g. `example.com`) don't, so they can't-be shown in-frame regardless of `allowed_hosts`.+`npm run dev` and `npm run print-resources` read `DATA_APP_MB_URL` and+`DATA_APP_MB_API_KEY` from the `.env.local` at the repository root;+`.env.local.example` lists them.diff --git a/skills/metabase-data-app-setup/template/data_app.yaml b/skills/metabase-data-app-setup/template/data_app.yamlindex 9fae16f682d..fed07487e26 100644--- a/skills/metabase-data-app-setup/template/data_app.yaml+++ b/skills/metabase-data-app-setup/template/data_app.yaml@@ -15,9 +15,12 @@ path: ./dist/index.js# - https://api.example.com# - https://*.internal.acme.com-entity_id: replace-entity-id-xxx+# The entity ID of the app's collection. Write the collection's file under the+# repo's `collections/data_apps/` first, then set its ID here.+collection:++# Generate with `npx representations generate-entity-id`.+entity_id:serdes/meta:- model: DataApp- id: replace-entity-id-xxx- label: data-app-template