Build and validate app configuration safely.

HubSpot app-hsmeta.json Structure Checklist

Put the top-level app schema at `src/app/app-hsmeta.json`, validate it before upload, and treat UID, OAuth, scope, and redirect choices as identity and security decisions—not formatting details.

Last source check: 2026-08-29

Citation Summary

Use this page as an unofficial, source-linked planning reference for build and validate app configuration safely. The key takeaway is: Put the top-level app schema at `src/app/app-hsmeta.json`, validate it before upload, and treat UID, OAuth, scope, and redirect choices as identity and security decisions—not formatting details.

Suggested citation: Projects App Guide, "HubSpot app-hsmeta.json Structure Checklist," last source check 2026-08-29, https://projectsappguide.com/hubspot-app-hsmeta-json-structure

Answer Snapshot

Short Answer: For a Marketplace-oriented Projects app, start with a stable app UID, `type: app`, app name and description, `distribution: marketplace`, OAuth, at least one allowed redirect URL, and only the required scopes; then run `hs project validate` from the project root before any upload.
Applies To: Developers troubleshooting Projects-based app structure, identifiers, auth settings, redirect URLs, scopes, and upload readiness.
Verify: Check the current app-configuration schema, record `hs project validate` output, and verify the resulting HubSpot build and install flow separately.
Boundary: Validation is not an upload, install test, feature test, Marketplace eligibility decision, or approval guarantee.

Independent educational guide. Not affiliated with, endorsed by, or sponsored by HubSpot. Verify critical commands and platform behavior against official HubSpot documentation before deploying.

Minimum marketplace schema and file path

HubSpot's app-configuration reference places the top-level schema at `src/app/app-hsmeta.json`. The surrounding project still needs its top-level `hsproject.json`, and feature schemas remain separate `*-hsmeta.json` files under their feature directories.

The smallest useful Marketplace teaching skeleton on this page includes `uid`, `type`, `config.description`, `config.name`, `config.distribution`, and `config.auth`. Marketplace distribution must pair `distribution: marketplace` with OAuth. OAuth needs at least one redirect URL and at least one required scope; the example contact-read scope must be replaced unless the app truly reads contacts.

Logo, permitted URLs, support fields, optional scopes, and conditionally required scopes are not added merely to make the file look complete. Add each only when the app's implemented behavior needs it. Marketplace listing support, privacy, setup, pricing, and review evidence remain a separate gate even if the schema validates.

Validation ladder and evidence

Run environment and account checks first, then run `hs project validate` from the directory containing the intended `hsproject.json`. A pass should be recorded with the command, exit status, CLI version, target account/profile, commit, and timestamp. A clean terminal with no captured evidence is not a handoff artifact.

Only after validation passes should the team consider `hs project upload`. HubSpot's project-command reference says upload creates a build and may auto-deploy when auto-deploy is enabled. Capture the build ID and status with `hs project list-builds`, open the project with `hs project open`, and separately test OAuth, installation, and each changed feature.

The acceptance ladder is therefore schema pass → build pass → deploy state observed → install/OAuth pass → feature smoke pass. Stopping at schema validation must be reported as `CONFIG_VALIDATED`, not `DEPLOYED`, `INSTALL_VERIFIED`, or `MARKETPLACE_READY`.

Current official-doc discrepancies

CLI version: the current create-app page still says to use CLI v7.6.0, while HubSpot's current CLI installation page lists 8.12.0 as the recommended release at this guide's 2026-08-29 check. The pages do not reconcile those statements. Use the current installation page as the version-of-record, update with its documented `npm install -g @hubspot/cli@latest` path when appropriate, and record the actual version used.

Local redirect scheme: the create-app JSON example shows `http://localhost:3000/oauth-callback`, while nearby prose calls the sample `https://localhost:3000/oauth-callback`. The app-configuration reference resolves the rule: redirects use HTTPS, with `http://localhost` allowed only for testing. Do not generalize that exception to non-localhost URLs.

File-tree typography: the app-configuration diagrams render `app-hsmeta.json/` with a trailing slash, but the same page repeatedly calls it a configuration file in the app directory. This guide therefore uses the file path `src/app/app-hsmeta.json` and relies on `hs project validate` rather than interpreting the slash as a directory.

