@hyperscale-it/cf-platform

Cloudflare platform package for monorepos:

1. Runtime SDK — Connect/PSM helpers for Workers (import '@hyperscale-it/cf-platform')
2. Project codegen — cf-platform codegen emits project-local RPC client stubs
3. Workspace generate-config — cf-platform generate-config --env <dev|prod|staging>

Install

pnpm add @hyperscale-it/cf-platform
# or from a packed tarball:
# npm install ./hyperscale-it-cf-platform-0.0.1.tgz

Requires Node ≥ 22. The published/packed artifact is precompiled JS under dist/ (no --experimental-strip-types, no executing src/**/*.ts from node_modules).

Optional peer dependencies

| Peer | When | | --- | --- | | @cloudflare/containers | Only if you call container-PSM fetch at runtime on Workers. Optional; not required for SDK root import, CLI, or codegen. | | @bufbuild/protobuf | Connect proto message types when using generated Connect clients. |

This package does not depend on @cloudflare/workers-types. Public APIs use structural aliases (CloudflareExecutionContext, ServiceBindingFetcher) so Node / Nest consumers typecheck with only @types/node. Worker apps may install workers-types (or Wrangler-generated types) for their own ambient env — that is an app concern, not a platform peer.

Consumer TypeScript notes

• Codegen emits NodeNext-compatible relative imports (./clients.js, ./registry.js, …). Prefer "moduleResolution": "NodeNext" (or Bundler) with "type": "module".
• codegen placeholders (no moon inventory) still satisfy ServiceRegistry — no extra private fields.

Build (contributors)

pnpm --filter @hyperscale-it/cf-platform build
pnpm --filter @hyperscale-it/cf-platform test

CLI

npx cf-platform --help
npx cf-platform codegen --project apps/my-app
npx cf-platform generate-config --env dev
npx cf-platform generate-config --env staging --no-branch-policy --staging-env preview

Migration aliases: dev-runtime-config, deployment-artifacts.

Exports

| Export | Path | | --- | --- | | @hyperscale-it/cf-platform | Runtime SDK (dist/index.js) |

@cloudflare/containers is an optional peer, lazy-loaded only when a container PSM fetch runs. Node-side import('@hyperscale-it/cf-platform') does not require it.

External tools (generate-config)

| Tool | When | Override | | --- | --- | --- | | moon | Discover projects / inventory | --inventory-file / CF_PLATFORM_INVENTORY_FILE | | proto + terraform | validate-terraform (prod/staging) | CF_PLATFORM_TERRAFORM_MODE=direct + CF_PLATFORM_TERRAFORM_BIN | | git | Branch fallback | AGENT_HARNESS_BRANCH / GITHUB_REF_NAME / --branch |

Missing tools produce actionable errors (not silent failures).

Workspace layout (configurable)

Defaults match agent-harness; foreign monorepos should override:

| Path | Default | Override | | --- | --- | --- | | Cloudflare dir | infra/deploy/cloudflare | --cloudflare-dir / CF_PLATFORM_CLOUDFLARE_DIR | | project.yml | <cloudflare-dir>/project.yml | --project-config / CF_PLATFORM_PROJECT_CONFIG | | generated/ | <cloudflare-dir>/generated | --generated-root / CF_PLATFORM_GENERATED_ROOT | | Proto IDL | contracts/idl/proto | --proto-root / CF_PLATFORM_PROTO_ROOT | | Apps prefix | apps/ | CF_PLATFORM_APPS_PREFIX | | Branch policy | agent-harness convention | --no-branch-policy / CF_PLATFORM_SKIP_BRANCH_POLICY=1 |

License

UNLICENSED (internal package).