Validate your extension for common errors before deploying to ensure compatibility with the Stackable platform. This checklist helps catch manifest issues, permission mismatches, and surface wiring problems that could cause runtime failures or marketplace rejection.

Tip — let the platform validate for you. The hosted Stackable MCP server exposes a validate_manifest tool that runs the same server-side checks the marketplace submission flow uses. If your AI client is connected to the Stackable MCP server (see AI-Accelerated Development), just ask it to validate packages/extension/public/manifest.json for you — it returns structured errors and warnings without you having to walk the checklist below by hand. The manual steps remain useful for code-level checks the manifest validator can't see (permission usage, surface wiring, sandbox compliance).

1. Manifest validation

Read packages/extension/public/manifest.json and verify:

[ ] Valid JSON
[ ] name is a non-empty string
[ ] version follows semver (e.g., "1.0.0")
[ ] targets is a non-empty array of valid target strings (slot.header, slot.content, slot.footer, slot.footer-links)
[ ] permissions contains only valid permission strings (context:read, data:query, data:fetch, actions:toast, actions:invoke, messaging:send, identity:extend, events:identity, events:messaging, events:activity)
[ ] allowedDomains is an array (can be empty if data:fetch is not used)
[ ] If data:fetch permission is declared, allowedDomains is not empty

2. Permission-to-usage matching

Scan all .tsx files in packages/extension/src/ for capability usage:

capabilities.data.query or data.query → needs data:query permission
capabilities.data.fetch or data.fetch → needs data:fetch permission
capabilities.context.read or useContextData → needs context:read permission
capabilities.actions.toast → needs actions:toast permission
capabilities.actions.invoke → needs actions:invoke permission
useExtendIdentity or capabilities.identity.extend → needs identity:extend permission AND every custom key returned by the handler / passed to extend(patch) MUST be declared in manifest.identityClaims (standard JWT claims external_id / email / name are exempt). Undeclared keys are dropped by the host filter with a console.warn.
useIdentityEvent → needs events:identity permission (also check manifest events array has matching entries)
useMessagingEvent → needs events:messaging permission (also check manifest events array has matching entries)
useActivityEvent → needs events:activity permission (also check manifest events array has matching entries)

Report:

Missing permissions: capabilities used in code but not declared in manifest
Unused permissions: permissions declared in manifest but not used in code
Undeclared identityClaims: keys returned from useExtendIdentity or passed to capabilities.identity.extend that are not in manifest.identityClaims (excluding the standard-claim exemption list)

3. Surface-to-target matching

Each .tsx file with a <Surface id="..."> should have a matching target in manifest.json
Each target in manifest.json should have a corresponding Surface component

4. Import validation

Verify that:

[ ] UI components are imported via ui.* namespace from @stackable-labs/sdk-extension-react
[ ] No direct imports of document, window.location, or other browser globals
[ ] No modifications to packages/preview/ directory
[ ] Entry point is src/index.tsx using createExtension

5. Summary

Print a summary: total issues found, categorized by severity (error vs warning). Errors must be fixed before deploying. Warnings are recommendations.

Next: deploy

Once validation passes, build the production bundle, host it, and register the Bundle URL with Stackable. See the Deploy guide.