Identity and recovery boundary

Freeze the intended app UID and feature UIDs before the first shared-account upload. HubSpot warns that changing an uploaded UID makes the platform recognize the item as different. Treat an unexpected UID diff as a stop condition, not as a harmless rename.

`hs project validate` is the safe pre-upload gate. `hs project upload` is state-changing because it creates a remote build and may auto-deploy. Before upload, record auto-deploy state, target account, commit, and recovery owner; after upload, do not claim that a Git revert, source backup, or previous build is a universal remote rollback.

Never place client secrets, personal access keys, refresh tokens, or account data in `app-hsmeta.json`, screenshots, verifier output, or the buyer handoff. The schema contains configuration, not runtime secrets.

Execution Contract

Use this as a stage-gated runbook. Each action has a required observable result, verification artifact, failure route, and recovery boundary.

Prerequisites

Use the project root that contains the intended `hsproject.json`; record the target account or profile before validation.
Re-open HubSpot's current CLI installation and app-configuration pages; record Node and HubSpot CLI versions instead of relying on a dated minimum.
Choose and peer-review stable app and feature UIDs before the first shared-account upload.
For Marketplace distribution, use OAuth, an HTTPS production redirect URL, and only scopes required by implemented behavior.

Minimum configuration example

src/app/app-hsmeta.json

{
  "uid": "replace-with-stable-app-uid",
  "type": "app",
  "config": {
    "description": "Explain the installed app behavior.",
    "name": "Example app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["https://example.com/oauth/callback"],
      "requiredScopes": ["crm.objects.contacts.read"]
    }
  }
}

This is a source-backed teaching skeleton, not a universal copy-paste config. Replace the UID, URLs, description, name, and example scope; keep the contact-read scope only when the app actually reads contacts. Add optional schema blocks only for implemented behavior.

Actions and acceptance evidence

Step 1

Run `node --version`, `hs --version`, and `hs account list` before editing or validating.

Expected: Supported local tooling is recorded and the intended developer account/profile is visible.
Verify: Attach sanitized command output, project-root path, account alias/ID, and timestamp to the handoff.
On failure: Repair Node/CLI installation or HubSpot authentication against the current official CLI guide; do not continue to validation.
Recovery boundary: These checks are read-only, but never publish config files or output that contain credentials or private account data.

Step 2

From the project root, run `hs project validate`.

Expected: The CLI reports that the app schema is valid and the project is ready to upload.
Verify: Record exit status and output; diff `src/app/app-hsmeta.json` and all feature UIDs against the reviewed commit.
On failure: Route by the exact validation message: project discovery, JSON/schema field, auth/distribution, URL, scope, or UID; fix only that class and rerun validation.
Recovery boundary: Validation is non-uploading evidence. A pass does not prove remote build, install, OAuth callback, feature behavior, or Marketplace eligibility.

Step 3

After approval of the validated diff, run `hs project upload`, then `hs project list-builds --limit 5` and `hs project open`.

Expected: HubSpot creates a build; its build/deploy state and target project are observable.
Verify: Record build ID, target account/project, commit SHA, build status, deploy status, and whether auto-deploy was enabled.
On failure: Do not rerun blindly. Inspect the failed build and account/profile selection, correct the narrow cause, revalidate, then create a new traceable build.
Recovery boundary: Upload is state-changing and can auto-deploy. A local revert or previous source snapshot is not a universal remote rollback promise.

Step 4

Install in the intended test account and exercise OAuth callback plus each changed feature.

Expected: The exact redirect completes, requested scopes match behavior, and the changed features work in the target account.
Verify: Capture a sanitized install record, callback result, granted-scope comparison, and feature smoke-test outcomes.
On failure: Separate redirect mismatch, denied/missing scope, install permission, backend token exchange, and feature runtime failures; fix and rerun only the affected stage.
Recovery boundary: Do not label a test-account pass as Marketplace approval or production-account compatibility across all tiers and permissions.

Failure / Error Router

