Metabase Full App To Modular Embedding Upgrade

Execution contract

Follow the workflow steps in order — do not skip any step. Create the checklist first, then execute each step and explicitly mark it done with evidence. Each step's output feeds into the next, so skipping steps produces wrong migrations.

If you cannot complete a step due to missing info or tool failure, you must:

1. record the step as ❌ blocked,
2. explain exactly what is missing / what failed,
3. stop (do not proceed to later steps).

Required output structure

Your response should contain these sections in this order:

1. Step 0: Metabase Version Detection
2. Step 0.1: Migration Plan Checklist
3. Step 1: Project Scan
4. Step 2: iframe Analysis & Web Component Mapping
5. Step 3: Migration Plan
6. Step 4: Applied Code Changes
7. Step 5: Validation
8. Step 6: Final Summary

Each step section should end with a status line:

• Status: ✅ complete or Status: ❌ blocked

Steps are sequential — do not start a step until the previous one is ✅ complete.

Evidence requirements

• Step 0: Metabase version detected (source: Docker tag, env var, or user answer).
• Step 1: every matched file path, every iframe location, SSO endpoint, layout/head file, Metabase config variables.
• Step 2: per iframe — parsed URL, content type, ID, hash params, mapped web component with attributes.
• Step 3: the complete file-by-file change plan with exact old/new code.
• Step 4: per file — what was changed and exact diffs applied.
• Step 5: each validation check's pass/fail result with evidence.

Architectural conformance

Follow the app's existing architecture, template engine, layout/partial system, code style, and route patterns. Do not switch paradigms (e.g., templates to inline HTML or vice versa). If the app has middleware for shared template variables, prefer that over duplicating across route handlers.

Performance

• Maximize parallelism within each step. Use parallel Grep/Glob/Read calls in a single message wherever possible.
• Do not use sub-agents for project scanning — results need to stay in the main context for cross-referencing in later steps.
• Do not parse repo branches, commits, PRs, or issues.

Scope

This skill converts Full App / Interactive embedding (iframe-based) to Modular embedding (web-component-based via embed.js).

The consumer's app may be written in any backend language (Node.js, Python, Ruby, PHP, Java, Go, .NET, etc.) with any template engine. Keep instructions language-agnostic unless a specific language is detected in Step 1.

What this skill handles

• Replacing ` elements pointing to Metabase with appropriate web components (e.g. , `)
• Adding the embed.js script tag (exactly once at app layout level)
• Adding window.metabaseConfig setup code (exactly once at app layout level)
• Modifying SSO/JWT endpoints to support modular embedding's JSON response format
• Mapping iframe URL customization parameters to theme config and component attributes

What this skill does not handle

• Migrating from Static (signed/guest) embedding

Allowed documentation sources

Fetch the version-specific llms-embedding-full.txt using this URL:

https://www.metabase.com/docs/v0.{VERSION}/llms-embedding-full.txt

The version in the URL uses the format v0.58 (normalize: strip leading v or 0., drop patch — e.g., 0.58.1 → 58 → URL uses v0.58). This single file contains all embedding documentation for that version, optimized for LLM consumption.

Other constraints:

• No GitHub PRs/issues or npm pages
• Do not follow changelog links to GitHub or guess URLs

AskUserQuestion triggers

Use AskUserQuestion and halt until answered if:

• The Metabase instance URL cannot be determined from project code or environment variables
• Always ask for the Metabase instance version — do not rely solely on code detection
• An iframe URL pattern does not match any known resource type (dashboard, question, collection, home)
• No SSO/JWT endpoint can be identified in the project
• No layout/head file can be identified (unclear where to inject embed.js)
• Multiple layout files exist and it is unclear which one(s) to use
• The backend language cannot be determined
• Multiple iframes specify different locale values (ask user which locale to set in window.metabaseConfig)

Pre-workflow steps

Migration Plan Checklist

Create a checklist to track progress. In Claude Code, use TaskCreate/TaskUpdate tools:

• Step 0: Detect Metabase version
• Step 1: Scan project + fetch target version docs
• Step 2: Analyze iframes and map to web components (using docs)
• Step 3: Plan migration changes
• Step 4: Apply code changes
• Step 5: Validate changes
• Step 6: Final summary

Workflow

Step 0: Detect Metabase instance version

Always AskUserQuestion for the Metabase instance version — even if a version appears in Docker tags or env vars, confirm it with the user. Abort if v52 or older (modular embedding was introduced in v53).

Then fetch llms-embedding-full.txt for the confirmed version (see "Allowed documentation sources" for URL format).

