create-stitchkit 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -12,6 +12,35 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.4] — 2026-09-23
+
+### Fixed
+
+- **The board reaches the API on two local ports.** The base template's board
+  posts to its own origin (`/api/…`), and the README said the web role forwards
+  that — but the forwarding route lived only in the repository example, so a
+  blank scaffold answered 404. The route
+  (`packages/frontend/src/app/api/[...path]/route.ts`) is now in the base
+  template, and says in words when `INTERNAL_API_URL` is unset.
+- **The browser build carries the socket client.** The board passes
+  `peers: { client: () => import('socket.io-client') }` to
+  `createRealtimeClient`; without the literal loader the bundle had no
+  `socket.io-client` and the page failed with "needs the socket.io-client peer".
+- **The socket dials the API role in development.** `.env.example` now sets
+  `INTERNAL_API_URL`, `PUBLIC_REALTIME_ORIGIN` and `CORS_ORIGIN` for the two
+  local ports, and the repository example passes its realtime origin to the
+  board. A two-tab browser test proves a note posted in one tab reaches the
+  other in both variants.
+
+### Changed
+
+- **A scaffold starts on stitchkit 0.95.3**, whose watch client no longer drops
+  the values of a restarted API. The template's range moves from `^0.94.0` to
+  `^0.95.3`, over a lockfile resolving 0.95.3.
+
+  A project generated from 0.6.3 adds the route file above, the `peers` line in
+  `features/board/board-live.ts` and the three variables to its `.env`.
+
 ## [0.6.3] — 2026-09-23
 
 ### Changed

package/examples/repository/_env.example.append

@@ -1,17 +1,3 @@
-# The web role reaches the API role internally, and forwards the browser's
-# same-origin `/api/…` calls to it. This one is required.
-INTERNAL_API_URL=http://127.0.0.1:3211
-
-# The realtime socket, and ONLY it. A WebSocket upgrade does not survive the
-# route handler that forwards `/api`, so two roles on two loopback ports must
-# name the socket's origin even though their HTTP is already same-origin.
-# Behind one routing layer that forwards `/socket.io`, leave this unset.
-PUBLIC_REALTIME_ORIGIN=http://127.0.0.1:3211
-
-# The browser origin the API role admits — for HTTP and for the realtime
-# handshake alike. Needed here because the socket above is cross-origin.
-CORS_ORIGIN=http://127.0.0.1:3210
-
 # THE CROSS-ORIGIN HTTP VARIANT — unset, and unnecessary for this example.
 # Set it only for a frontend that dials the API role itself instead of calling
 # its own `/api`: separate hostnames with nothing in front of them. Setting it

package/examples/repository/packages/frontend/src/app/[locale]/page.tsx

@@ -3,6 +3,7 @@ import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
 import { LocaleSchema } from '@/i18n/locales';
+import { publicRealtimeOrigin } from '@/lib/api/place';
 import { useRepository } from '@/lib/api/queries';
 import { createServerRepositoryApi } from '@/lib/api/server-client';
 import { getQueryClient } from '@/lib/query-client';
@@ -39,6 +40,7 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
         heroTitle={t('heroTitle')}
         catalogueLabel={t('ui')}
         locale={appLocale}
+        realtimeOrigin={publicRealtimeOrigin()}
       />
     </HydrationBoundary>
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -83,7 +83,7 @@
     "@types/react": "^19.3.0",
     "ai": "^7.0.111",
     "react": "^19.3.0",
-    "stitchkit": "0.93.0",
+    "stitchkit": "0.95.3",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/README.md

@@ -72,10 +72,12 @@ Two things can pull a deployment out of that, and they are separate questions,
 so they have separate variables. **`PUBLIC_REALTIME_ORIGIN`** is the socket: a
 WebSocket upgrade does not survive the route handler that forwards `/api`, so
 two roles on two ports with nothing in front of them must name the socket's
