Metabase Static Embedding To Guest 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 Results: Metabase Version Detection
2. Step 0.1: Migration Plan Checklist
3. Step 1 Results: Project Scan + Docs Fetch
4. Step 2 Results: Static Embed 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 static embed location, JWT signing code, layout/head file, Metabase config variables, fetched docs listing.
• Step 2: per embed — parsed iframe URL, content type, token variable, 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.

The web component must be rendered using the same delivery mechanism as the static iframe it replaces. If the iframe was rendered by a server-side template (EJS, Jinja, ERB, Blade, etc.), the web component should be rendered by the same template. If the iframe was returned as inline HTML from a route handler (e.g., res.send('\)), the migrated web component should receive its token the same way — rendered server-side into the token attribute (e.g., ). If the JWT was fetched client-side via fetch(), keep using fetch()` for the token. Do not change the delivery mechanism — just change what is delivered (raw token instead of full iframe URL).

Credential safety

This migration touches code that handles METABASE_SECRET_KEY and signed JWTs. Rules:

• Never output literal secret values — if you encounter a hardcoded secret key or token string in the code, reference it by variable name only (e.g., "the secret in config.js:12"), never echo the value itself
• In code diffs and summaries, use variable references (METABASE_SECRET_KEY, token) — not the resolved values
• If you find hardcoded secrets, flag them to the user and recommend moving them to environment variables as part of the migration

Performance

• Maximize parallelism within each step. Use parallel Grep/Glob/Read calls in single messages 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 static (signed) iframe embedding to guest embeds (web-component-based via embed.js). Both approaches use the same authentication model — signed JWTs with METABASE_SECRET_KEY — so the backend signing logic is preserved. The migration changes how the signed content is delivered: from iframes with JWT-in-URL to web components with a token attribute.

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 signed ` elements (/embed/dashboard/{JWT}, /embed/question/{JWT}) with web components (, `)
• Adding the embed.js script tag (exactly once at app layout level)
• Adding window.metabaseConfig with isGuest: true (exactly once at app layout level)
• Mapping iframe hash parameters (#titled=true, #bordered=true) to web component attributes
• Preserving the existing JWT signing logic — the backend still signs tokens with METABASE_SECRET_KEY using the same {resource, params} payload
• Converting how the signed token reaches the frontend (from iframe URL path to template variable passed as token attribute)
• Mapping locked params in the JWT to initial-parameters attribute where applicable
• Removing iframeResizer.js references if present

What this skill does not handle

• Migrating to SSO-based modular embedding (with user accounts) — this skill targets guest embedding only

How guest embeds differs from static iframe embedding

The auth model is the same — both use METABASE_SECRET_KEY to sign JWTs with {resource, params, exp}. What changes is how the embed is rendered:

| Aspect | Static embedding (iframe) | Guest embeds (web component) | |---|---|---| | Element | ` | | | **Token delivery** | Baked into iframe URL path | Passed as token attribute | | **Config** | None (iframe is self-contained) | window.metabaseConfig = { isGuest: true, instanceUrl: "..." } | | **Script** | Optional iframeResizer.js | Required embed.js | | **Appearance** | Hash params (#titled=true) | Component attributes (with-title="true") | | **Locked params** | In JWT params field | Same JWT params field (unchanged) | | **Secret key** | METABASESECRETKEY | Same METABASESECRETKEY` |

Guest embeds support additional attributes (e.g., downloads, drill-through, hidden parameters) not available in static embedding. Consult the fetched docs for the full list of available attributes for the target version.

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
• The backend language cannot be determined
• The Metabase instance version cannot be determined from the project code
• 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

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 static embeds 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 version

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: v53 or older, v54–v58, v59+). Abort if section is defined — this is where embed.js and window.metabaseConfig` will be injected (unless already present per Step 1c).

Search for:

• ` or ` content is generated

1g: 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})
  - Secret key variable: {name} (read at {file}:{line})
  - Other variables: ...
Layout/head file: {path}:{line range}
Static embeds found: {count}
  - {file}:{line} — {brief description} (dashboard/question, ID: {id})
  - ...
JWT signing: {file}:{line} — {library used}
JWT payload: resource type={dashboard|question}, params={list or "none"}
iframeResizer: {present|not present}
Existing modular embedding: {embed.js: yes/no, metabaseConfig: yes/no}

Step 2: Analyze static embeds 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 guest embedding 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 static embed found in Step 1:

2a: Parse the signed iframe URL

Extract from the iframe src attribute:

• Metabase base URL: may come from env var, constant, or be hardcoded
• Resource type: dashboard or question (from the /embed/{type}/ path)
• Resource ID: the numeric ID from the JWT resource field (e.g., resource: { dashboard: 10 })
• Locked parameters: any params in the JWT payload (e.g., params: { category: ["Gadget"] })
• Hash parameters: appearance customization after # (e.g., #titled=true&bordered=false)
• iframeResizer usage: whether iFrameResize() is called on this iframe

2b: Map content type to web component

| Static embed URL pattern | Modular Web Component | Required Attribute | |---|---|---| | /embed/dashboard/{JWT} | ` | token="{JWT}" | | /embed/question/{JWT} | | token="{JWT}"` |

The token attribute receives the same signed JWT that was previously baked into the iframe URL. The backend signing code stays the same — only the delivery mechanism changes.

If the token was built dynamically in a template (e.g., src="/embed/dashboard/"), extract the token variable and pass it as the token attribute (e.g., token="").

2c: Map hash parameters

Parameters that map to web component attributes:

| Static embedding hash params | Guest embeds equivalent | |---|---| | titled=true/false | with-title="true/false" on the component | | bordered=true/false | No direct equivalent — drop (web components have no border chrome) | | refresh=N | No direct equivalent — drop (handled by Metabase instance config) | | theme=night | Use window.metabaseConfig.theme instead (if supported by version) |

2d: Map locked and editable parameters

Locked parameters (in JWT params field) — no change needed. They remain in the JWT and continue to work the same way. The signed token already contains them.

Editable parameters — if the static embed allowed users to interact with filters, these can now be set as defaults via the initial-parameters attribute:

initial-parameters sets default filter values that the user can change. This is a new capability not available in static iframe embedding.

2e: Output Migration Mapping Table

For each static embed, output:

embed #{n}: {file}:{line}
  Old: {iframe HTML or signing + iframe code}
  Content type: {dashboard|question}
  Token variable: {template expression for the signed JWT}
  Locked params: {in JWT — no change needed}
  Hash params: {list or "none"}
  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: metabaseConfig — exactly once per app

Skip this step if Step 1c found an existing window.metabaseConfig assignment. If it exists but is missing isGuest: true, add that field to the existing config instead of creating a new one.

• Target: the layout/head file identified in Step 1f
• Location: inside ``, before the embed.js script tag (the config must be set before embed.js loads)
• Code to add:

```html

window.metabaseConfig = { isGuest: true, instanceUrl: "{METABASESITEURL}", };

```

• isGuest: true is required — it tells embed.js to use guest (signed token) mode instead of SSO mode.
• instanceUrl should be rendered dynamically using the project's template expression syntax.
• Locale: If a locale parameter was found in any static embed hash, add locale: "{code}" to the config object.
• Consult the fetched docs (Step 1a) for any additional window.metabaseConfig options supported by the target version (e.g., theme, font).
• window.metabaseConfig should be set exactly once.

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

Skip this step if Step 1c found an existing embed.js script tag.

• Target: same layout/head file as 3a
• Location: inside `, after the window.metabaseConfig` script (embed.js reads the config on load)
• Code to add:

```html

```

• {METABASE_SITE_URL} should be rendered dynamically using the project's existing template expression syntax.
• Verify this will appear exactly once in the rendered HTML regardless of which page the user visits.

3c: Refactor backend token delivery

The backend already has JWT signing code that produces the token. Currently it builds a full iframe URL (/embed/dashboard/{token}#params). The signing logic stays — but how the token reaches the frontend changes:

• Before: Backend builds full iframe URL string, passes to template, template renders ``
• After: Backend passes just the signed token to the template, template renders ``

For each signing location found in Step 1d:

1. Keep the JWT signing call (jwt.sign(payload, METABASE_SECRET_KEY)) unchanged
2. Remove the URL construction code that prepended {baseUrl}/embed/dashboard/ and appended hash params
3. Pass the raw token string to the template context instead of the full URL

If the signing happens inline in the template handler (not in a shared function), the change is local to that handler.

3d: iframe replacement plan

For EACH iframe from Step 2e's Migration Mapping Table:

• Specify: file path, exact old code to replace, exact new code
• The new web component uses token="{token_variable}" where {token_variable} is the template expression for the signed JWT
• Map hash parameters to component attributes per Step 2c
• Preserve styling: Transfer the iframe's sizing directly to the web component element — no wrapper `` needed:
• If the iframe had width/height HTML attributes or inline style, apply them directly to the web component (e.g., ``)
• If the iframe was styled via CSS classes, apply those classes directly to the web component
• If the iframe was inside a container that already controls sizing, no extra styling needed — the web component will fill that container
• If the iframe used iframeResizer for auto-height, drop it — web components handle their own sizing
• Remove any iframeResizer calls associated with this iframe

3e: Dead code removal

After replacing iframes, identify and remove:

• URL construction code that built /embed/dashboard/{token}#params or /embed/question/{token}#params strings
• iframeResizer.js script tag and any iFrameResize() calls
• Hash parameter string construction (e.g., const mods = "titled=true&bordered=false")
• Any helper functions that were only used for building static embed ifr

…

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.