metabase-full-app-to-modular-embedding-upgrade
Migrates a project from Metabase Full App / Interactive (iframe-based) embedding to Modular (web-component-based) embedding. Use when the user wants to replace Metabase iframes with Modular embedding web components.
metabase · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add metabase/agent-skills --skill metabase-full-app-to-modular-embedding-upgradeAbout this skill
name: metabase-full-app-to-modular-embedding-upgrade description: Migrates a project from Metabase Full App / Interactive (iframe-based) embedding to Modular (web-component-based) embedding. Use when the user wants to replace Metabase iframes with Modular embedding web components. model: opus allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion
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:
- record the step as ❌ blocked,
- explain exactly what is missing / what failed,
- stop (do not proceed to later steps).
Required output structure
Your response should contain these sections in this order:
- Step 0: Metabase Version Detection
- Step 0.1: Migration Plan Checklist
- Step 1: Project Scan
- Step 2: iframe Analysis & Web Component Mapping
- Step 3: Migration Plan
- Step 4: Applied Code Changes
- Step 5: Validation
- Step 6: Final Summary
Each step section should end with a status line:
Status: ✅ completeorStatus: ❌ 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
<iframe>elements pointing to Metabase with appropriate web components (e.g.<metabase-question>,<metabase-dashboard>) - Adding the
embed.jsscript tag (exactly once at app layout level) - Adding
window.metabaseConfigsetup 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
localevalues (ask user which locale to set inwindow.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 `jwtP