How to publish a plugin
5 steps to go from a custom Metabase visualization to a published plugin on MetaViz Hub.
Requirements
- Metabase Pro or Enterprise — Custom visualizations are not available on the free plan.
- Public GitHub repository — MetaViz Hub reads your plugin files directly from GitHub.
- metabase-plugin.json at the root — The standard Metabase manifest — the only required file.
- A .tgz release asset on GitHub — Users download the installable plugin from your latest release.
Create a custom visualization
Follow the official Metabase documentation to build your custom visualization. This covers the SDK, the component API, and how Metabase loads external plugins.
Read the Metabase custom viz docs →Add the required files to your repo
MetaViz Hub reads one required file at the root of your repository.
metabase-plugin.jsonThe standard Metabase manifest — required to load your plugin in Metabase. See official documentation →{
"name": "my-visualization",
"version": "0.1.0",
"description": "A short description of your plugin",
"main": "dist/index.js"
}MetaViz Hub reads name, version, and description from this file to pre-fill your submission form.
Preview images (recommended)
Place your screenshots in the assets/ directory at the root of your repo. All image files (.png, .jpg, .webp…) will be picked up automatically and displayed as a carousel on both the catalog card and the plugin detail page.
No configuration needed — just drop the images in assets/ and they appear automatically.
Submit your repository
Make sure your repo is public on GitHub, then paste the URL on the submit page. We'll read your metabase-plugin.json automatically, then ask you to fill in category, description and tags in a short form.
Wait for validation
Our team manually reviews every submission. We check the manifest, the preview image, and that the plugin loads correctly in Metabase.
Track your submission status anytime from your account page. If rejected, the reason is shown there and you can fix and resubmit at any time.
Your visualization is live
Once approved, your plugin appears in the catalog. The community can discover it, rate it, and install it directly from its detail page.
Important: publish a .tgz release on GitHub
The download button on your plugin page links to your latest GitHub release. MetaViz Hub looks for a .tgz file uploaded as a release asset — make sure you attach one when you publish a release, otherwise users will get the auto-generated source code archive instead of the installable plugin.
- 1.Build your plugin:
npm run build→ produces a.tgzfile - 2.Go to your GitHub repo → Releases → Draft a new release
- 3.Upload the
.tgzfile as a release asset - 4.Publish the release — MetaViz Hub will pick it up automatically
Frequently asked questions
Which Metabase edition is required?
Custom visualizations work with Metabase Pro and Enterprise only. They are not available on the free or Starter plans. Your users must be on one of those paid editions to install plugins.
Does my repository have to be public?
Yes. MetaViz Hub reads your metabase-plugin.json and preview images directly from your public GitHub repository. Private repositories cannot be submitted.
What file format should the plugin be in?
Metabase loads plugins as .tgz archives. Your build step (usually npm run build) should output a .tgz file. Upload it as an asset on your GitHub release — MetaViz Hub links to it automatically.
What does the review process check?
We manually verify that the metabase-plugin.json is valid, that the plugin loads without errors in Metabase, that preview images are present and representative, and that the description is accurate. Reviews typically complete within 48 hours.
My plugin was rejected. Can I resubmit?
Yes. The rejection reason is shown on your account page. Fix the issue, push your changes to GitHub, then use the Sync button on your account page to re-fetch your repository — your plugin moves back to Pending for review.
Can I update a plugin after it is approved?
Yes. Use the Edit button on your account page to update the description, category, or tags. Changes put the plugin back to Pending while we verify them. To publish a new version, just push a new GitHub release with an updated .tgz asset — MetaViz Hub picks it up automatically.