Before anything else, determine the Metabase version. Grep the project for Docker image tags (metabase/metabase:v, metabase/metabase-enterprise:v), METABASE_VERSION, or version references. If undetected, AskUserQuestion (options: v52 or older, v53, v54–v58, v59+). Abort if v52 or older (modular embedding not available — it was introduced in v53). Record the version — it controls jwtProviderUri placement in later steps.

Step 1: Scan the project + fetch docs no sub-agent)

Perform the project scan and doc fetch concurrently — they are independent. Use parallel tool calls within a single message wherever there are no dependencies.

1a: Fetch target version docs

Fetch llms-embedding-full.txt for the target version (see "Allowed documentation sources" for URL format). These docs are the authoritative source for web component attributes, window.metabaseConfig options, and SSO endpoint behavior for the target version. Use them in Step 2 for mapping instead of relying on hardcoded tables alone.

Launch this concurrently with the project scan steps below.

1b: Identify backend language and framework

• Check for dependency/build files (package.json, requirements.txt, Gemfile, pom.xml, go.mod, composer.json, etc.).
• Identify the template engine and record the language and framework.

1c: Find ALL Metabase iframes

Use Grep to search for all of these patterns (in parallel):

• ` section is defined — this is where embed.js and window.metabaseConfig` will be injected.

Search for:

• ` or ` content is generated

1f: Find Metabase configuration

Grep for METABASE_ and MB_ prefixed variables. Record every Metabase-related variable name and where it is read.

Output: Structured Project Inventory

Compile all findings into:

Backend: {language}, {framework}, {template engine}
Metabase config:
  - Site URL variable: {name} (read at {file}:{line})
  - Dashboard path variable: {name} (read at {file}:{line})
  - JWT secret variable: {name} (read at {file}:{line})
  - Other variables: ...
Layout/head file: {path}:{line range} (or "inline HTML in {file}:{line range}")
Iframes found: {count}
  - {file}:{line} — {brief description}
  - ...
SSO endpoint: {file}:{line} — {route} ({method})

Step 2: Analyze iframes and map to web components (only after Step 1 ✅)

Use the documentation fetched in Step 1a as the authoritative reference for web component attributes, window.metabaseConfig options, and SSO endpoint behavior. The hardcoded tables below are fallbacks — if the docs describe additional attributes or different behavior for the target version, prefer the docs.

For each iframe found in Step 1:

2a: Parse the iframe URL

Extract from the iframe src attribute (which may be a template expression, variable, or literal):