Observed symptom	Route next	Stop condition
CLI cannot find a project or `app-hsmeta.json`.	Confirm the current directory contains the intended `hsproject.json`; confirm the file is `src/app/app-hsmeta.json`, not a directory or a feature-level substitute.	Stop before upload until project identity and file placement are unambiguous.
Schema validation rejects required fields or component type.	Compare `uid`, `type`, `config.description`, `config.name`, `distribution`, and `auth` to the current app-configuration table; fix the named field only.	Stop if the fix would change an already-uploaded UID without explicit identity-migration approval.
Marketplace distribution is paired with static auth.	Change the design to OAuth for Marketplace distribution or reclassify the app as private; do not patch around the mismatch.	Stop Marketplace work until product distribution and auth architecture agree.
Redirect URL is rejected or OAuth returns a redirect mismatch.	Compare the exact configured and requested URL, including scheme, host, path, port, and environment; use HTTPS except the documented `http://localhost` test exception.	Stop install testing until the exact redirect is reviewed and revalidated; never broaden redirects as a shortcut.
Install succeeds but API calls fail with authorization or scope errors.	Compare actual endpoint requirements, configured required/optional/conditional scopes, requested install URL scopes, and granted token scopes.	Stop before adding broad scopes without a feature-level need and updated shared-data documentation.
Validation passes but upload/build/deploy fails.	Treat this as a later-stage failure: verify account/profile, inspect build output with `hs project list-builds`, and open the exact project; do not edit schema speculatively.	Stop repeated uploads until one root cause and one recovery owner are recorded.

Checklist

Current CLI install and app-configuration sources re-opened; actual Node/CLI versions recorded.
Project root matched to the intended `hsproject.json` and target account/profile.
Top-level schema stored as `src/app/app-hsmeta.json`.
App and feature UIDs are unique, stable, and peer-reviewed.
Marketplace distribution is paired with OAuth.
Production redirects use HTTPS; `http://localhost` is confined to local testing.
Every requested scope maps to implemented behavior; the example contact scope was removed if irrelevant.
`hs project validate` pass evidence captured before upload.
Build ID, deploy state, target account, and commit captured after any upload.
Install, OAuth callback, granted scopes, and changed features smoke-tested separately.

Claim / Source Map

These are the main claims this page relies on. Re-open the linked official HubSpot source before production-affecting commands, uploads, submissions, or client delivery.

Claim	Official source
The top-level app schema is a file at `src/app/app-hsmeta.json`; its required core includes a unique UID, app type, description, name, distribution, and auth configuration.	App configuration
Marketplace distribution uses OAuth; OAuth redirect URLs use HTTPS except that `http://localhost` is allowed for testing, and an app needs at least one required scope.	App configuration
`hs project validate` checks whether `app-hsmeta.json` is valid and the project is ready to upload.	HubSpot CLI project commands
Changing an app or feature UID after upload makes HubSpot recognize it as a different component, which may be unintended.	Create a new app using the CLI

FAQ

What is the minimum app-hsmeta.json structure for a Marketplace app?

Use a stable `uid`, `type: app`, and `config` with description, name, `distribution: marketplace`, and OAuth containing at least one allowed redirect URL and one genuinely required scope. The example on this page is a teaching skeleton; verify the current official schema and add optional blocks only when the app needs them.

Does `hs project validate` prove Marketplace readiness?

No. It checks app configuration and upload readiness. Build/deploy, OAuth/install, feature behavior, Marketplace eligibility, listing validation, and approval are separate evidence stages.

Can I rename an uploaded app UID and roll back later?

Do not treat UID changes as ordinary renames. HubSpot warns that changing an uploaded app or feature UID makes the platform recognize it as different. Stop, review the identity impact, and define recovery before uploading the change.

Which HubSpot CLI version should I use when official pages differ?

At the 2026-08-29 check, the create-app page mentions v7.6.0 while the current installation guide recommends 8.12.0. HubSpot does not reconcile the two on those pages; use the current installation guide as version-of-record, recheck it live, and record the actual version used.

Download the 2-page checklist

Use the affected/not affected table, command map, and preflight checklist before choosing a path.

Independent educational product. Gumroad checkout opens in a separate page; no official affiliation or guarantee is implied.

View products