metabase-react-sdk-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use this skill for any task involving

@metabase/embedding-sdk-react

— whether that's initial setup, embedding dashboards, theming, or plugins.

Communication style: Be concise. Do one step at a time. When asking the user for input, output only the question — do not explain upcoming steps, implementation details, or what you plan to do next. The user does not need a roadmap.

CRITICAL — YOU MUST GET AN API KEY BEFORE DOING ANYTHING ELSE
Step 1 asks the user for a Metabase URL and API key. You CANNOT proceed without both. Do NOT detect the Metabase version, fetch
llms.txt
, install packages, or write ANY code until the user has given you an API key. Do NOT attempt to call any Metabase API endpoint without an API key — it will return 401 and you will be guessing. If any Metabase API call returns 401, STOP everything and ask the user for an API key.

本技能适用于所有涉及

@metabase/embedding-sdk-react

的任务——无论是初始设置、嵌入仪表盘、主题定制还是插件开发。

沟通风格：简洁明了。分步操作。向用户请求输入时，仅输出问题——无需解释后续步骤、实现细节或下一步计划。用户不需要路线图。

重要提示——在进行任何操作前必须获取API密钥
步骤1会向用户索要Metabase URL和API密钥。缺少其中任何一项都无法继续。在用户提供API密钥之前，请勿检测Metabase版本、获取
llms.txt
、安装包或编写任何代码。请勿在没有API密钥的情况下尝试调用任何Metabase API端点——这会返回401错误，且你将无法准确操作。如果任何Metabase API调用返回401错误，请立即停止所有操作并向用户索要API密钥。

Step 1 — Get the Metabase URL and API key

步骤1 — 获取Metabase URL和API密钥

You need a Metabase instance URL and an admin API key before anything else.

.env.metabase
is only for admin tasks within this skill (API calls to Metabase). It is NOT the app's runtime config. Never import, read, or reference

.env.metabase

from the user's application code or build config. The app's instance URL goes in the user's own

.env

file (e.g.,

VITE_METABASE_URL

NEXT_PUBLIC_METABASE_URL

) — set that up in Step 4.

Check if

.env.metabase

exists in the project root and already has both

METABASE_INSTANCE_URL

(non-empty) and

METABASE_ADMIN_API_KEY

(non-empty). If so, skip to Step 2.

Otherwise, create the file and gitignore it:

bash

grep -qxF '.env.metabase' .gitignore 2>/dev/null || echo '.env.metabase' >> .gitignore
printf 'METABASE_INSTANCE_URL=\nMETABASE_ADMIN_API_KEY=\n' > .env.metabase

Then output only this message — no preamble, no explanation of what comes next, no implementation details:

I created
.env.metabase
in the project root. Please fill in both values:
Set
METABASE_INSTANCE_URL
to your Metabase URL (e.g.
http://localhost:3000
)
Open
{your URL}/admin/settings/authentication/api-keys
, create a new API key
Set
METABASE_ADMIN_API_KEY
to that key
Let me know when you're done

Do not guess or assume the instance URL. Do not pre-fill

localhost:3000

. Do not ask the user to paste the key in the chat — it should only go in

.env.metabase

. Wait for the user to confirm, then proceed to Step 2.

在进行任何操作之前，你需要一个Metabase实例URL和管理员API密钥。

.env.metabase
仅用于本技能中的管理员任务（调用Metabase的API）。它不是应用的运行时配置。切勿从用户的应用代码或构建配置中导入、读取或引用

.env.metabase

。应用的实例URL应放在用户自己的

.env

文件中（例如

VITE_METABASE_URL

、

NEXT_PUBLIC_METABASE_URL

）——这将在步骤4中设置。

检查项目根目录中是否存在

.env.metabase

，且文件中是否已包含非空的

METABASE_INSTANCE_URL

和

METABASE_ADMIN_API_KEY

。如果是，则跳至步骤2。

否则，创建该文件并将其添加到git忽略列表：

bash

