@hs-x/codegen

@hs-x/codegen turns an HS-X app's declarations into the concrete artifacts a deploy needs: typed ref stubs that give card and backend code a stable, type-checked link to each other, the Cloudflare Worker entrypoint that boots @hs-x/runtime, the Alchemy program that describes your Cloudflare resources, and the portal-schema management plan. It is the compiler step between what you wrote and what gets deployed.

This package is CLI-internal. You do not install or call it directly; hs-x deploy and hs-x dev invoke it for you (it ships with @hs-x/cli). It is documented here so the generated files in your project's .hs-x/ directory are not a black box.

What it generates

| Export | Artifact | | --- | --- | | generateProjectArtifacts | Writes the .hs-x/ output set for a project: manifest.json, refs.d.ts, refs.js, and alchemy.run.ts | | renderRefsTypes / renderRefsModule | The .hs-x/refs.d.ts and .hs-x/refs.js stubs: one typed export per card backend, app object, and app event, so card code references backend capabilities through generated identifiers instead of hand-typed ids | | renderCloudflareWorkerEntrypoint | The Worker entrypoint that wires your worker definition into createRuntime(...) with token stores, OAuth, and rate limiting | | renderAlchemyProgram / workerCloudflareResourcePlan | The Alchemy infrastructure program written to .hs-x/alchemy.run.ts | | planPortalSchemaManagement | Diffs your declared app objects and properties against the observed portal schema to produce a create/alter plan | | generateHubSpotRuntimeProject / generateLegacyCardProject | Assemble the full HubSpot project source for a deploy or a card migration |

.hs-x/alchemy.run.ts is tracked in git on purpose: it is the leaveability artifact, a plain description of the Cloudflare resources your app owns, so you can keep running the app without HS-X. The rest of .hs-x/ is regenerated on every dev and deploy and stays gitignored.

Part of HS-X

HS-X is a leaveable, type-safe HubSpot app framework on Cloudflare Workers. Deployed apps run in your own Cloudflare account. Start with the CLI:

npm i -g @hs-x/cli
hs-x init myapp

See @hs-x/cli and the docs at hs-x.dev/docs.

License

Apache-2.0