Metabase Data App Setup

Create a Metabase Data App

A Metabase data-app is a single JS bundle that the host loads inside a Near Membrane sandbox and renders inside its own React tree. The scaffold is a Vite + React + TypeScript project: source under src/, a dev server that previews the app against a real Metabase through the same Near Membrane sandbox + distortion rules Metabase uses in production — so npm run dev behaves like production, including for third-party libraries the app bundles — and npm run build producing a single dist/index.js. (Because the sandbox runs a built bundle, a change rebuilds it and does a soft reload — re-evaluates the bundle in the sandbox and remounts the app, keeping auth/SDK loaded — rather than hot-swapping modules; component state resets, but there's no full browser refresh.) The dev preview also shows a corner ⚠ Diagnostics toolbar that captures runtime errors — including the sandbox's otherwise-opaque blocked-API messages — so failures surface instead of being swallowed. The same data is served as JSON at http://localhost:5174/__data-app/diagnostics, which is how you read it (see "Reading the diagnostics feed" below) — you have a shell, not a browser, and these failures are invisible from the terminal otherwise.

Data apps are served from Git, not uploaded. A single repository is connected to Metabase via remote-sync (Admin → Settings → Remote sync). Each app lives in its own directory data_apps/<app>/ inside that repo — its source, a data_app.yaml (name/path), and the committed built bundle at the path its data_app.yaml declares (dist/index.js by default). On each remote-sync import Metabase materializes one app per directory and serves it at /apps/<slug> url, where the slug is the directory's name. So this skill always scaffolds into the connected repo's data_apps/<app>/ directory, never as a standalone project.

The scaffold ships inside this skill at ./template/ — a Vite + React + TypeScript project that was installed alongside the skill. Step 3 just copies it into the app directory; the skill then guides you through the customization + first-app-content steps — it never generates project files from scratch. If you find yourself writing package.json, vite.config.ts, tsconfig.json, or src/index.tsx by hand, stop — copy the template instead.

When to invoke this skill

• "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.

Step 1 — Locate the remote-sync repository

Data apps live inside the Git repository connected to Metabase via remote-sync. Find it before scaffolding:

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

Step 2 — Name the app and create its directory

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.

Detecting an existing app

If <repo>/data_apps/<slug>/ already holds a project, verify it matches the current data-app-template. Check all of:

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

All checks pass → template-shaped. Ask: "Extend this app, or scaffold a new one under a different slug?" If extend → skip the copy step, edit src/. If new → pick a different slug and restart at Step 2.

Any check fails → not template-shaped (older scaffold or drift). Stop. Tell the user the structure differs from the current template, extending it risks breaking the bundle contract, and ask whether to (1) migrate it, (2) scaffold fresh under a new slug and port the code over, or (3) proceed anyway at their risk. Wait for the answer.

Never overwrite existing files without explicit confirmation.

Step 3 — Copy the template into the app directory

The template ships inside this skill at ./template/ (installed alongside the skill via skills add metabase/metabase/skills#release-x.<major>.x). Copy it into the app directory:

APP_DIR="<repo>/data_apps/<slug>"
# `<skill-dir>` = the directory this SKILL.md was loaded from
# (e.g. `.claude/skills/metabase-data-app-setup`); the template is its `template/` subfolder.
cp -R "<skill-dir>/template/." "$APP_DIR/"

A data app is a subdirectory of the remote-sync repo, not its own repository — so this is a plain copy, never a nested git clone / git init. Everything below runs inside $APP_DIR.

Step 4 — Customize

Once the template is in <repo>/data_apps/<slug>/ (run everything below from that directory):

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 *):

   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:

   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:

   # 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 sources 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:

   name: Sales App        # display name shown in the admin UI
   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
   

   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.

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

Step 5 — Verify the starter app

At this point the data app exists. Keep this workflow focused on creating the project scaffold and proving the starter bundle works.

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

   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.

Stop here if the user only asked to create, scaffold, or set up a data app.

If the next task is to build or iterate on the actual app UI — especially if it mentions an existing data app, Metabase data, generated schema files, saved questions, tables, metrics, actions, filters, semantic-layer entities, or data hooks — treat it as a separate existing-data-app editing task. Use the agent's normal skill-discovery flow from those terms. Do not expand this scaffold skill with data-layer authoring rules.

Do not modify src/index.tsx or tsconfig.json unless the change is genuinely required. The whole build/dev setup lives in the SDK behind dataAppConfig() (which also serves the dev HTML shell — there's no index.html to edit), so vite.config.ts is just:

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

export default dataAppConfig();

dataAppConfig exposes only a curated set of overrides (currently just port). The whole contract — factory shape, externals/globals, the dev sandbox entry, CSS inlining, and SVG-as-component support — is baked in and can't be overridden; that's deliberate, so a data app can't drift from what Metabase loads. There's no local build config to touch (and no index.html — the SDK's dev server serves the HTML shell), and tweaks to src/index.tsx still risk breaking the factory shape and silently break drill popups and routing.

There is intentionally no escape hatch for extra Vite plugins, aliases, or defines — port is the only knob. If you think you need more, you almost certainly don't; solve it in src/ instead.

After every meaningful round of edits, run npm run typecheck. It runs tsc --noEmit over src/ and vite.config.ts — catches wrong prop shapes against the SDK types, broken refactors, missing imports, etc. The Vite dev server does NOT typecheck (it only transpiles), so errors that would fail a production CI run can sit invisibly in a passing npm run dev session. Run it before declaring a task complete.

Before handoff, re-check package hygiene. @metabase/embedding-sdk-react should use the expected data-app SDK source/tag for the target environment, and @types/react-datepicker should not be installed unless the chosen react-datepicker version actually needs it.

Reading the diagnostics feed

npm run dev serves everything the toolbar shows as JSON — the only way you see runtime failures, since sandbox blocks, CSP refusals, failed queries and uncaught errors reach neither the terminal nor npm run typecheck. Check it after any change you can't verify by reading the code.

Loop: note nextEventId before editing → make the change (rebuilds automatically) → re-read. startEventId is inclusive and survives page reloads.

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

{
  "entries": [{
    "eventId": 31, "kind": "blocked-network", "alert": true,
    "summary": "Blocked fetch to api.example.com (not in allowed_hosts)",
    "detail": null,   // stack frames, when any
    "hint": "Add https://api.example.com to allowed_hosts in data_app.yaml …",
    "buildId": 7      // the bundle generation that reported it
  }],
  "clients": 1,       // connected preview tabs — 0 means nothing ran
  "buildId": 7,       // the generation running now
  "staleEntries": 164, // held back, reported by an older build — see below
  "nextEventId": 32   // pass back as ?startEventId=
}

clients: 0 does not mean healthy — it means no preview tab is open, so an empty entries proves nothing. Open http://localhost:5174 first.

The feed answers for the bundle that is running, not for everything that ever happened. Every save rebuilds and remounts the app, so a multi-step edit runs through builds that don't compile or don't render — errors from those describe code the preview has already replaced. They're withheld and counted in staleEntries; read mid-edit and you see the current build's failures, not a pile of them. Nothing is lost: the rebuild re-runs the app from scratch, so anything still broken reports itself again under the new buildId, and ?includeStale=true hands back the withheld entries when comparing builds is the point. A failed build doesn't advance buildId — the preview keeps running the last good bundle, so its entries stay current.

Triage by kind (always read hint — it names the exact fix; never soften a summary when reporting it):

Text is truncated and the buffer holds the last 200 events. curl -X DELETE .../__data-app/diagnostics clears it for every reader.

Source conventions

1. Write TSX

Plain ESM + TSX, normal package imports:

// src/components/CustomerCard.tsx
import { StaticQuestion } from "@metabase/embedding-sdk-react";

type Customer = { name: string; questionId: number };

export default function CustomerCard({ customer }: { customer: Customer }) {
  return (
    <article>
      <h3>{customer.name}</h3>
      <StaticQuestion questionId={customer.questionId} height={300} width="100%" />
    </article>
  );
}

2. Structure from the start

Default project layout once the starter app is extended:

src/
├── index.tsx          (template — the factory; don't edit)
├── App.tsx            (routing + composition only)
├── theme.ts
├── pages/             (one file per screen)
│   ├── Overview.tsx
│   └── CustomerDetail.tsx
├── components/        (shared UI)
│   └── Card.tsx
├── hooks/             (data-fetching wrappers, custom hooks)
│   └── useCustomers.ts
├── lib/               (pure helpers / derivations)
│   └── format.ts
└── types/             (shared TS types)
    └── customer.ts

Vite bundles everything reachable from src/index.tsx into a single dist/index.js IIFE — the folder layout is purely for your own readability.

If the app has multiple tabs (or any top-level screen switcher), the default — leftmost / first — tab MUST be selected on initial load. The app should never boot to a blank page, an empty shell, or a "nothing selected" state that waits for the user to click. Agents repeatedly forget this. For local-state tabs, initialize the active tab to the first one so the very first render shows it:

const [active, setActive] = useState(TABS[0].id); // default = leftmost tab

If the tabs are instead backed by URL routes (multiple pages), the same rule applies via the router — see the metabase-data-app-routing skill for making the base path / resolve to the default tab. Either way, verify by loading the app fresh: the leftmost tab's content is visible immediately and reads as selected.

The build output is one self-contained .js file — nothing else. The backend serves a single bundle, so there are no sidecar files: CSS is inlined into the JS, and every imported asset (images, fonts, SVGs-as-URLs) is base64-inlined as a data URI. So import logo from "./logo.png" / import iconUrl from "./icon.svg" give you a ready-to-use data-URI string, and SVGs can also be imported as React components with the ?react suffix (built-in svgr): import Icon from "./icon.svg?react". Everything gets baked into dist/index.js — just keep large binaries out, since inlining inflates the bundle. (If your editor doesn't recognize a ?react import, add declare module "*.svg?react"; to a .d.ts in src/.)

3. Import SDK values from the correct SDK entrypoint

The build externalizes React, the JSX runtimes, @metabase/embedding-sdk-react, and @metabase/embedding-sdk-react/data-app to sandbox globals in both production and npm run dev — in dev the sandbox entry endows them from the npm package, so the bundle runs identically in both. Just import from the entrypoints normally:

// ✅ correct
import { StaticQuestion } from "@metabase/embedding-sdk-react";
import {
  DataAppRouter,
  DataAppLink,
  useMetabaseQuery,
} from "@metabase/embedding-sdk-react/data-app";

// ❌ wrong — no globalThis pattern; you'd be reading nothing
const { MetabaseProvider, StaticQuestion } = globalThis;

Do NOT render <MetabaseProvider> in App.tsx. The dev entry (served by the SDK's dev preset) and the production host both wrap your tree in a provider that lives in their own realm — wrapping inside the bundle would route the SDK's setState-via-listener paths through the Near Membrane sandbox and silently break drill popups, plugin init, and similar.

4. Import react normally too

The build externalizes react and react-dom, so plain imports resolve the same way in both modes — the production host and the dev sandbox both endow them as sandbox globals:

import { useState, useEffect, useMemo } from "react";

No import React from "react" needed in TSX files — the template uses the automatic JSX runtime (jsx: "react-jsx" in tsconfig.json; dataAppConfig() includes the React plugin). The compiler injects the JSX-runtime imports it needs (react/jsx-runtime in production, react/jsx-dev-runtime in dev — both externalized and endowed by the sandbox). Just write JSX and named imports — that's it.

For React types (e.g. ComponentType, ReactNode, RefObject), use named type imports rather than the React. namespace:

import type { ComponentType, ReactNode } from "react";

Theme rules

MetabaseProvider's theme (defined in src/theme.ts) is the only way SDK component appearance changes. It is NOT a stylesheet for the bundle's own chrome.

Hover colors are a contrast pair. If you set colors.text-hover, verify it contrasts with colors.brand-hover / colors.brand-hover-light in open menus, chart type selectors, and visualization settings dropdowns. For a blue brand, use a pale hover surface like #EAF4FF, not the brand blue itself.

The theme only styles SDK widgets — never your own UI. For your page background, headers, card wrappers, etc., use inline style={{ background: "#f5f5f7" }} or CSS modules on your own elements.

Don't expect per-subtree theming. Multiple <MetabaseProvider>s on the page fight for the single CSS-variable slot. If the look needs to change with state, recompute sdkTheme at the App level and re-render — the whole tree re-themes.

Custom error UI (optional)

When an embedded question or dashboard can't load — its questionId was removed, the user lacks access, or a request fails — the host renders a neutral built-in error state in place of that component (a muted icon + the SDK's message). This needs no setup; leave it alone unless the app has a strong reason to restyle it.

To match the app's look, return your own errorComponent in the factory's providerProps (the same object that carries theme). It's an ordinary providerProps key, not a change to the factory shape — safe to add:

// 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 },
});

Rules:

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

Available SDK surface

The bundle imports React hooks/JSX, SDK components from @metabase/embedding-sdk-react, and data-app-specific routing/query APIs from @metabase/embedding-sdk-react/data-app. dataAppConfig() externalizes these packages at build time, so production references the host's copies at runtime (globalThis.__metabase_sdk__ / globalThis.__metabase_data_app__ for SDK packages), and the Vite dev sandbox endows the same globals from the installed npm package.

<MetabaseProvider> is not rendered by the bundle's App.tsx — the dev entry and the host wrap it for their respective modes. Bundle author only renders the content below.

Blocked APIs

The Near Membrane sandbox throws at runtime on these globals. Use the endowed replacement instead:

Rule of thumb: if you're about to touch window.X, document.X, navigator.X, history.X, or any storage global, stop and pick the endowed replacement above. The endowed surface (React + React DOM + SDK components + data hooks + useAction + DataAppRouter + copy) covers every routine need; anything outside it is intentionally unreachable.

Rendering a chart: Metabase first

This is a per-element decision, not one taken once for a row, a section, or the app. One tile that needs custom code makes a row with one custom tile in it, not a row of them — the rest stay SDK components and keep their formatting, theming and drill-through. Consistent heights and card chrome come from the container each tile sits in, so "the others should match it" is not a reason to hand-build the others.

A built-in visualization carries the instance's theming, accessibility, tooltips, formatting and drill-through. A chart built in React carries none of that, and drifts from every other chart in the app as soon as either changes. So the question is never "which looks closer to my design" — it is can Metabase display this at all?

• 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 is the default of the two. It renders the visualization and nothing else — no query bar, no editor, no save — and takes withChartTypeSelector, withDownloads, title and the sizing props. Use InteractiveQuestion when the element is meant to be explored: drill-through, filtering, switching the chart type, or the notebook editor. It shows a Save button unless you turn it off — isSaveEnabled defaults to true — which offers viewers a save-to-collection flow that belongs in Metabase, not in an app, so pass isSaveEnabled={false} unless the app is deliberately an editing surface. That applies to the default layout; giving InteractiveQuestion its own children replaces the layout, so a composed <InteractiveQuestion.QuestionVisualization /> renders no toolbar and no Save button.

Pass title={false} when the question sits in a card or section that already carries a heading. InteractiveQuestion's default layout shows the question's own title, so you get two; StaticQuestion hides it already.

"It has to match our styling" is not a reason to hand-build one: pass visualization for the chart type, visualizationSettings for setting-level changes, and theme the SDK for the rest. A pie chart in a data app is a Metabase pie chart — unless the user asked for a custom one, which is their call to make, not one to infer from a design reference, brand colours, or a screenshot of something bespoke.

A single-value KPI is a scalar — or smartscalar, gauge, progress. If the tile wants a number plus something Metabase does not draw, such as a star row, a caption, or a total from a second query, render the scalar for the number and put the extra beside it. Hand-build it only when the number itself cannot come from one.

Always render a spinner (or skeleton) while isLoading is true — never an empty slot or stale value, which causes layout shift when the data arrives. Same rule for lifted / derived queries (pass isLoading down) and for useAction's isExecuting (spinner in the button + disabled={isExecuting}).

For the hook contract itself — generics, table sources, segments, measures, breakouts, sorting, and debugging — use skill discovery before authoring schema-backed data-layer code.

App layout — fill the frame height

Metabase and npm run dev both give the bundle a full-height frame, but nothing between it and your root element sets a height — so an app shorter than the frame ends where its content ends, leaving its background, sidebar and footer in a short strip over bare white.

So the app's outermost element carries minHeight: "100vh" (plus boxSizing: "border-box" when it has padding) and paints the page background. minHeight, never height — taller content must still scroll. Regions that should reach the bottom (sidebar, sticky footer) go in a flex-column root with flex: 1. Check the emptiest screen — loading, empty state, a lone KPI — those are the ones that render short.

SDK component sizing

SDK components do NOT auto-fit their parent — without height/width they render at their intrinsic size and overflow. Setting only the outer container or card height is not enough either; the height goes on the SDK component that owns the visualization:

• Chart only: pass height to InteractiveQuestion.QuestionVisualization.
• Default question layout with query bar: pass height to InteractiveQuestion.
• Static question: pass height to StaticQuestion.

Use the actual body height available to the chart. For example, if a card is 560px tall and has a 60px header, pass height="500px".

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

Do not wrap `Interac

…(truncated)