grep -qxF '.env.metabase' .gitignore 2>/dev/null || echo '.env.metabase' >> .gitignore
printf 'METABASE_INSTANCE_URL=\nMETABASE_ADMIN_API_KEY=\n' > .env.metabase

然后仅输出以下消息——无需开场白、无需解释后续内容、无需实现细节：

我已在项目根目录创建了
.env.metabase
文件。请填写以下两个值：
将
METABASE_INSTANCE_URL
设置为你的Metabase URL（例如
http://localhost:3000
）
打开
{你的URL}/admin/settings/authentication/api-keys
，创建一个新的API密钥
将
METABASE_ADMIN_API_KEY
设置为该密钥
完成后告知我

请勿猜测或假设实例URL。请勿预填充

localhost:3000

。请勿要求用户在聊天框中粘贴密钥——密钥仅应放入

.env.metabase

文件。等待用户确认后，再继续步骤2。

Step 2 — Detect version and discover dashboards

步骤2 — 检测版本并发现仪表盘

Now that you have an API key, detect the version and find dashboards.

现在你已获取API密钥，可以检测版本并查找仪表盘。

2a — Detect version

2a — 检测版本

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/session/properties" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" | grep -o '"tag":"[^"]*"'

Parse both the edition and the major version from the tag:

Tag format	Edition	Example
`v0.X.Y`	OSS (Community)	`v0.60.1` → major `60` , OSS
`v1.X.Y`	Enterprise (EE)	`v1.60.1` → major `60` , EE

If major version < 49, tell the user the Embedding SDK requires Metabase 49+ and stop.

If the tag starts with
v1.
, the instance is Enterprise Edition — use full JWT SSO embedding. Do not fall back to guest embedding or any OSS-only auth path.

Remember the major version number — you will need it in Step 3.

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/session/properties" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" | grep -o '"tag":"[^"]*"'

从标签中解析版本类型和主版本号：

标签格式	版本类型	示例
`v0.X.Y`	OSS（社区版）	`v0.60.1` → 主版本号 `60` ，OSS
`v1.X.Y`	企业版（EE）	`v1.60.1` → 主版本号 `60` ，EE

如果主版本号 < 49，请告知用户Embedding SDK需要Metabase 49及以上版本并停止操作。

如果标签以
v1.
开头，则该实例为企业版——请使用完整的JWT SSO嵌入方式。请勿回退到访客嵌入或任何仅OSS支持的认证路径。

记住主版本号——步骤3会用到它。

2b — Enable the Embedding SDK

2b — 启用Embedding SDK

Automatically enable the SDK so the user doesn't have to toggle it manually in the admin panel:

bash

source .env.metabase && \
  curl -s -X PUT "$METABASE_INSTANCE_URL/api/setting/enable-embedding-sdk" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": true}'

If this returns an error (e.g., 403), tell the user to enable it manually at <INSTANCE_URL>/admin/settings/embedding and move on.

Do NOT fetch
llms.txt
yet. You need dashboard IDs first.

自动启用SDK，无需用户在管理面板中手动切换：

bash

source .env.metabase && \
  curl -s -X PUT "$METABASE_INSTANCE_URL/api/setting/enable-embedding-sdk" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": true}'

如果返回错误（例如403），请告知用户手动在**<INSTANCE_URL>/admin/settings/embedding**启用该功能，然后继续操作。

请勿获取
llms.txt
。你需要先获取仪表盘ID。

2c — Find dashboards and table candidates

2c — 查找候选仪表盘和表格

Run both of these:

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/search?models=dashboard&archived=false" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/database/1/candidates" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

Filter and prioritize the results:

Exclude any dashboards from the "Usage analytics" collection — those are internal Metabase admin dashboards, not user content.
Deprioritize anything from the "Sample Database" — prefer the user's own databases and dashboards.
Pick the top 5 most relevant to what the user asked for from each category. Do not dump every result.

Format like this:

Existing dashboards:

Sales Overview (ID 3)

Customer Analysis (ID 7) ...

Or I can create a new dashboard from your data: A. Orders table B. Products table ...