• Metabase base URL: may come from env var, constant, or be hardcoded
• Resource path: the path after the base URL, e.g., /dashboard/1, /question/entity/abc123, /collection/5
• Resource type: dashboard, question, collection, or home (if path is /)
• Entity ID or numeric ID: the resource identifier in the path.
• An ID may be:
• a numeric id, e.g. 123
• a numeric id + slug, e.g. 123-slug. You need to remove the slug completely; including the slug will prevent the resource from loading.
• an entity id — URLs with pattern /{resource_type}/entity/{entity_id} use entity IDs
• URL hash/query parameters used for UI customization (e.g., #logo=false&top_nav=false)
• SSO wrapping: whether the iframe goes through an SSO endpoint first (e.g., /sso/metabase?return_to=...)

2b: Map content type to web component

| Full App iframe path pattern | Modular Web Component | Required Attribute | |---|---|---| | /dashboard/{id} or /dashboard/entity/{entity_id} | ` | dashboard-id="{id or entityid}" | | /question/{id} or /question/entity/{entityid} | | question-id="{id or entityid}" | | /model/{id} or /model/entity/{entityid} | | question-id="{id or entityid}" | | /collection/{id} or /collection/entity/{entityid} | | initial-collection="{id or entity_id}" | | / (Metabase home / root) | | initial-collection="root"` |

If the iframe path is built dynamically from a variable, the web component attribute should use the same variable/expression.

If an iframe path does not match any known pattern → AskUserQuestion.

2c: Map URL customization parameters

Parameters to drop (not applicable — modular web components do not include Metabase application chrome):

| Full App Parameter | Why it is dropped | |---|---| | top_nav | Web components have no Metabase top navigation bar | | side_nav | Web components have no Metabase sidebar | | logo | Web components have no Metabase or whitelabel logo | | search | Web components have no Metabase search bar | | new_button | No + New button (use with-new-question / with-new-dashboard on ` if applicable) | | breadcrumbs` | Web components have no Metabase breadcrumbs |

Parameters that map to web component attributes:

| Full App Parameter | Modular Equivalent | |---|---| | header=false | with-title="false" on the component | | action_buttons=false | drills="false" on the component |

Parameters that map to window.metabaseConfig:

| Full App Parameter | metabaseConfig Property | |---|---| | locale={code} | locale: "{code}" |

Locale migration rules:

• If one locale value is found across all iframes → add locale: "{code}" to window.metabaseConfig automatically
• If multiple different locale values are found across iframes → AskUserQuestion to let the user decide which single locale to set in window.metabaseConfig (modular embedding supports only one global locale)

2d: Output Migration Mapping Table

For each iframe, output:

iframe #{n}: {file}:{line}
  Old: {full iframe HTML or code}
  Content type: {dashboard|question|collection|home}
  ID: {static value or variable expression}
  Dropped params: {list}
  Mapped attributes: {list}
  New: {exact replacement web component HTML}

Step 3: Plan migration changes (only after Step 2 ✅)

Create a complete file-by-file change plan covering all areas below. Every change should be specified with the target file, the old code, and the new code.

3a: embed.js script injection — exactly once per app

• Target: the layout/head file identified in Step 1e
• Location: inside ` (or as close as possible to other ` tags)
• Code to add:

```html

```

• {METABASE_SITE_URL} should be rendered dynamically using the project's existing template expression syntax.
• If the Metabase URL variable is only available in specific routes, pass it to the layout via middleware or template context.
• Verify this will appear exactly once in the rendered HTML regardless of which page the user visits — if it loads twice, the SDK reinitializes and breaks auth state.

3b: metabaseConfig — exactly once per app

Modular embedding reads its configuration from window.metabaseConfig. There is no defineMetabaseConfig() function — assign the config object directly.

• Target: same layout/head file as 3a
• Location: before the embed.js script tag (the config must be set before embed.js loads, otherwise the SDK has no config to read)
• Code to add (minimum — add auth fields only if the fetched docs list them for this version):

```html

window.metabaseConfig = { instanceUrl: "{METABASESITEURL}", // Add auth fields here only if supported by the confirmed version's docs };

```

• Locale: If a locale parameter was found on any iframe in Step 2c, add locale: "{code}" to the config object. If multiple iframes had different locale values, the user will have already been asked which one to use (per AskUserQuestion trigger).
• instanceUrl (and jwtProviderUri if supported) should be rendered dynamically using the project's template expression syntax.
• Auth config fields: Consult the docs fetched in Step 0 to determine which fields window.metabaseConfig supports for the confirmed version. For example, jwtProviderUri may or may not be available. If the docs list it, include it as a full absolute URL (e.g., http://localhost:9090/sso/metabase) — relative paths don't work. If the docs don't list it, the JWT Identity Provider URI must be configured in Metabase admin settings instead (see Step 3f).
• window.metabaseConfig should be set exactly once — if it appears in per-iframe code instead of the layout, each component will re-initialize the SDK.

3c: SSO endpoint modification

The existing SSO endpoint currently redirects the browser to Metabase's /auth/sso?jwt={token}&return_to={path}.

For modular embedding, the embed.js SDK sends a fetch request to the JWT Identity Provider URI and expects a JSON response. The endpoint should be converted to return JSON only — do not keep a fallback to the old redirect-based auth flow.

This is a full migration, not a gradual one. The old iframe-based embedding is being completely replaced, so the redirect behavior is no longer needed.

Consult the auth docs fetched in Step 0 for the expected SSO endpoint response format for the confirmed version.

Constraints:

• Do not modify the JWT signing logic — only change how the response is delivered
• Remove the old redirect behavior entirely — the endpoint should only return JSON
• The JSON response body should be exactly { "jwt": "" } — no other fields, because the SDK parses this exact shape
• Remove any code that builds the redirect URL (e.g., new URL("/auth/sso", ...), searchParams.set("return_to", ...)) as it is now dead code

3d: iframe replacement plan

For each iframe from Step 2d's Migration Mapping Table:

• Specify: file path, exact old code to replace, exact new code
• The new web component should preserve any dynamic ID expressions from the original iframe URL
• If the iframe had explicit width/height attributes or inline style, apply them directly to the web component element (e.g., `) — do not wrap in a `
• If the iframe was styled via CSS classes, apply those classes directly to the web component
• If the iframe was inside a container element with styles, keep that container
• Remove any server-side SSO URL construction that was used only for the iframe src (e.g., building /sso/metabase?return_to=...). But do not remove the SSO endpoint itself — it is still needed for modular embedding auth.
• If the iframe src was built via a server-side route handler that sends inline HTML (e.g., Express `res.send(' Embedding > toggle "Enable modular embedding"

1. Configure CORS origins: Admin > Embedding > Modular embedding > add the host app's domain (e.g., http://localhost:9090)
2. **Config

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: metabase
• Source: metabase/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.