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.
Before you start
Section titled “Before you start”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
How to contribute
Section titled “How to contribute”Step 1 — Fork the repo
Section titled “Step 1 — Fork the repo”Click Fork in the top right of this repo. This creates your own copy of the repo under your GitHub account.
Step 2 — Clone your fork
Section titled “Step 2 — Clone your fork”git clone https://github.com/YOUR-USERNAME/trading-cards-templates.gitcd trading-cards-templatesStep 3 — Create a branch
Section titled “Step 3 — Create a branch”Always work on a new branch, not on main. Name your branch after your template:
git checkout -b template/your-template-nameStep 4 — Build your template
Section titled “Step 4 — Build your template”Follow the template structure below. Your template must be a self-contained folder inside templates/.
Step 5 — Test it
Section titled “Step 5 — Test it”Deploy your template to a test HubSpot portal and confirm it works end-to-end before submitting. Check the testing checklist below.
Step 6 — Submit a pull request
Section titled “Step 6 — Submit a pull request”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.
git add .git commit -m "Add [template name] template"git push origin template/your-template-nameThen go to your fork on GitHub and click “Compare & pull request”.
Step 7 — Review
Section titled “Step 7 — Review”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.
Template structure
Section titled “Template structure”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.jsontc-config.json
Section titled “tc-config.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 namecategory— pick the CRM object type your template primarily targetsscopes— 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.
app-hsmeta.json
Section titled “app-hsmeta.json”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"}HubSpot platform rules
Section titled “HubSpot platform rules”These are the most common mistakes. Read them before writing code.
API calls from serverless functions
- Use
hubspot.serverless()— notrunServerlessFunction(deprecated) - Pass
context.portal.idfrom your JSX component as a parameter —context.accountIdis undefined inside serverless functions
CRM properties
- Use
useCrmPropertiesfrom@hubspot/ui-extensions/crmto read CRM record properties client-side - Do not use
propertiesToSendfor client-side reads — it’s server-side only
UI components
styleprops are not valid on any@hubspot/ui-extensionscomponent — 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-03endpoint (/crm/lists/2026-03/...) — thecrm/v3/listsendpoint is deprecated and sunset April 30, 2026 - All external HTTP calls from templates use standard
fetch()inside serverless functions (templates useauth: static, notauth: 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
Testing checklist
Section titled “Testing checklist”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.jsonare 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.jsonis present and all fields are filled in correctly - Author name and URL are set in
tc-config.json
What gets rejected
Section titled “What gets rejected”Pull requests will be closed (with feedback) if:
- The template doesn’t install or run without errors
tc-config.jsonis 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
Review timeline
Section titled “Review timeline”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.
Credit and attribution
Section titled “Credit and attribution”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.
Questions
Section titled “Questions”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.