Which ones should I embed? (e.g. "1 and 3" or "A")

Wait for the user to pick. If they choose a table, generate and save the X-ray dashboard:

bash

source .env.metabase && \
  DASHBOARD=$(curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/table/<TABLE_ID>" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY")

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/dashboard/save" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$DASHBOARD"

The save response contains the persisted dashboard with a real

id

field. Use these IDs going forward.

运行以下两个命令：

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/search?models=dashboard&archived=false" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

bash

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/database/1/candidates" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

对结果进行筛选和优先级排序：

排除「使用分析」集合中的所有仪表盘——这些是Metabase内部管理仪表盘，不属于用户内容。
降低「示例数据库」中内容的优先级——优先选择用户自己的数据库和仪表盘。
从每个类别中挑选与用户需求最相关的前5个结果。请勿输出所有结果。

按以下格式输出：

现有仪表盘：

销售概览（ID 3）

客户分析（ID 7） ...

或者我可以从你的数据创建新仪表盘： A. 订单表 B. 产品表 ...

你想要嵌入哪些？（例如："1和3"或"A"）

等待用户选择。如果用户选择表格，请生成并保存X-ray仪表盘：

bash

source .env.metabase && \
  DASHBOARD=$(curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/table/<TABLE_ID>" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY")

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/dashboard/save" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$DASHBOARD"

保存响应包含带有真实

id

字段的持久化仪表盘。后续操作请使用这些ID。

Step 3 — Fetch docs, set up auth, and install SDK

步骤3 — 获取文档、设置认证并安装SDK

You MUST have real dashboard IDs before reaching this step. If you don't, go back to Step 2.

Now fetch the versioned docs index using the major version from Step 2a:

bash

curl -s https://www.metabase.com/docs/v0.<MAJOR>/llms.txt

Fall back to

https://www.metabase.com/docs/latest/llms.txt

if empty. This contains correct prop names, auth config shapes, SDK install commands, and breaking changes for this version. Do not fetch

llms-embedding-full.txt

(too large).

进入此步骤前必须已获取真实的仪表盘ID。如果没有，请返回步骤2。

现在使用步骤2a中的主版本号获取对应版本的文档索引：

bash

curl -s https://www.metabase.com/docs/v0.<MAJOR>/llms.txt

如果为空，则回退到

https://www.metabase.com/docs/latest/llms.txt

。该文件包含对应版本的正确属性名称、认证配置结构、SDK安装命令和破坏性变更。请勿获取

llms-embedding-full.txt

（文件过大）。

3a — Set up JWT SSO authentication (skip if already done)

3a — 设置JWT SSO认证（已完成则跳过）

Follow the auth setup instructions in

llms.txt

. In particular:

Retrieve the JWT signing secret from Metabase: Settings → Admin → Embedding → Embedding secret key
Tell the user to save it as
```
METABASE_JWT_SECRET
```
in their server-side environment only (never a browser-accessible env var)
Ask which backend framework they are using (Next.js API route, Express, Fastify, etc.) and scaffold a minimal JWT signing endpoint following the pattern in
```
llms.txt
```

按照

llms.txt

中的认证设置说明操作。特别注意：

从Metabase获取JWT签名密钥：设置 → 管理员 → 嵌入 → 嵌入密钥
告知用户将其保存为
```
METABASE_JWT_SECRET
```
，且仅放在服务端环境变量中（绝不能放在浏览器可访问的环境变量中）
询问用户使用的后端框架（Next.js API路由、Express、Fastify等），并按照
```
llms.txt
```
中的模板搭建一个最小化的JWT签名端点

3b — Install the SDK (skip if already installed at correct version)

3b — 安装SDK（已安装正确版本则跳过）

Check whether

@metabase/embedding-sdk-react

is already in the user's

package.json

If not installed: use the install command from
```
llms.txt
```
(the correct dist-tag matches the instance major version).
If already installed: verify the major version matches. Warn on mismatch and offer to update.

检查用户的

package.json

中是否已包含

@metabase/embedding-sdk-react

。

