pyRPC
← Back to Blog

How to version, edit, and ship pyRPC’s multi-package surface

·12 min read

pyRPC is one product and many packages: Python on PyPI (pyrpc-core, framework adapters, codegen) and TypeScript on npm (@pyrpc/client, @pyrpc/types, @pyrpc/react, @pyrpc/next, @pyrpc/vue, @pyrpc/svelte). Different registries, different version numbers — one release story.

Two version lines

npm @pyrpc/* — keep these on a synchronized version (e.g. all 0.8.1) in the npm workspaces under packages/. Peer dependencies pin compatible major/minor of @pyrpc/client and TanStack Query.

PyPI — pyrpc-core, pyrpc-fastapi, etc. may diverge slightly, but any schema change that codegen/TS depends on (like procedure kind) must ship with a matching codegen + npm bump in the same release train.

How to edit safely

  • Transport / protocol — change pyrpc-core + tests first; then adapters if the HTTP contract moved.
  • Generated contract — change introspection + pyrpc-codegen templates; regenerate fixtures; update @pyrpc/types placeholder if the public exports changed.
  • Framework DX — edit only the relevant @pyrpc/react|next|vue|svelte package; do not reimplement fetch.
  • Docs/examples — same PR when the public API renamed (e.g. createNextClient).

PR standards (recommended)

  1. Branch from main: feat/framework-adapters (or similar).
  2. One vertical feature per PR when possible — adapters + kinds + docs + example is one coherent story; avoid mixing unrelated refactors.
  3. Keep commits focused; message the why (Conventional Commits works well: feat(client): add TanStack adapters).
  4. Run: Python tests for touched packages, npm run build/test for touched workspaces.
  5. Open the PR with summary + test plan; do not publish npm/PyPI from the PR branch until review lands.
  6. After merge: tag release, publish npm packages in lockstep, publish PyPI as needed, then deploy docs.

Pushing this work

git checkout -b feat/framework-adapters
git add packages/react packages/next packages/vue packages/svelte \
        packages/pyrpc-core packages/pyrpc-codegen packages/types \
        examples/nextjs docs architecture plan.md
git commit -m "feat: TanStack framework adapters, procedure kinds, docs"
git push -u origin HEAD
gh pr create --title "feat: framework adapters + procedure kinds" --body "..."

Prefer a single PR for the feature set reviewers can reason about. If the diff is huge, split as: (1) core kinds + codegen, (2) JS adapters + example, (3) docs/blog — but land (1) before (2).

Semver guidance while pre-1.0

On 0.x, minor bumps can include breaking DX changes — still call them out loudly in the PR and changelog. Schema additions like kind with a default of query are backward compatible for existing @rpc users.

Related