Skip to content

Contributing to Trading Cards

Trading Cards is an open-source library of pre-built HubSpot UI extension templates. Anyone can contribute a template — HubSpot Solutions Partners, developers, admins who can code, or anyone who has built something useful and wants to share it.

This document explains how to submit a template, what the quality bar looks like, and what to expect from the review process.


Check the wanted list first. Open GitHub Issues and look for issues tagged template-request. These are templates the community has asked for — if you build one of these, it’s much more likely to be useful and get merged quickly.

Open an issue before you build. Before spending time building a template, open a GitHub Issue describing what you want to contribute. Use the template-proposal issue template. This lets us give early feedback and avoids you building something that’s already in progress or outside scope.

What makes a good template?

  • Solves a real problem HubSpot admins actually have
  • Works without requiring external services (or documents them clearly if it does)
  • Fits naturally in a CRM record card or app home page
  • Is general enough to be useful across different portals — not something hyper-specific to one company’s setup

Click Fork in the top right of this repo. This creates your own copy of the repo under your GitHub account.

Terminal window
git clone https://github.com/YOUR-USERNAME/trading-cards-templates.git
cd trading-cards-templates

Always work on a new branch, not on main. Name your branch after your template:

Terminal window
git checkout -b template/your-template-name

Follow the template structure below. Your template must be a self-contained folder inside templates/.

Deploy your template to a test HubSpot portal and confirm it works end-to-end before submitting. Check the testing checklist below.

Push your branch and open a pull request against main. Use the PR template — it asks you to confirm the checklist items and describe what your template does.

Terminal window
git add .
git commit -m "Add [template name] template"
git push origin template/your-template-name

Then go to your fork on GitHub and click “Compare & pull request”.

Every submission is reviewed before merging. Expect feedback within 1–2 weeks. Reviews will focus on functionality, code quality, and whether the template fits the library. You may be asked to make changes before it’s merged.

Once approved and merged, your template will be published to the Trading Cards app automatically via the GitHub → template registry sync.


Every template must follow this folder structure exactly:

templates/
└── your-template-name/
├── tc-config.json # Required — Trading Cards metadata
└── src/
└── app/
├── app-hsmeta.json # HubSpot app config
├── extensions/
│ └── YourCard.jsx # The UI extension component
└── functions/ # Serverless functions (if needed)
└── your-function/
├── your-function.js
└── serverless.json

This file is required. It powers the template card in the Trading Cards app.

{
"id": "your-template-name",
"name": "Your Template Name",
"version": "1.0.0",
"description": "One or two sentences. What does this template do? What problem does it solve?",
"category": "deals | companies | contacts | app-home",
"location": "crm-record | app-home",
"author": {
"name": "Your Name",
"url": "https://your-website-or-linkedin.com"
},
"scopes": [
"crm.objects.deals.read"
],
"externalDependencies": [],
"platformVersion": "2025.2"
}

Fields:

  • id — kebab-case, unique, matches your folder name
  • category — pick the CRM object type your template primarily targets
  • scopes — list every HubSpot OAuth scope your template requires. Be accurate — under-declaring breaks deploys.
  • externalDependencies — list any third-party APIs or services your template calls (e.g. ["Mapbox Search API"]). Leave as [] if none.
  • author — your name and a link. This appears on your template card in the app and in the docs.

Standard HubSpot app config. Must include:

{
"name": "Your Template Name",
"description": "Short description",
"uid": "your-template-name",
"scopes": ["crm.objects.deals.read"],
"extensions": {
"crm": {
"cards": [
{
"file": "extensions/YourCard.jsx",
"type": {
"crm-card": {
"title": "Your Card Title",
"location": "crm.record.tab",
"objectTypes": [{ "name": "deals" }]
}
}
}
]
}
},
"auth": {
"type": "static"
},
"distribution": "private",
"platformVersion": "2025.2"
}

These are the most common mistakes. Read them before writing code.

API calls from serverless functions

  • Use hubspot.serverless() — not runServerlessFunction (deprecated)
  • Pass context.portal.id from your JSX component as a parameter — context.accountId is undefined inside serverless functions

CRM properties

  • Use useCrmProperties from @hubspot/ui-extensions/crm to read CRM record properties client-side
  • Do not use propertiesToSend for client-side reads — it’s server-side only

UI components

  • style props are not valid on any @hubspot/ui-extensions component — use layout components (Flex, Box) instead
  • React fragments (<>...</>) are not supported — use <Flex> or another wrapper component
  • Available components: Button, Text, Flex, Table, Input, Select, Toggle, Modal, Tag, Tile, Alert, Divider, LoadingSpinner, SearchInput, Tabs, Tab, AutoGrid, StatisticsItem, StatisticsTrend, BarChart

HubSpot APIs

  • Lists API: use 2026-03 endpoint (/crm/lists/2026-03/...) — the crm/v3/lists endpoint is deprecated and sunset April 30, 2026
  • All external HTTP calls from templates use standard fetch() inside serverless functions (templates use auth: static, not auth: oauth)

Config storage

  • Store per-portal config in HubSpot File Manager (private files)
  • Encrypt any sensitive values (API keys, tokens) with AES-256-GCM before storing

Before submitting your PR, confirm each of these:

  • Template installs to a test portal without errors
  • Template renders correctly in the CRM location defined in app-hsmeta.json
  • All declared scopes in tc-config.json are actually used (no over-declaring)
  • All external dependencies are listed in tc-config.json
  • No hardcoded portal IDs, API keys, or personal data anywhere in the code
  • No data is sent outside the user’s portal except to explicitly documented external services
  • Works on platformVersion: 2025.2
  • tc-config.json is present and all fields are filled in correctly
  • Author name and URL are set in tc-config.json

Pull requests will be closed (with feedback) if:

  • The template doesn’t install or run without errors
  • tc-config.json is missing or incomplete
  • The template sends data to undocumented external services
  • There is hardcoded sensitive data (API keys, portal IDs, personal info)
  • The code is a copy of an existing template with minor changes
  • The template is too narrow to be useful beyond a single company’s setup
  • Code quality is too low to be maintainable by others

PRs are reviewed within 1–2 weeks. If you haven’t heard back after 2 weeks, comment on the PR to follow up.

Reviews happen in the open — feedback will be posted as PR comments. You’re welcome to discuss, push back, or ask questions in the PR thread.


Every merged template includes:

  • Your name and URL on the template card inside the Trading Cards app
  • Your name and URL on the template’s docs page at tradingcards.app/docs/templates/your-template
  • A shout-out when the template is announced on LinkedIn and in the HubSpot community

There is no revenue share on the free tier. If a paid tier launches that includes community templates, contributors will be notified and terms will be agreed separately.


Open a GitHub Issue with the question label, or post in the HubSpot developer community. Don’t email directly — keeping questions in the open means others benefit from the answers.


Trading Cards is maintained by Kye Bessant. Template submissions are reviewed and approved before publishing.