Notion Arena

[Deploy with Vercel] [npm version] [MCP Registry] [License: MIT] [PRs Welcome] [Discord]

Notion Arena

[Notion Arena Hero]

The component registry for Notion.
shadcn/ui's model: browse, configure, copy, own, install from code — applied to Notion dashboards.

[192 Widgets] [11 Recipes] [MCP Ready] [Skill Enabled]

[Time] [Dashboards] [Trackers] [Planning] [Business] [Docs] [Visuals] [Automations]

🎯 What is Notion Arena?

Notion Arena is a machine-readable component registry for Notion — 203 pre-built components you can drop into any Notion page:

Notion is a trademark of Notion Labs Inc. This is an independent project and is not affiliated with or endorsed by Notion.

🎨 Popular Widgets Showcase

[Popular Widgets]

⚙️ Native Recipes (11)

[Native Recipes]

🤖 For AI Agents — MCP + Skill

Plug Notion Arena directly into your AI agent — Claude Code, Cursor, Windsurf, Claude Desktop.

MCP Server

Gives your agent tools to list/search/configure/plan-install all 203 components:

# Claude Code (project scope)claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp
# Or pinned versionnpx -y [email protected]
# Cursor — .cursor/mcp.json# Claude Desktop — claude_desktop_config.json# See docs/AGENT_SETUP.md for all clients

Skill

Teaches your agent the Notion Arena workflow, delivery channels, widget contract:

# Via skills.sh (Vercel) — cross-agentnpx skills add SynergyFlowLabs/notion-arena --skill notion-arena
# Via Claude Code plugin marketplace/plugin marketplace add SynergyFlowLabs/notion-arena/plugin install notion-arena@notion-arena-marketplace
# Manualcp -r skills/notion-arena .claude/skills/notion-arena

Once both are installed, just ask:

"Find me a pomodoro timer for Notion" "Add a CRM pipeline to my Notion" "I need a habit tracker that works offline"

Your agent will use search_components, get_component, build_embed_url, plan_install automatically.

MCP Tools: list_components, search_components, get_component, get_widget_schema, build_embed_url, plan_install, get_registry_item, get_install_guide, get_categories, get_site_info

Skill: skills/notion-arena/SKILL.md + .claude/skills/notion-arena/SKILL.md + .claude-plugin/plugin.json + .claude-plugin/marketplace.json

[MCP Flow]

See docs/AGENT_SETUP.md for MCP+Skill setup and docs/DEPLOY_AND_PUBLISH.md for free deployment (Vercel) + publishing MCP to npm & registry and Skill to skills.sh & plugin marketplace.

🏗️ Three Delivery Channels — Visualized

[Delivery Channels]

One HTML file serves both widget channels, so they cannot drift. Configuration comes from the query string on the hosted path and from a baked-in <script id="bk-config"> on the downloaded path, because a sandboxed block has no URL.

📋 Widget Contract — The 4 Rules

Every widget in public/widgets/ implements the same four rules. See /docs/authoring for the full guide and checklist.

[Widget Architecture]

Plus: body { overflow: hidden } with .wrap managing its own scroll (one scrollbar, not two), a prefers-reduced-motion escape hatch, and clipboard exports that always also console.log the payload as a fallback.

🏃 Running It Locally

# Install dependenciesnpm install
# Restore 13 design/dev skills into .agents/skills/npx skills experimental_install -y
# Start dev servernpm run dev          # http://localhost:3000

Requirements: Node 22+, Next.js 16 (Turbopack), React 19, Tailwind v4, TypeScript.

# Type-checknpx tsc --noEmit
# Widget contract checks (offline HTML validation)npm run check:widgets
# Contrast auditnpm run audit:contrast
# Production buildnpm run build
# MCP servernpm run generate:mcp-catalog  # 143 components → mcp/src/data/catalog.jsonnpm run build:mcp             # build notion-arena-mcpnpm run dev:mcp               # run MCP server with tsx (stdio)

Set NEXT_PUBLIC_SITE_URL in production to https://notionarena.vercel.app so registry manifests emit absolute URLs for the right host. Without it, URLs are derived from the request's forwarded host, falling back to https://notionarena.vercel.app (or http://localhost:3000 in local dev).

📁 Project Layout

