• "scaffold a new data app" / "create a Metabase data app" / "set up a data-app project"
• "I want to build a data app" / any vague intent to author a data app
• Starting a fresh agent task that will produce a data-app bundle.
• Do not use this skill for an existing data-app project when the task is to build screens, use Metabase data, generate or refresh schema files, wire saved questions / tables / metrics / actions, add filters, or author data hooks. Treat those as existing-data-app editing tasks and use the agent's normal skill-discovery flow from the user's wording.

• Ask: "Do you already have a Git repository connected to this Metabase via remote-sync?"
  • Yes → ask for its local path.
  • No → ask the user to create one (a plain Git repo they will connect under Admin → Settings → Remote sync) and share its path. The skill does not create or connect the repo — the user owns that.
• Verify the path exists and is a Git working tree (it has a

  .git

  ). This repo is the working directory for every step below.

1. Settle on the app's directory name before scaffolding — it is used verbatim as the slug (the

   /apps/<slug>

   URL), so it must be dash-cased: lowercase letters, numbers, and single dashes (

   [a-z0-9]+(?:-[a-z0-9]+)*

   ), e.g.

   sales-overview

   . Anything else (uppercase, spaces, underscores) is rejected on sync. If the purpose isn't clear yet, ask a one-line "what's this app for?" and propose a name; confirm it.
2. Ensure

   <repo>/data_apps/

   exists; create it if missing.
3. Create

   <repo>/data_apps/<slug>/

   . If it already exists, treat it as an existing project (see below) — never overwrite without confirmation.

<repo>/data_apps/<slug>/

data-app-template

1. vite.config.ts

   is a one-liner:

   export default dataAppConfig()

   (from

   @metabase/embedding-sdk-react/data-app-dev/config

   ). There is no local

   config/

   directory: the whole bundle contract (externals/globals, the dev sandbox entry, CSS/SVG handling) lives inside that SDK config, not the scaffold.

   dataAppConfig

   takes only a curated set of overrides (currently just

   port

   ); the contract plugin is always applied and can't be overridden.

2. src/index.tsx

   default-exports a

   DataAppFactory

   (type from

   @metabase/embedding-sdk-react/data-app

   ) returning

   { component, providerProps? }

   (no args).

src/

<repo>/data_apps/<slug>/

1. Edit

   package.json

   name

   to match the slug.