如果未安装：使用
```
llms.txt
```
中的安装命令（正确的dist-tag与实例主版本号匹配）。
如果已安装：验证主版本号是否匹配。若不匹配则发出警告并提供更新选项。

Step 4 — Generate embedding code

步骤4 — 生成嵌入代码

Use

llms.txt

as the authoritative reference for all API shapes. Write files directly into the user's project — edit existing files in place rather than creating new ones alongside them.

所有API结构均以

llms.txt

为权威参考。直接将文件写入用户项目——在现有文件中编辑，而非创建新文件并存放在旁边。

Code conventions (override anything in the docs)

代码规范（覆盖文档中的任何内容）

JWT SSO only: API keys grant admin-level access and are not safe for end-user embeds. Use a server-side JWT signing endpoint;
```
MetabaseProvider
```
receives its URL. Never generate
```
apiKey
```
,
```
METABASE_API_KEY
```
,
```
api-key
```
, or
```
x-api-key
```
— not even as a placeholder. Deviate only if the user explicitly asks and acknowledges the security risk.
Instance URL from env:
```
VITE_METABASE_URL
```
(Vite),
```
NEXT_PUBLIC_METABASE_URL
```
(Next.js), etc. Never hardcode.
Dashboard IDs as inline literals: always hardcode dashboard IDs directly in JSX — e.g.
```
<InteractiveDashboard dashboardId={7} />
```
. Dashboard IDs are not secrets. Never use
```
import.meta.env.VITE_METABASE_DASHBOARD_*
```
, env vars, config objects,
```
parseDashboardId
```
helpers, or any indirection for dashboard IDs. The goal is clean, minimal code the user can instantly understand and tweak.
Secrets server-side only: JWT secrets must never appear in browser-accessible env vars or frontend code.

仅使用JWT SSO：API密钥具有管理员级权限，用于终端用户嵌入并不安全。使用服务端JWT签名端点；
```
MetabaseProvider
```
接收其URL。切勿生成
```
apiKey
```
、
```
METABASE_API_KEY
```
、
```
api-key
```
或
```
x-api-key
```
——即使作为占位符也不行。仅当用户明确要求并确认知晓安全风险时才可偏离此规范。
实例URL来自环境变量：
```
VITE_METABASE_URL
```
（Vite）、
```
NEXT_PUBLIC_METABASE_URL
```
（Next.js）等。切勿硬编码。
仪表盘ID作为内联字面量：始终在JSX中直接硬编码仪表盘ID——例如
```
<InteractiveDashboard dashboardId={7} />
```
。仪表盘ID不是机密信息。切勿使用
```
import.meta.env.VITE_METABASE_DASHBOARD_*
```
、环境变量、配置对象、
```
parseDashboardId
```
工具函数或任何间接方式获取仪表盘ID。目标是生成用户可立即理解并调整的简洁、极简代码。
机密信息仅放在服务端：JWT密钥绝不能出现在浏览器可访问的环境变量或前端代码中。

Theming

主题定制

After generating the embedding code, inspect the user's app for existing styles — look at CSS variables, Tailwind config, or theme files. Set the

theme

prop on

MetabaseProvider

to match the app's look and feel. At minimum, align:

```
colors.brand
```
— the app's primary/accent color
```
colors.background
```
— to match the page background so the embed doesn't look like a white box on a dark page (or vice versa)
```
fontFamily
```
— to match the app's font

Refer to

llms.txt

for the full theme shape. Keep it minimal — only set values that differ from Metabase defaults.

生成嵌入代码后，检查用户应用的现有样式——查看CSS变量、Tailwind配置或主题文件。设置

MetabaseProvider

的

theme

属性以匹配应用的外观和风格。至少需对齐以下内容：

```
colors.brand
```
——应用的主色调/强调色
```
colors.background
```
——匹配页面背景色，避免嵌入内容在深色页面上显示为白色框（反之亦然）
```
fontFamily
```
——匹配应用的字体

参考

llms.txt

中的完整主题结构。保持极简——仅设置与Metabase默认值不同的属性。