public/widgets/*.html      the products: 192 self-contained HTML fileslib/catalog.ts             source of truth for all 203 componentslib/types.ts               component/param types + the 8 categorieslib/widget.ts              config coercion, injection, HTML rendering  (server)lib/widget-url.ts          URL builders                                (browser-safe)lib/notion/schema.ts       Notion API payload builderslib/notion/installer.ts    executes plans against @notionhq/clientlib/recipes/               11 recipe declarations + planInstall()lib/registry.ts            shadcn-compatible manifest generationcomponents/                site UI, catalog browser, configurator, docs proseapp/embed/[slug]/          framed, configured widget HTMLapp/api/widget/[slug]/     the same HTML as a downloadapp/r/[name]/              registry: index.json, schema.json, {name}.jsonapp/api/install/           plan | embed | html-block | apidocs/RESEARCH.md           the research behind all of itskills/notion-arena/       AI agent skill (workflow, channels, contract)mcp/                       MCP server (tools for agents)

📦 The Registry (shadcn-compatible)

GET /r/index.json          the whole catalogGET /r/{name}.json         one item, HTML or recipe JSON inlineGET /r/schema.json         JSON Schema of every widget's parameters

// mcp config / components.json{ "registries": { "@notion-arena": "https://notionarena.vercel.app/r/{name}.json" } }

# see exactly what an install will do: no credentials, touches nothingcurl -X POST localhost:3000/api/install \  -H 'content-type: application/json' \  -d '{"component":"crm-pipeline","mode":"plan"}'
# then run itcurl -X POST localhost:3000/api/install \  -H 'content-type: application/json' \  -d '{"component":"crm-pipeline","mode":"api",       "token":"'"$NOTION_TOKEN"'","parentPageId":"'"$PAGE_ID"'"}'

mode: "plan" requiring no token is deliberate: review the request sequence before authorising any write to your workspace.

⚠️ Two Things Worth Knowing

A widget cannot read or write your Notion data. Notion's HTML block sandbox has no network access and no bridge to its parent page. Widgets may keep user-entered personal state in this browser, but that state is not Notion data and is not shared. If a workflow needs workspace records, collaboration, permissions, or an audit trail, use a native database or recipe.

Relations force a two-pass install. Since Notion split databases from data sources, a relation property targets a data_source_id that does not exist until the target database has been created and read back. planInstall() therefore emits: create databases with base properties → read back each data source id → patch in relations → patch in rollups → patch in formulas → views → seed rows → pages → block bodies in chunks of 100.

Recipes also declare what they cannot do. Four real API gaps (no button block type, no automation endpoint, no recurring-template endpoint, no synced-block duplicates) appear as manual[] steps, each citing the limitation. A manual step whose reason is "it's easier by hand" is rejected.

🤝 Contributing

We welcome contributions! Whether it's a new widget, a native recipe, a bug fix, documentation, or an idea — here's how to contribute.

[Contribution Flow]

Quick Start for Contributors

1. Open an Issue — Discuss your idea first. Check for duplicates. Get maintainer feedback.
2. Fork & Clone — Create your branch: git checkout -b feat/my-widget
3. Develop — Follow the widget contract (see checklist below)
4. Test — Run all checks locally
5. Pull Request — Clear title, link issue, screenshots/GIFs, update CHANGELOG
6. Review — Maintainer review, CI checks, widget contract audit
7. Merge — Auto-deploy to Vercel, MCP catalog regenerates, available immediately

Widget Authoring Checklist

Every widget must pass all checks before merge — see scripts/check-widgets.mjs.

[Widget Checklist]

Adding a New Widget

1. Create public/widgets/my-widget.html (single HTML file, self-contained)
2. Add entry to lib/catalog.ts with all required fields:
   typescript

   {  slug: "my-widget",  name: "My Widget",  emoji: "🎯",  tagline: "One-line hook",  description: "Full paragraph explaining what it does and why.",  category: "time", // time | dashboards | trackers | planning | business | docs | visuals | automations  kind: "widget",  tier: "free", // free | pro  tags: ["tag1", "tag2"],  color: "blue", // red | orange | yellow | green | blue | purple | pink | brown | gray  params: [    { key: "param1", label: "Label", type: "number", default: 10, min: 1, max: 100 },    { key: "theme", label: "Theme", type: "select", default: "auto", options: [...] },    { key: "accent", label: "Accent", type: "color", default: "#2383e2" },  ],  features: ["Feature 1", "Feature 2"],  useCases: ["Use case 1", "Use case 2"],  capabilities: {    interactive: true,    offlineSafe: true,    persistsLocally: false,    writesToNotion: false,    needsNetwork: false,  },}

3. Run npm run check:widgets and npm run typecheck
4. Test in Notion (embed + HTML block)
5. Submit PR

Adding a Native Recipe

1. Create recipe in lib/recipes/my-recipe.ts exporting planInstall() and schema
2. Add entry to lib/catalog.ts with kind: "native" and recipe: "my-recipe"
3. Run npm run generate:mcp-catalog and npm run build:mcp
4. Test with mode: "plan" then mode: "api"
5. Submit PR

Code Style

• TypeScript strict mode — no any, explicit types
• Tailwind v4 — utility-first, no custom CSS unless necessary
• React 19 — server components by default, 'use client' only when needed
• Conventional Commits — feat:, fix:, docs:, chore:, refactor:

📜 Honesty Policy

• No fabricated install counts, star counts, or customer logos
• Badges are qualitative (new, popular, staff-pick) and derived from the catalog
• Market numbers appear only where cited
• Capability claims are booleans in the catalog (interactive, offlineSafe, persistsLocally, writesToNotion, needsNetwork) exposed in the registry so an agent can filter on them instead of reading prose

📄 License

MIT License — see LICENSE for details.

Components you download are yours: modify them, host them, ship them in templates you sell. Free components carry no attribution requirement. See /legal/terms.

🔗 Links

• Live Site: https://notionarena.vercel.app
• MCP Package: https://www.npmjs.com/package/notion-arena-mcp
• MCP Registry: https://registry.modelcontextprotocol.io
• Documentation: https://notionarena.vercel.app/docs
• Research: docs/RESEARCH.md
• Agent Setup: docs/AGENT_SETUP.md
• Deploy & Publish: docs/DEPLOY_AND_PUBLISH.md
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md

Made with ❤️ by SynergyFlow Labs and contributors

[GitHub Stars] [GitHub Forks] [GitHub Issues] [GitHub PRs]