-origin even though their HTTP is already same-origin. Behind one routing layer
-that forwards `/socket.io`, leave it unset. **`PUBLIC_API_ORIGIN`** is HTTP, for
-a frontend that genuinely dials the API role itself — and setting it changes
-nothing on its own: switching is one import in
+origin even though their HTTP is already same-origin — `.env.example` sets it,
+with `CORS_ORIGIN` admitting the web origin, for the two local ports. Behind one
+routing layer that forwards `/socket.io`, leave both unset.
+**`PUBLIC_API_ORIGIN`** is HTTP, for a frontend that genuinely dials the API
+role itself — and setting it changes nothing on its own: with
+`--example repository`, switching is one import in
 `packages/frontend/src/lib/api/queries.ts`, documented in
 `packages/frontend/src/lib/api/cross-origin.ts`. That variant costs a
 server-delivered address, a client built on first use (hence the parentheses),

package/template/_env.example

@@ -22,5 +22,17 @@ SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
 # carries. List here only the hosts this deployment really answers for.
 PUBLIC_WEB_HOSTS=127.0.0.1:3210
 LOG_FORMAT=pretty
-# CORS_ORIGIN is only needed for a genuinely cross-origin browser.
-# CORS_ORIGIN=http://127.0.0.1:3210
+
+# The web role reaches the API role internally, and forwards the browser's
+# same-origin `/api/…` calls to it (packages/frontend/src/app/api/[...path]).
+INTERNAL_API_URL=http://127.0.0.1:3211
+
+# The realtime socket, and ONLY it. A WebSocket upgrade does not survive the
+# route handler that forwards `/api`, so two roles on two loopback ports must
+# name the socket's origin even though their HTTP is already same-origin.
+# Behind one routing layer that forwards `/socket.io`, leave this unset.
+PUBLIC_REALTIME_ORIGIN=http://127.0.0.1:3211
+
+# The browser origin the API role admits — for HTTP and for the realtime
+# handshake alike. Needed here because the socket above is cross-origin.
+CORS_ORIGIN=http://127.0.0.1:3210

package/template/bun.lock

