fix RivetKit quickstart preview startup

[NathanFlurry]

Summary

• fixes RivetKit quickstart package startup for the preview release flow
• updates backend and Next.js quickstart docs to match the working fresh-project setup
• adds a publish guard so stale engine binary versions fail before release

Validation

• published preview package: 0.0.0-codex-rivetkit-quickstart-preview.7e0cd02
• verified backend quickstart with a plain JavaScript client calling a real counter actor
• verified Next.js stable quickstart with a plain JavaScript client calling a real counter actor through /api/rivet
• reran both E2E checks inside an isolated Docker network

Progress and proof artifacts: /home/nathan/progress/rivet-website/2026-06-29-rivetkit-quickstart-e2e/progress.html

[claude]

PR Review: fix RivetKit quickstart preview startup

This PR fixes the quickstart package startup flow for preview releases: it updates docs for backend and Next.js quickstarts, adds a publish-time guard that verifies engine binary versions before release, adds new generated BARE protocol schema files (v3/v4 client-protocol, v2/v3/v4 inspector), switches dynamic imports to literal strings, enables shims: true in the Node tsup config, and adds a resolveServerlessDrainGracePeriod helper with tests.

---

Findings

.github/workflows/publish.yaml:531 — Windows engine binaries are structurally excluded from version verification

The verification globs are npm/*/rivet-engine (no .exe extension). The publish step at line 446 places the Windows artifact as rivet-engine.exe in win32-x64/. The [ -e "$binary" ] || continue guard skips these silently — not because CI is Linux-only, but because the glob never matches .exe files. A Windows engine binary with a mismatched version string would pass every release gate unchecked.

Fix: extend the glob to also cover rivet-engine.exe:

for binary in \
  rivetkit-typescript/packages/engine-cli/npm/*/rivet-engine \
  rivetkit-typescript/packages/engine-cli/npm/*/rivet-engine.exe \
  rivetkit-typescript/packages/cli/npm/*/rivet-engine \
  rivetkit-typescript/packages/cli/npm/*/rivet-engine.exe

---

.github/workflows/publish.yaml:526 — Verification silently passes if no binaries are found

If the artifact download step produces no files at the expected paths (wrong working directory, artifact naming change, download failure), the for loop iterates zero times, failed stays 0, and exit "$failed" returns success. A release with zero verified binaries looks identical to a release with all binaries correctly verified.

Fix: count verified binaries and fail if the count is zero:

checked=0
# ... existing loop ...
  checked=$((checked + 1))
# after the loop:
if [ "$checked" -eq 0 ]; then
  echo "No engine binaries found to verify" >&2
  exit 1
fi
exit "$failed"

---

rivetkit-typescript/packages/rivetkit/src/registry/napi-runtime.ts:831 — Literal dynamic import violates the split-string convention documented in .claude/reference/dependencies.md

.claude/reference/dependencies.md lines 22–26 explicitly require building module specifiers from string parts (e.g. ["@scope", "pkg"].join("/")) for packages like @rivetkit/rivetkit-napi and @rivetkit/engine-cli so that browser and serverless bundlers cannot statically trace native-only imports. The same applies to @rivetkit/rivetkit-wasm in wasm-runtime.ts and @rivetkit/engine-cli in native.ts.

The esbuildOptions.external list in tsup.config.ts (lines 16–23) does not include any of these three packages. Whether the inherited skipNodeModulesBundle from tsup.base.ts covers this gap should be confirmed before merging, since an unmitigated static trace of a native .node addon would break the published package for bundler consumers.

---

rivetkit-typescript/packages/rivetkit/src/serverless/configure.ts:38 — Return type number | undefined is inaccurate; function always returns number

Every branch of resolveServerlessDrainGracePeriod returns a number: the explicit-override path returns drainGracePeriod (a number, not undefined, per the !== undefined guard), and both auto-computed paths return numeric constants. The | undefined in the return type is a false signal that callers could receive an absent value.

The downstream field drain_grace_period in serverlessConfig receives this value, and any consumer that checks result === undefined as a fallback signal will silently never take that branch. Change the return type to number.

🤖 Generated with Claude Code

[railway-app]

🚅 Deployed to the rivet-pr-5355 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Jul 4, 2026 at 12:52 am
website	😴 Sleeping (View Logs)	Web	Jul 4, 2026 at 12:17 am
kitchen-sink	😴 Sleeping (View Logs)	Web	Jul 3, 2026 at 11:07 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Jul 3, 2026 at 10:20 pm
mcp-hub	✅ Success (View Logs)	Web	Jun 30, 2026 at 9:16 am
ladle	✅ Success (View Logs)	Web	Jun 30, 2026 at 8:20 am