2. Pin

   @metabase/embedding-sdk-react

   to the published data-apps tag (the template ships with

   *

   ):
   bash

   npm install @metabase/embedding-sdk-react@64-alpha

   This resolves to the current internal-testing SDK build with the

   @metabase/embedding-sdk-react/data-app

   entrypoint (the app's APIs) and the

   @metabase/embedding-sdk-react/data-app-dev/config

   entrypoint

   vite.config.ts

   uses (the dev/build preset, which serves the sandbox entry). Do not use

   latest

   or

   64-stable

   as data apps are not yet released.
3. Ensure the repo-root

   .gitignore

   ignores

   .env.local

   — do this before creating any credentials file so the secret can never be committed. Create the

   .gitignore

   if the repo doesn't have one, then add the entry if it's missing:
   bash

   ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
   if [ -z "$ROOT" ]; then
     echo "MISSING (run this from inside the connected git repo)"
   else
     GITIGNORE="$ROOT/.gitignore"
     # Create the repo-root .gitignore if absent, then ensure `.env.local` is
     # ignored so the credentials file (next step) can never be committed.
     [ -f "$GITIGNORE" ] || : > "$GITIGNORE"
     grep -qxF ".env.local" "$GITIGNORE" || echo ".env.local" >> "$GITIGNORE"
   fi

4. Set up the Metabase credentials at the repository root —

   <repo>/.env.local

   (usually two levels up from the app dir), not the app dir. One

   .env.local

   there serves every data app in the repo.
   Create it from the example if absent, then verify the two vars are set without printing the file (it may hold other secrets) —

   source

   it and echo only a pass/fail signal, never the values:
   bash

   # Resolve the repo root first; an unguarded $(git ...) would expand to
   # "/.env.local" outside a repo and touch a system-level file.
   ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
   if [ -z "$ROOT" ]; then
     echo "MISSING (run this from inside the connected git repo)"
   else
     ENV_FILE="$ROOT/.env.local"
     [ -f "$ENV_FILE" ] || cp .env.local.example "$ENV_FILE"
     # Source inside a subshell so the vars never leak into your environment.
     ( source "$ENV_FILE" 2>/dev/null
       [ -n "$DATA_APP_MB_URL" ] && [ "$DATA_APP_MB_URL" != "mb_replace_me" ] &&
       [ -n "$DATA_APP_MB_API_KEY" ] && [ "$DATA_APP_MB_API_KEY" != "mb_replace_me" ]
     ) && echo "creds present" || echo "MISSING"
   fi

   If it prints

   MISSING

   , ask the user to fill

   DATA_APP_MB_URL

   (the running Metabase instance) and

   DATA_APP_MB_API_KEY

   (Admin → Authentication → API keys) in

   <repo>/.env.local

   themselves — up front, before anything needs the key.

   Never ask the user to paste the API key into the chat, and never

   cat

   /

   echo

   / print

   .env.local

   or its variables. It's git-ignored and may hold other secrets — the file's contents and the key must never enter the conversation or your context. Every command that needs the key

   source

   s the file (as above) so the shell uses the value directly; you only ever see the

   creds present

   /

   MISSING

   signal, never the secret itself. (

   creds present

   only means both vars are filled and not the default

   mb_replace_me

   placeholder — not that the URL or key are valid; a bad key surfaces later when a request fails.)

5. npm install

   (or whichever package manager the user prefers — the template ships with no lockfile, so

   npm

   /

   yarn

   /

   pnpm

   /

   bun

   all work; use the project's existing lockfile if one appears post-clone).
6. Fix the app's

   .gitignore

   so the lockfile and the built bundle get committed. Two things must end up tracked in the remote-sync repo:
   • Lockfile — strip the lockfile-ignoring block (the chunk between

     # Lockfiles —

     and

     bun.lockb

     , covering

     package-lock.json

     /

     yarn.lock

     /

     pnpm-lock.yaml

     /

     bun.lock

     /

     bun.lockb

     ) so the project commits its lockfile for reproducible installs.
   • The built bundle — Metabase serves the file at the

     path

     declared in

     data_app.yaml

     (the template builds to

     dist/index.js

     , the default

     path

     ) straight from the committed Git tree, so that file must be committed. If the template's

     .gitignore

     ignores

     dist/

     (or wherever your build outputs), remove that line. Verify with

     git status

     — after

     npm install

     + a build, both the generated lockfile and the built bundle (the file

     path

     points at) must appear as untracked/committable files. If either doesn't, the relevant

     .gitignore

     line is still there; remove it and re-check. Do not skip this — agents have repeatedly shipped projects with no committed lockfile or an un-synced bundle.

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. Fill in its fields for this app:
   yaml

   name: Sales App        # display name shown in the admin UI
   description: Pipeline health and quota attainment by region  # optional — see below
   version: 1             # data app contract version — leave as-is (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

   Commit it alongside the built bundle (the file

   path

   points at).

   description

   — optional: a single short sentence saying what the app does, shown under its name in the admin UI so admins can tell apps apart at a glance. Sync folds any whitespace into single spaces and rejects anything over 255 characters; the admin list wraps what is left rather than cutting it off, so a sentence reads well there and a paragraph crowds out the rows around it. Replace the template's placeholder with a real sentence about this app, or delete the line entirely if it adds nothing beyond the name.

   version

   — the data app contract version this app's code targets, a whole number. The template ships the version this skill targets; do not change it by hand. Metabase bumps the version it serves only on a breaking change to the contract. An app on an older version is marked Outdated in the admin list, hidden from every other user, and refuses to open until it is migrated to the current contract, its

   version

   raised to match, rebuilt, and synced. Migrating an app from one version to the next is a separate, instructed procedure; never do it ad hoc.

   allowed_hosts

   — only needed if the app calls an external API directly with

   fetch

   /

   XHR

   . The sandbox blocks all network egress by default; listing an origin here (exact or a

   *.

   subdomain wildcard) opens it in both

   npm run dev

   (dev-server CSP) and Metabase (iframe CSP + sandbox). Do not list the Metabase instance — Metabase data is read via the

   useMetabaseQuery

   data hooks and written via

   useAction

   (the SDK handles auth), never raw

   fetch

   . Leave

   allowed_hosts

   out entirely when the app only talks to Metabase.
   Native

   <form action="…">

   submissions and

   <iframe src="…">

   /navigations obey the same allowlist. Prefer a client-side

   <form onSubmit>

   that

   preventDefault

   s and writes via

   useAction

   /

   fetch

   : a native submit navigates the sandboxed iframe away from the app. If you do use one, the target host must be in

   allowed_hosts

   or it's blocked (

   form-action

   for submits,

   frame-src

   for embeds/navigations). A host you navigate to or embed must also permit framing (

   X-Frame-Options

   /

   frame-ancestors

   ) — many public sites don't.

1. Run

   npm run typecheck

   .
2. Run

   npm run build

   .
3. Confirm

   git status

   shows the app source, lockfile,

   data_app.yaml

   , and the built bundle (

   dist/index.js

   by default) as committable files.
4. If the user asked for a live preview, run

   npm run dev

   and confirm the starter "Hello, data app" screen renders through the sandbox preview.
5. With the preview open, check the diagnostics feed once — it is the only place runtime failures appear to you (see Reading the diagnostics feed):
   bash

   curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"

   Expect

   clients: 1

   and no entries with

   "alert": true

   .

   clients: 0

   means no preview tab is open, so an empty feed proves nothing.

src/index.tsx

tsconfig.json

dataAppConfig()

index.html

vite.config.ts

import { dataAppConfig } from "@metabase/embedding-sdk-react/data-app-dev/config";

export default dataAppConfig();

dataAppConfig

port

index.html

src/index.tsx

define

port

src/

npm run typecheck

tsc --noEmit

src/

vite.config.ts

npm run dev

@metabase/embedding-sdk-react

react-datepicker

react-day-picker

flatpickr

@mui/x-date-pickers

antd

rsuite

DateRangePopover

@metabase/embedding-sdk-react/data-app

@types/react-datepicker

react-datepicker

questionId

errorComponent

providerProps

theme

providerProps

// src/components/AppError.tsx
import type { SdkErrorComponentProps } from "@metabase/embedding-sdk-react";

export default function AppError({ message }: SdkErrorComponentProps) {
  return (
    <div style={{ padding: 16, textAlign: "center", color: "#6b7280" }}>
      {message}
    </div>
  );
}

// src/index.tsx — add the key alongside `theme`
import AppError from "./components/AppError";

const factory: DataAppFactory = () => ({
  component: App,
  providerProps: { theme: sdkTheme, errorComponent: AppError },
});

• It replaces the error UI for every SDK component in the app, not just not-found — so keep the copy generic. Render

  message

  (or your own wording), not an assumption about which error occurred.

• message

  is a

  ReactNode

  — render it as-is; don't call

  .toString()

  or index into it.
• Keep it a small presentational component. It renders inside the host's provider, but treat it as leaf UI — no data hooks, no

  useMetabaseQuery

  .
• Omit

  errorComponent

  entirely to keep the neutral default. There's no need to re-implement it.

• Yes →

  useMetabaseQueryObject

  +

  StaticQuestion

  /

  InteractiveQuestion

  . Bar, line, area, combo, row, trend, pie/donut, scalar/smartscalar, gauge, progress, funnel, scatter, waterfall, boxplot, sankey, pivot, map, object/list views, sortable table, and anything else in the chart-type list. Also whenever visualization settings can carry the presentation — axes, labels, stacking, goals, trendlines, split panels, series, formatting, table/pie/pivot/list settings — or the user benefits from sorting, column inspection, drill-through, or downloading. Build the semantic query from generated schema objects, destructure the returned

  query

  , and pass only that value in a card object —

  <StaticQuestion card={{ query }} visualization="pie" ... />

  . Never pass the whole

  { query, error, isLoading }

  hook result as

  card.query

  .
• No →

  useMetabaseQuery

  and your own component. Only when the user asked for a custom visualization, or nothing Metabase renders can express the request: bespoke scorecards, alert panels, narrative layouts or mixed-content cards, custom interactions its chart/table chrome cannot express, unusual forms such as calendar grids, timelines, heat strips, radial views, custom maps or domain-specific diagrams, and elements combining several queries into one visual unit. Keep the row handling typed. Use a charting dependency the app already has; otherwise SVG is fine.

StaticQuestion

withChartTypeSelector

withDownloads

title

InteractiveQuestion

isSaveEnabled

true

isSaveEnabled={false}

InteractiveQuestion

<InteractiveQuestion.QuestionVisualization />

title={false}

InteractiveQuestion

StaticQuestion

visualization

visualizationSettings

isLoading

true

isLoading

useAction

isExecuting

disabled={isExecuting}

height

width

• Chart only: pass

  height

  to

  InteractiveQuestion.QuestionVisualization

  .
• Default question layout with query bar: pass

  height

  to

  InteractiveQuestion

  .
• Static question: pass

  height

  to

  StaticQuestion

  .

height="500px"

<div style={{ height: 360 }}>
  <StaticQuestion
    questionId={1}
    height="100%"
    width="100%"
    withChartTypeSelector={false}
  />
</div>

InteractiveQuestion

StaticQuestion

overflow: hidden

1. npm run build

   → produces the bundle at your

   data_app.yaml

   path

   (the template builds to

   dist/index.js

   ).
2. From the repo root, commit the app directory — its

   data_app.yaml

   , the built bundle (the file

   path

   points at), the source, and the lockfile — and push:
   bash

   git add data_apps/<slug>
   git commit -m "Add <slug> data app"
   git push

3. The app appears in Metabase on the next remote-sync import — a manual Pull changes (Admin → Data apps / Remote sync), the auto-import poll, or a restart — reachable at

   /apps/<slug>

   .

Don't offer to "deploy" the app or ask how the bundle reaches a staging environment — there is no separate deploy step, and the question only confuses users: Metabase imports the committed bundle straight from the connected repo on its next sync. Once the change is on the branch Metabase syncs from — however the user gets it there (a merged PR, or a push straight to that branch) — just tell them to pull it in and open the app in Metabase at

/apps/<slug>

.

• To update: commit a new build and pull again.
• To remove: delete the app's directory from the repo and push — the next sync removes it. You can't delete a repo-managed app from the UI; the Remove action on the Data apps admin page appears only after the repo is disconnected, to clear out apps left behind.