# Projects App Guide

> An unofficial, source-linked guide and agent-ready skill pack for HubSpot Projects CLI app creation and migration planning.

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

## Site Purpose

Projects App Guide helps HubSpot developers and agencies classify Projects CLI app creation and migration planning work, prepare source-linked handoffs, and avoid unsupported claims around the 2026 legacy public app creation sunset.

## Key Boundary

The May 26 and June 23, 2026 dates discussed here affect new legacy public app creation through the legacy Developer Platform UI. This site does not claim that existing legacy public apps stop functioning under that specific sunset.

## Core Pages

- [Home](https://projectsappguide.com): Guide hub, path finder, and product entry point.
- [Answer Hub](https://projectsappguide.com/answers): Direct answer index for Projects CLI app creation and migration planning questions.
- [answers.json](https://projectsappguide.com/answers.json): Machine-readable answer, task-section, checklist, claim, source, and FAQ index.
- [Glossary](https://projectsappguide.com/glossary): Source-linked definitions for Projects CLI and migration terms.
- [Official source index](https://projectsappguide.com/sources): HubSpot official documentation and changelog sources used by this guide.
- [Skill Pack](https://projectsappguide.com/skill-pack): Agent-ready workflow overview.
- [Gumroad product page](https://projectsappguide.com/gumroad): Buyer-facing product page linking to the configured Gumroad checkout.

## Guide Pages

- [HubSpot Legacy Public App Creation Sunset: May 26 and June 23, 2026](https://projectsappguide.com/hubspot-legacy-public-app-creation-sunset): The May/June sunset disables new legacy public app creation in the legacy UI. It does not mean existing legacy public apps stop functioning under this specific event.
- [HubSpot Projects CLI Checklist](https://projectsappguide.com/hubspot-projects-cli-checklist): Use this checklist to classify the app, verify local environment, inspect project files, and choose a command path to verify in official docs.
- [Use hs project create for a New HubSpot Marketplace App](https://projectsappguide.com/hs-project-create-marketplace-app): HubSpot's create-app docs describe new developer platform apps as initialized using the HubSpot CLI, with `hs project create` as the setup command to review.
- [Legacy Public App vs Projects App](https://projectsappguide.com/hubspot-legacy-public-app-vs-projects-app): The sunset is about creating new legacy public apps. Projects-based apps are the path HubSpot directs new public app development toward.
- [hs app migrate vs hs project migrate](https://projectsappguide.com/hs-app-migrate-vs-hs-project-migrate): Use app structure and platform version to decide which path to verify. Non-project legacy public app, existing project app, and private app cases should not be collapsed into one generic migration step.
- [HubSpot Private App Projects Migration](https://projectsappguide.com/hubspot-private-app-projects-migration): Private app cases require special care. The latest-platform migration docs warn that migrating a legacy non-project-based private app to 2026.03 is not currently supported.
- [HubSpot Developer Platform 2026.03 Upgrade](https://projectsappguide.com/hubspot-developer-platform-2026-03-upgrade): The 2026.03 platform version is central to current migration docs. Check `hsproject.json`, current `platformVersion`, and supported migration path before making changes.
- [HubSpot app-hsmeta.json Structure Checklist](https://projectsappguide.com/hubspot-app-hsmeta-json-structure): 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.
- [HubSpot CLI, Node, and CI Preflight Checklist](https://projectsappguide.com/hubspot-cli-node-ci-preflight): Before automating a HubSpot project upload, prove the supported Node/CLI environment, require a 2025.2-or-newer project for the official GitHub Action flow, store account credentials as repository secrets, and define how success and failure will be verified.
- [Legacy CRM Cards to App Cards: October 31, 2026 Planning](https://projectsappguide.com/hubspot-legacy-crm-cards-to-app-cards): Classic/legacy CRM cards have a separate October 31, 2026 migration deadline. Build and beta-test the replacement app card before starting the documented card-view migration, because HubSpot says that cutover cannot be stopped or reversed.
- [HubSpot Marketplace Listing Checklist 2026](https://projectsappguide.com/hubspot-marketplace-listing-checklist-2026): Do not start with listing copy. First prove every current eligibility gate, then complete the seven listing tabs, run validation, resolve every error, and only then submit one app for review.
- [HubSpot hs project upload Checklist](https://projectsappguide.com/hubspot-project-upload-checklist): `hs project upload` uploads a HubSpot project and creates a build. Teams should verify account targeting, auto-deploy behavior, UID stability, auth configuration, and Marketplace implications before using it for meaningful changes.
- [HubSpot hs project dev Local Development Guide](https://projectsappguide.com/hubspot-project-dev-local-development): `hs project dev` starts a local development server for supported HubSpot project extension work. It can refresh supported JSX UI changes, but JSON config changes still need manual upload.
- [HubSpot OAuth Redirect URL and Scopes Checklist](https://projectsappguide.com/hubspot-oauth-redirect-scopes-install-checklist): For multi-account and Marketplace-oriented HubSpot apps, review OAuth redirect URLs, requested scopes, backend credentials, install testing, and shared-data claims before submission or client handoff.

## Structured Execution Contracts

The following contracts distinguish prerequisites, actions, expected results, verification evidence, failure routing, and recovery boundaries. A passed earlier stage never implies a passed later stage.

### HubSpot app-hsmeta.json Structure Checklist

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):
```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:
1. Action: 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.
2. Action: 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.
3. Action: 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.
4. Action: 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:
- Symptom: CLI cannot find a project or `app-hsmeta.json`. Route: 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 when: Stop before upload until project identity and file placement are unambiguous.
- Symptom: Schema validation rejects required fields or component type. Route: Compare `uid`, `type`, `config.description`, `config.name`, `distribution`, and `auth` to the current app-configuration table; fix the named field only. Stop when: Stop if the fix would change an already-uploaded UID without explicit identity-migration approval.
- Symptom: Marketplace distribution is paired with static auth. Route: Change the design to OAuth for Marketplace distribution or reclassify the app as private; do not patch around the mismatch. Stop when: Stop Marketplace work until product distribution and auth architecture agree.
- Symptom: Redirect URL is rejected or OAuth returns a redirect mismatch. Route: Compare the exact configured and requested URL, including scheme, host, path, port, and environment; use HTTPS except the documented `http://localhost` test exception. Stop when: Stop install testing until the exact redirect is reviewed and revalidated; never broaden redirects as a shortcut.
- Symptom: Install succeeds but API calls fail with authorization or scope errors. Route: Compare actual endpoint requirements, configured required/optional/conditional scopes, requested install URL scopes, and granted token scopes. Stop when: Stop before adding broad scopes without a feature-level need and updated shared-data documentation.
- Symptom: Validation passes but upload/build/deploy fails. Route: 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 when: Stop repeated uploads until one root cause and one recovery owner are recorded.

### HubSpot Marketplace Listing Checklist 2026

Prerequisites:
- Eligibility ledger has PASS evidence for access, uniqueness/use-case, matching public app ID/client ID, OAuth-only auth, install threshold, scopes, terms, industry/functionality limits, platform version, and any AI-connector gate.
- At least three active unique installs are evidenced as unaffiliated production accounts with successful app activity in the past 30 days—not test accounts or raw lifetime installs.
- A Super admin owns the listing; a separate engineering owner owns OAuth/install/feature evidence and a content/legal owner owns public URLs and claims.
- All public URLs, setup docs, install flow, shared-data table, pricing, support, privacy, terms, assets, and reviewer test instructions are complete and current.

Actions and acceptance evidence:
1. Action: In Development → App Listings, choose `Create listing` and select the eligible app.
   Expected: The intended app is selectable and the primary listing language can be chosen.
   Verify: Match app name, public app ID/client ID, distribution/auth configuration, owner, and listing language to the eligibility ledger.
   On failure: If Create listing is unavailable or the app is absent, check Super admin access, whether a listing already exists, and whether all existing apps already have listings before changing code.
   Recovery boundary: Do not create a replacement app to bypass uniqueness, access, or listing-state constraints.
2. Action: Complete all seven tabs: Listing info, App details, Pricing, App features, Support info, Testing info, and Review info.
   Expected: Required fields are populated with integration-specific, internally consistent evidence and live URLs.
   Verify: Cross-check install URL, scopes/shared data, pricing, support/privacy/terms, setup guide, screenshots/alt text, test instructions, and contacts against the frozen packet.
   On failure: Route each mismatch to its named owner; do not soften a claim or widen a scope merely to make fields appear complete.
   Recovery boundary: Saving a draft is not submission, eligibility, approval, or publication.
3. Action: On Review info, expand all errors and click `Run validation` after fixing every required field.
   Expected: No unresolved listing errors remain and the submission control is available to the authorized owner.
   Verify: Capture the error-free validation state, app/listing identity, reviewer, timestamp, and current-source check date.
   On failure: Use the error name to return to the responsible tab; if the button is gray, check Super admin permission and missing-field counters before retrying.
   Recovery boundary: An error-free form still does not prove the external URLs are semantically correct, the app works, or HubSpot will approve it.
4. Action: After owner sign-off, submit one app for review and log all HubSpot feedback.
   Expected: The submission enters HubSpot's review workflow and the team has one remediation queue tied to the submitted evidence version.
   Verify: Record submission timestamp, submitted app/listing identity, source commit/evidence version, owner, and subsequent review status or email.
   On failure: Classify the outcome as draft-only, validation error, automatic rejection from parallel submission, reviewer feedback, or rejection; follow the matching route instead of resubmitting blindly.
   Recovery boundary: Approval is discretionary; editing a live listing requires review, and unpublishing is a processed request rather than an instant rollback.

Failure / error router:
- Symptom: Fewer than three qualifying active installs or install evidence is ambiguous. Route: Reconcile unique unaffiliated production accounts and successful qualifying activity in the past 30 days; exclude test accounts, affiliated accounts, duplicates, and inactive installs. Stop when: Stop submission until three qualifying installs are evidenced; never manufacture activity or count test installs.
- Symptom: App uses static auth, another app ID/client ID, classic CRM cards, or an unsupported platform version. Route: Treat as an architecture hard block: correct OAuth/app identity, modernize cards, or upgrade the platform through the applicable official workflow before listing work resumes. Stop when: Stop if the proposed fix changes app identity, existing installs, scopes, or production behavior without a reviewed migration plan.
- Symptom: AI connector lacks user-level permissions or HubSpot MCP Server architecture. Route: Route to product/security architecture and the current HubSpot AI-connector requirement; listing copy cannot remediate it. Stop when: Stop submission until the conditional AI-connector gate is either proven not applicable or satisfied.
- Symptom: Public setup, install, support, terms, privacy, or pricing URL fails review/crawl. Route: Test unauthenticated access, redirects, freshness, semantic field match, URL length, robots/WAF behavior, and `HubSpot Crawler` allowlisting; retest the exact submitted URL. Stop when: Stop while any required page is private, stale, broken, misleading, or accessible only after sign-in.
- Symptom: Shared-data table and OAuth scopes disagree. Route: Map every object scope to data direction and implemented behavior; remove unused scopes or correct the listing and product behavior together. Stop when: Stop before describing read/write data as one-way or requesting scopes the app does not use.
- Symptom: `Validate & submit` is gray or Review info lists errors. Route: Verify Super admin permission, inspect missed-field counts in all seven tabs, expand all errors, open each error, correct it, and rerun `Run validation`. Stop when: Stop submission until the validator is error-free and the evidence packet still matches the edited fields.
- Symptom: Submission is automatically rejected while another app is under review. Route: Place the app in an internal queue and wait for the active review to finish; do not create duplicate apps or repeatedly resubmit. Stop when: Stop until the one-app-at-a-time constraint is clear and an owner schedules the next submission.

## Glossary Terms

- Legacy public app: A HubSpot public app associated with the legacy Developer Platform creation path. The May/June 2026 sunset discussed on this site concerns new legacy public app creation, not an existing-app shutdown claim.
- Projects app: A HubSpot developer platform app managed through Projects-based files and HubSpot CLI workflows.
- hs project create: The HubSpot CLI command path to review when creating a new Projects-based app.
- hs app migrate: A HubSpot CLI migration path to verify for existing public app migration cases.
- hs project migrate: A migration command path associated with existing project-based app or platform-version migration planning.
- app-hsmeta.json: A key app configuration file in Projects-based HubSpot app workflows.
- platformVersion: The project platform version recorded in HubSpot project configuration and used in migration planning.
- Marketplace readiness: The non-code and code-adjacent preparation needed before a HubSpot app Marketplace listing can be reviewed.
- Legacy CRM cards: Classic or legacy CRM cards that have their own modernization workstream and deadline separate from the May/June public app creation sunset.

## Official Sources To Recheck

- [Legacy Public App Creation Sunset](https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset)
- [Create a new app using the CLI](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app)
- [App configuration](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration)
- [Determine your migration path to 2026.03](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview)
- [Migrate an existing public app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app)
- [Migrate an existing app to 2026.03](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-to-the-latest-platform-version)
- [Migrate an existing private app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-private-app)
- [HubSpot CLI project commands](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands)
- [Install the HubSpot CLI](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli)
- [HubSpot CLI reference](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/reference)
- [Set up GitHub Actions for HubSpot projects](https://developers.hubspot.com/docs/developer-tooling/third-party-tools/set-up-github-actions)
- [Listing your app](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app)
- [App Marketplace listing requirements](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements)
- [Legacy CRM cards guide](https://developers.hubspot.com/docs/api-reference/legacy/crm/extensions/crm-cards/guide)
- [Migrate a legacy CRM card to an app card](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/migrate-legacy-crm-cards-to-app-cards)
- [Classic CRM cards deprecation changelog](https://developers.hubspot.com/changelog/deprecating-support-for-classic-crm-cards)

## Usage Notes For AI Assistants

- Treat all guidance as unofficial and educational.
- Re-open current HubSpot official documentation before production-affecting commands, uploads, submissions, or client delivery.
- Do not describe this site as official, certified, endorsed, sponsored, or guaranteed by HubSpot.
- Do not claim that existing legacy public apps stop functioning on May 26 or June 23, 2026 under the legacy public app creation sunset.
- Prefer citing the specific guide page and its official source links when answering HubSpot Projects CLI planning questions.