@@ -145,7 +145,7 @@
     "zod": "4.6.5",
   },
   "catalog": {
-    "stitchkit": "^0.94.0",
+    "stitchkit": "^0.95.3",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.89", "", { "dependencies": { "@ai-sdk/provider": "4.0.17", "@ai-sdk/provider-utils": "5.0.45", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-n0Q88UUASYQBGK3Ogs9pCe8h3ZXeTHFSuGOLBJAyH73MVGNKUv9w8EJX2f340WUF3eDWWOV305gO7YBpSCPblA=="],
@@ -1128,7 +1128,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.94.0", "", { "dependencies": { "ky": "^2.1.0" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2 || ^2.0.0", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.1.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.2", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.4.2", "ai": "^7.0.107", "google-auth-library": "^11.1.0", "grammy": "^1.46.0", "maxmind": "^5.0.7", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5 || ^1.0.5", "zod": "^4.6.5" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "google-auth-library", "grammy", "maxmind", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"], "bin": { "stitchkit": "dist/entrypoints/bin/upgrade-cli.js" } }, "sha512-fZ7b/YwiOs8Hia5cNJgDxOzRBAb2nNMaEq2Zh7GWeIFdhKVz9Ywn2B83G4ZvUjqgNnPooclMdDXo6NBSOL/wBA=="],
+    "stitchkit": ["stitchkit@0.95.3", "", { "dependencies": { "ky": "^2.1.0" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2 || ^2.0.0", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.1.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.2", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.4.2", "ai": "^7.0.107", "google-auth-library": "^11.1.0", "grammy": "^1.46.0", "maxmind": "^5.0.7", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5 || ^1.0.5", "zod": "^4.6.5" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "google-auth-library", "grammy", "maxmind", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"], "bin": { "stitchkit": "dist/entrypoints/bin/upgrade-cli.js" } }, "sha512-IVIf7CF951Q4Olfiu+wONxAmc802zvPwGYWjNo+657OHua4gzc91XNo4/zmmPPZzkvA6iyOQmzFurgrbmJ9SrQ=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 

package/template/e2e/starter.spec.ts

@@ -35,6 +35,24 @@ test('calls the live backend through the typed contract client', async () => {
   }).toPass({ timeout: 5_000 });
 });
 
+test('a note posted in one tab reaches another through the web origin and the socket', async ({
+  browser,
+}) => {
+  // The browser's own origin carries HTTP (`/api` is forwarded by the web
+  // role) and the socket dials the API role; a post in one tab must reach a
+  // second tab that never asked for it. Both halves failed silently before:
+  // `/api` was a 404 on the web port, and the browser build had no socket.
+  const writer = await browser.newPage();
+  const reader = await browser.newPage();
+  await Promise.all([writer.goto('/en'), reader.goto('/en')]);
+  const note = `note ${Date.now()}`;
+  await writer.getByRole('textbox', { name: 'Note' }).fill(note);
+  await writer.getByRole('button', { name: 'Post' }).click();
+  await expect(writer.getByText(note)).toBeVisible();
+  await expect(reader.getByText(note)).toBeVisible({ timeout: 10_000 });
+  await Promise.all([writer.close(), reader.close()]);
+});
+
 test('publishes complete page metadata', async ({ page }) => {
   await page.goto('/en/ui/themes');
   await expect(page).toHaveTitle(`Theme system · ${appDeclaration.identity.name}`);

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.94.0"
+    "stitchkit": "^0.95.3"
   },
   "overrides": {
     "@playwright/test": "1.63.0",

package/{examples/repository → template}/packages/frontend/src/app/api/[...path]/route.ts

@@ -1,10 +1,10 @@
-import { internalApiUrl } from '@/lib/api/place';
+import { env } from '@/env';
 
 /**
  * The default shape: the browser talks to its OWN origin, and the web role
- * forwards to the API role.
+ * forwards `/api/…` to the API role.
  *
- * This is what makes the example's client a plain module constant. A browser
+ * This is what makes the board's client a plain module constant. A browser
  * that dials the API role directly needs that role's public address, which is a
  * property of the place — so the address has to arrive from the server at
  * runtime, the client cannot exist until it does, and every call site pays for
@@ -13,9 +13,9 @@ import { internalApiUrl } from '@/lib/api/place';
  *
  * What it costs: one extra hop through the web role, and no WebSocket — a
  * route handler cannot proxy an upgrade. The realtime socket is therefore the
- * one place this example still needs the API role's address, or a routing layer
- * in front of both roles that serves them on one origin (see
- * `lib/api/cross-origin.ts`).
+ * one place the browser still needs the API role's address
+ * (`PUBLIC_REALTIME_ORIGIN`), or a routing layer in front of both roles that
+ * serves them on one origin.
  */
 export const dynamic = 'force-dynamic';
 
@@ -28,10 +28,18 @@ const FORWARDED_REQUEST_HEADERS = [
 const FORWARDED_RESPONSE_HEADERS = ['content-type', 'cache-control', 'etag'];
 
 async function forward(request: Request): Promise<Response> {
+  const apiUrl = env.INTERNAL_API_URL;
+  if (!apiUrl) {
+    // Said here, in words, rather than as a 404 from a route that is not there.
+    return Response.json(
+      { error: 'INTERNAL_API_URL is not set, so the web role cannot reach the API role' },
+      { status: 503 },
+    );
+  }
   const incoming = new URL(request.url);
   // Rebuilt from the incoming pathname rather than from the matched segments,
   // so an encoded segment reaches the API role exactly as it arrived.
-  const target = new URL(`${incoming.pathname}${incoming.search}`, internalApiUrl());
+  const target = new URL(`${incoming.pathname}${incoming.search}`, apiUrl);
 
   const headers = new Headers();
   for (const name of FORWARDED_REQUEST_HEADERS) {

package/template/packages/frontend/src/features/board/board-live.ts

@@ -27,6 +27,10 @@ let shared: ReturnType<typeof connect> | undefined;
 function connect(realtimeOrigin?: string) {
   const realtime = createRealtimeClient(liveContract, {
     url: realtimeOrigin ?? window.location.origin,
+    // The literal loader is what puts the socket client into this bundle.
+    // Stitchkit's own import of the peer is left alone by bundlers on purpose,
+    // so without this line the browser build has no `socket.io-client` in it.
+    peers: { client: () => import('socket.io-client') },
   });
   realtime.connect();
   return {