HubSpot hs project dev Local Development Guide

`hs project dev` is best understood as a local development loop for supported Projects app work. The project commands docs describe it as starting a local development server, and they call out supported browser refresh behavior for JSX changes when developing app cards or settings pages with UI components.

That makes it useful for fast iteration on interactive UI surfaces, copy tweaks, component behavior, and developer feedback loops. It is less useful as a final source of truth for account configuration, OAuth readiness, Marketplace listing quality, or build/deploy behavior.

Before starting local development, install or test the app according to the current create-app flow, confirm the target account, and write down which feature you are testing. A clear test scope keeps local dev from turning into a vague green light.

The official project commands docs make a critical distinction: changes to `.json` config files are not included in the local refresh behavior and need to be manually uploaded with `hs project upload`. This affects planning because many important app decisions live in configuration rather than JSX.

If you change `app-hsmeta.json`, feature schema, auth configuration, scopes, redirect URLs, or other JSON-driven configuration, add a separate upload and verification step. Do not tell a client or product owner that local dev has validated those changes just because a UI surface refreshed in the browser.

A clean workflow separates local UI confidence from project configuration confidence. Use `hs project dev` for the former, then use upload/build/install checks for the latter.

For team handoff, create a short local-dev note: command used, target account, feature tested, files changed, browser behavior observed, JSON config changed or not changed, and next upload required or not required. That note gives a reviewer enough context to understand what was actually proven.

If browser permissions, local network settings, or enterprise device policies interfere with the local development server, document the environment rather than turning the issue into a platform claim. Browser behavior changes over time, so the official docs and the local machine state should both be checked.

For AI-assisted development, paste the local-dev note into the agent prompt and ask for separate next steps for JSX/UI issues, JSON config upload, OAuth install checks, and Marketplace readiness. This mirrors the source boundary and reduces overconfident output.