create-stitchkit 0.3.3 → 0.4.1

package/examples/repository/_env.example.append

@@ -1,3 +1,24 @@
+# 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
+# changes nothing on its own; switching is one import in
+# packages/frontend/src/lib/api/queries.ts. See lib/api/cross-origin.ts.
+# PUBLIC_API_ORIGIN=https://api.example
+
 GITHUB_REPOSITORY=max-listov/stitchkit
 GITHUB_CACHE_TTL_SECONDS=900
 # Optional. Defaults to the public GitHub API and supports GitHub Enterprise.

package/examples/repository/packages/backend/src/domain/repository/github-cache.ts

@@ -1,5 +1,5 @@
 import { env } from '@app/config';
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { RepositoryVisibility } from '@app/db';
 import type { RepositorySnapshot } from '@app/shared';
 import { z } from 'zod';
@@ -81,7 +81,7 @@ const snapshotStore: RepositorySnapshotStore = {
 function githubHeaders(): Headers {
   const headers = new Headers({
     Accept: 'application/vnd.github+json',
-    'User-Agent': appIdentity.slug,
+    'User-Agent': appDeclaration.identity.slug,
     'X-GitHub-Api-Version': '2026-03-10',
   });
   if (env.GITHUB_TOKEN) headers.set('Authorization', `Bearer ${env.GITHUB_TOKEN}`);

package/examples/repository/packages/backend/src/surface.ts

@@ -6,7 +6,7 @@ import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
   const socket = await createSocketIOServer({
-    cors: { origin: env.CORS_ORIGIN },
+    cors: { origin: env.CORS_ORIGIN ?? [] },
   });
   const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
   const repositoryService = createRepositoryService((snapshot) =>

package/examples/repository/packages/config/src/features.ts

@@ -1,6 +1,23 @@
 import { z } from 'zod';
 
 export const featureServerSchema = {
+  // The web role dereferences this on every proxied request and on every server
+  // render, so it TIGHTENS from optional to required. Declared optional, a
+  // deployment reading project.json would supply nothing and every request would
+  // throw — the declaration would be derived and still wrong, which is the one
+  // failure the derivation exists to prevent.
+  INTERNAL_API_URL: z.url(),
+  // Deliberately NOT tightened. The browser talks to its own origin by default
+  // (`frontend/src/lib/api/client.ts`), so a single-origin deployment supplies
+  // none of these. They are the price of a browser that leaves that origin, and
+  // only a deployment that has that case should be made to pay it.
+  //   PUBLIC_REALTIME_ORIGIN — where the socket connects, when no routing layer
+  //     forwards `/socket.io`. A WebSocket upgrade cannot be proxied by the
+  //     route handler that forwards `/api`, so this one is separate on purpose.
+  //   PUBLIC_API_ORIGIN — where the browser dials the API role over HTTP, for
+  //     the cross-origin variant. Inert until the import in `queries.ts` moves.
+  //   CORS_ORIGIN — the API role's allow-list, needed once the browser is
+  //     genuinely cross-origin for either of the two.
   GITHUB_API_URL: z.url().default('https://api.github.com'),
   GITHUB_REPOSITORY: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
   GITHUB_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(900),

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

@@ -1,10 +1,10 @@
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
 import { LocaleSchema } from '@/i18n/locales';
-import { createServerRepositoryApi } from '@/lib/api/client';
 import { useRepository } from '@/lib/api/queries';
+import { createServerRepositoryApi } from '@/lib/api/server-client';
 import { getQueryClient } from '@/lib/query-client';
 import { createPageMetadata } from '@/lib/seo/metadata';
 import { StarterPage } from './starter-page';
@@ -34,8 +34,8 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
       <StarterPage
-        applicationName={appIdentity.name}
-        applicationDescription={appIdentity.description[appLocale]}
+        applicationName={appDeclaration.identity.name}
+        applicationDescription={appDeclaration.identity.description[appLocale]}
         heroTitle={t('heroTitle')}
         catalogueLabel={t('ui')}
         locale={appLocale}

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

@@ -57,7 +57,7 @@ const architecture = [
   },
 ];
 
-export function StarterPage({
+export async function StarterPage({
   applicationName,
   applicationDescription,
   heroTitle,
@@ -71,7 +71,7 @@ export function StarterPage({
     name: SITE_NAME,
     applicationCategory: 'DeveloperApplication',
     operatingSystem: 'Web',
-    url: absoluteSiteUrl(`/${locale}`),
+    url: await absoluteSiteUrl(`/${locale}`),
     description: homeSeo.description,
   };
 

package/examples/repository/packages/frontend/src/app/api/[...path]/route.ts

@@ -0,0 +1,66 @@
+import { internalApiUrl } from '@/lib/api/place';
+
+/**
+ * The default shape: the browser talks to its OWN origin, and the web role
+ * forwards to the API role.
+ *
+ * This is what makes the example'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
+ * that with a lazy accessor. A same-origin request needs no address at all:
+ * `/api/…` is complete before any machine exists.
+ *
+ * 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`).
+ */
+export const dynamic = 'force-dynamic';
+
+const FORWARDED_REQUEST_HEADERS = [
+  'accept',
+  'accept-language',
+  'content-type',
+  'authorization',
+];
+const FORWARDED_RESPONSE_HEADERS = ['content-type', 'cache-control', 'etag'];
+
+async function forward(request: Request): Promise<Response> {
+  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 headers = new Headers();
+  for (const name of FORWARDED_REQUEST_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+
+  // Buffered rather than streamed: forwarding a stream needs the non-standard
+  // `duplex` init that this project's types do not carry, and every payload
+  // this contract accepts is a small JSON document.
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  const response = await fetch(target, {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.arrayBuffer() : undefined,
+    // A redirect is the API role's answer, not something to resolve here.
+    redirect: 'manual',
+  });
+
+  const responseHeaders = new Headers();
+  for (const name of FORWARDED_RESPONSE_HEADERS) {
+    const value = response.headers.get(name);
+    if (value !== null) responseHeaders.set(name, value);
+  }
+  return new Response(response.body, { status: response.status, headers: responseHeaders });
+}
+
+export const GET = forward;
+export const POST = forward;
+export const PUT = forward;
+export const PATCH = forward;
+export const DELETE = forward;

package/examples/repository/packages/frontend/src/lib/api/client.ts

@@ -1,20 +1,25 @@
 import { repositoryContract } from '@app/shared';
 import { createClient, createHttpClient, createUrlBuilder } from 'stitchkit';
-import { env } from '@/env';
 
-function apiOrigin(): string {
-  return typeof window === 'undefined' ? env.INTERNAL_API_URL : env.NEXT_PUBLIC_API_URL;
-}
+/**
+ * The browser's API client — a module CONSTANT, because it needs no address.
+ *
+ * `/api` is complete when no machine exists: it names a path on whatever origin
+ * served the page. That is the whole reason this file has no factory, no lazy
+ * accessor and no parentheses at its call sites — see `queries.ts`. The web
+ * role forwards these requests to the API role (`app/api/[...path]/route.ts`).
+ *
+ * A browser that genuinely must reach a DIFFERENT origin cannot do this, and
+ * pays a real price for it. That variant lives in `cross-origin.ts`, named and
+ * explained, rather than in the default path everybody copies.
+ */
+const browserHttp = createHttpClient({ baseUrl: '/api', credentials: 'same-origin' });
+
+export const repositoryApi = createClient(repositoryContract, browserHttp);
+export const repositoryUrls = createUrlBuilder(repositoryContract, browserHttp);
 
+/** The server-side client needs an address, and reads it from the place. */
 export function createRepositoryApi(baseUrl: string) {
   const http = createHttpClient({ baseUrl: `${baseUrl}/api`, credentials: 'omit' });
   return createClient(repositoryContract, http);
 }
-
-const http = createHttpClient({ baseUrl: `${apiOrigin()}/api`, credentials: 'omit' });
-export const repositoryApi = createRepositoryApi(apiOrigin());
-export const repositoryUrls = createUrlBuilder(repositoryContract, http);
-
-export function createServerRepositoryApi() {
-  return createRepositoryApi(env.INTERNAL_API_URL);
-}

package/examples/repository/packages/frontend/src/lib/api/cross-origin.ts

@@ -0,0 +1,87 @@
+/**
+ * THE VARIANT: a browser that must reach the API role at a different origin.
+ *
+ * The default in this example is same-origin (`lib/api/client.ts`): the browser
+ * calls `/api/…` and the web role forwards. Two things can pull a deployment
+ * out of that, and they are separate, so they have separate variables:
+ *
+ * - **`PUBLIC_REALTIME_ORIGIN`** — the socket. A WebSocket upgrade does not
+ *   survive a proxying route handler, so a deployment running the two roles on
+ *   two ports with no routing layer in front of them must name the socket's
+ *   origin even though its HTTP is already same-origin. This one is read by the
+ *   default path, and unset means the page's own origin.
+ * - **`PUBLIC_API_ORIGIN`** — HTTP. Only for a frontend that genuinely dials
+ *   the API role itself: separate hostnames with nothing in front of them.
+ *   Setting it changes nothing on its own; switching is an import, below.
+ *
+ * Switching HTTP to this variant is one line in `queries.ts`:
+ *
+ * ```ts
+ * // before
+ * import { repositoryApi } from './client'
+ * fetcher: () => repositoryApi.read()
+ * // after
+ * import { repositoryApiCrossOrigin } from './cross-origin'
+ * fetcher: () => repositoryApiCrossOrigin().read()
+ * ```
+ *
+ * What that costs, in order:
+ *
+ * 1. **The address is a property of the place**, so it can never be compiled
+ *    in. The server reads it per request and hands it to the browser
+ *    (`providers/index.tsx` → `providers/client-providers.tsx`).
+ * 2. **Nothing can be built at import time.** The client has to be constructed
+ *    on FIRST USE — hence the parentheses, which the default path does not pay.
+ * 3. **Order matters.** Anything reading the origin must render inside
+ *    `<Providers>`; outside it, the value is not there yet.
+ * 4. **The API role needs `CORS_ORIGIN`**, for HTTP and for the realtime
+ *    handshake alike.
+ *
+ * None of that is wrong — it is the correct shape for the case. It is simply
+ * not the case most projects have, which is why it is not the body of the
+ * example.
+ */
+import { createRepositoryApi } from './client';
+
+export interface PublicOrigins {
+  /** Where the browser dials the API role over HTTP, if not this origin. */
+  readonly api: string | undefined;
+  /** Where the browser opens the realtime socket, if not this origin. */
+  readonly realtime: string | undefined;
+}
+
+let origins: PublicOrigins = { api: undefined, realtime: undefined };
+
+/** Supplied by the server, once, above every consumer. */
+export function setPublicOrigins(supplied: PublicOrigins): void {
+  origins = supplied;
+}
+
+/**
+ * The socket's origin, or `undefined` when this deployment serves both roles on
+ * one origin.
+ *
+ * `undefined` is an answer, not a missing value: the socket then connects to
+ * the page's own origin, where a routing layer forwards `/socket.io`.
+ */
+export function optionalRealtimeOrigin(): string | undefined {
+  return origins.realtime;
+}
+
+export function requirePublicApiOrigin(): string {
+  const { api } = origins;
+  if (!api) {
+    throw new Error(
+      'The public API origin has not been provided — set PUBLIC_API_ORIGIN and render this inside <Providers>, which supplies it from the server.',
+    );
+  }
+  return api;
+}
+
+let crossOriginApi: ReturnType<typeof createRepositoryApi> | undefined;
+
+/** Built on FIRST USE: the origin arrives at runtime, not at import. */
+export function repositoryApiCrossOrigin(): ReturnType<typeof createRepositoryApi> {
+  crossOriginApi ??= createRepositoryApi(requirePublicApiOrigin());
+  return crossOriginApi;
+}

package/examples/repository/packages/frontend/src/lib/api/place.ts

@@ -0,0 +1,26 @@
+import { env } from '@/env';
+
+/**
+ * The addresses this example reads from the place.
+ *
+ * `INTERNAL_API_URL` is REQUIRED — see `packages/config/src/features.ts` — and
+ * the declaration a deployment reads says so, because the web role dereferences
+ * it on every proxied request and on every server render.
+ *
+ * The two public ones are optional and independent, because the questions they
+ * answer are independent: HTTP can be forwarded by the web role, and a
+ * WebSocket upgrade cannot. A deployment behind one routing layer sets neither.
+ */
+export function internalApiUrl(): string {
+  return env.INTERNAL_API_URL;
+}
+
+/** Where the browser dials the API role over HTTP — the cross-origin variant. */
+export function publicApiOrigin(): string | undefined {
+  return env.PUBLIC_API_ORIGIN;
+}
+
+/** Where the browser opens the realtime socket, when it is not this origin. */
+export function publicRealtimeOrigin(): string | undefined {
+  return env.PUBLIC_REALTIME_ORIGIN;
+}

package/examples/repository/packages/frontend/src/lib/api/queries.ts

@@ -1,6 +1,9 @@
 import { createMutation, createQuery } from 'react-query-kit';
 import { repositoryApi } from './client';
 
+// No parentheses: the client is a module constant, because a same-origin path
+// needs no address. The cross-origin variant pays for its address with a lazy
+// accessor — see `cross-origin.ts`.
 export const useRepository = createQuery({
   queryKey: ['repository'],
   fetcher: () => repositoryApi.read(),

package/examples/repository/packages/frontend/src/lib/api/server-client.ts

@@ -0,0 +1,11 @@
+import { createRepositoryApi } from './client';
+import { internalApiUrl } from './place';
+
+/**
+ * Server-side API client. Separate module on purpose: it reads the SERVER
+ * environment, and importing that from a module the browser bundle also pulls
+ * in would drag server configuration into the client graph.
+ */
+export function createServerRepositoryApi() {
+  return createRepositoryApi(internalApiUrl());
+}

package/examples/repository/packages/frontend/src/lib/realtime/repository.ts

@@ -1,20 +1,52 @@
 import { repositoryRealtimeContract } from '@app/shared';
 import { createRealtimeClient } from 'stitchkit';
 import { createCacheBridge } from 'stitchkit/react';
-import { env } from '@/env';
+import { optionalRealtimeOrigin } from '@/lib/api/cross-origin';
 import { useRepository } from '@/lib/api/queries';
 import { getQueryClient } from '@/lib/query-client';
 
-export const repositorySocket = createRealtimeClient(repositoryRealtimeContract, {
-  url: env.NEXT_PUBLIC_API_URL,
-});
+/**
+ * The one thing a route handler cannot proxy.
+ *
+ * A WebSocket upgrade does not survive a Next route handler, which is why this
+ * has a variable of its own — `PUBLIC_REALTIME_ORIGIN` — rather than sharing
+ * the HTTP one. A deployment can be same-origin for HTTP and still have to name
+ * the socket's address: two roles on two ports with no routing layer in front
+ * of them is exactly that. Unset picks the page's own origin, where a routing
+ * layer forwards `/socket.io`.
+ */
+function buildSocket() {
+  // `window.location.origin` is not a value baked in anywhere: it is what this
+  // browser actually dialled, read at connect time, exactly like the server
+  // reads the request's origin. This function only ever runs in an effect.
+  const url = optionalRealtimeOrigin() ?? window.location.origin;
+  return createRealtimeClient(repositoryRealtimeContract, { url });
+}
 
-export const repositoryBridge = createCacheBridge({
-  socket: repositorySocket,
-  queryClient: getQueryClient,
-  handlers: {
-    'repository:refreshed': (snapshot, { queryClient }) => {
-      queryClient.setQueryData(useRepository.getKey(), snapshot);
+function buildBridge() {
+  return createCacheBridge({
+    socket: repositorySocket(),
+    queryClient: getQueryClient,
+    handlers: {
+      'repository:refreshed': (snapshot, { queryClient }) => {
+        queryClient.setQueryData(useRepository.getKey(), snapshot);
+      },
     },
-  },
-});
+  });
+}
+
+// Built on FIRST USE: the socket needs whatever origin the server supplied,
+// and that arrives at runtime rather than from the build. See
+// `lib/api/cross-origin.ts`.
+let socket: ReturnType<typeof buildSocket> | undefined;
+let bridge: ReturnType<typeof buildBridge> | undefined;
+
+export function repositorySocket(): ReturnType<typeof buildSocket> {
+  socket ??= buildSocket();
+  return socket;
+}
+
+export function repositoryBridge(): ReturnType<typeof buildBridge> {
+  bridge ??= buildBridge();
+  return bridge;
+}

package/examples/repository/packages/frontend/src/providers/client-providers.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { TooltipProvider } from '@radix-ui/react-tooltip';
+import type { ReactNode } from 'react';
+import { Toaster } from '@/components/ui/toaster';
+import { type PublicOrigins, setPublicOrigins } from '@/lib/api/cross-origin';
+import { ReactQueryProvider } from './react-query';
+import { RealtimeProvider } from './realtime';
+
+export function ClientProviders({
+  origins,
+  children,
+}: {
+  origins: PublicOrigins;
+  children: ReactNode;
+}) {
+  // Recorded before any child renders, so the realtime socket can be built
+  // lazily on first use. Idempotent: the same values every render. `undefined`
+  // means this deployment serves both roles on one origin.
+  setPublicOrigins(origins);
+
+  return (
+    <ReactQueryProvider>
+      <RealtimeProvider>
+        <TooltipProvider delayDuration={250}>{children}</TooltipProvider>
+      </RealtimeProvider>
+      <Toaster />
+    </ReactQueryProvider>
+  );
+}

package/examples/repository/packages/frontend/src/providers/index.tsx

@@ -1,18 +1,23 @@
-'use client';
-
-import { TooltipProvider } from '@radix-ui/react-tooltip';
 import type { ReactNode } from 'react';
-import { Toaster } from '@/components/ui/toaster';
-import { ReactQueryProvider } from './react-query';
-import { RealtimeProvider } from './realtime';
+import { publicApiOrigin, publicRealtimeOrigin } from '@/lib/api/place';
+import { ClientProviders } from './client-providers';
 
+/**
+ * A SERVER component on purpose.
+ *
+ * The browser's data calls are same-origin and need no address at all. What
+ * still can is the realtime socket, which no route handler can proxy: when this
+ * deployment runs the two roles on two origins, the socket's address is read
+ * HERE, per request, and handed down. Reading it at request time rather than at
+ * build time is what lets one artifact serve every address it is routed to; a
+ * `NEXT_PUBLIC_` variable would have frozen one into the bundle.
+ *
+ * `undefined` for both is the normal answer for a single-origin deployment.
+ */
 export function Providers({ children }: { children: ReactNode }) {
   return (
-    <ReactQueryProvider>
-      <RealtimeProvider>
-        <TooltipProvider delayDuration={250}>{children}</TooltipProvider>
-      </RealtimeProvider>
-      <Toaster />
-    </ReactQueryProvider>
+    <ClientProviders origins={{ api: publicApiOrigin(), realtime: publicRealtimeOrigin() }}>
+      {children}
+    </ClientProviders>
   );
 }

package/examples/repository/packages/frontend/src/providers/realtime.tsx

@@ -5,11 +5,13 @@ import { repositoryBridge, repositorySocket } from '@/lib/realtime/repository';
 
 export function RealtimeProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
-    repositorySocket.connect();
-    repositoryBridge.connect();
+    const socket = repositorySocket();
+    const bridge = repositoryBridge();
+    socket.connect();
+    bridge.connect();
     return () => {
-      repositoryBridge.disconnect();
-      repositorySocket.disconnect();
+      bridge.disconnect();
+      socket.disconnect();
     };
   }, []);
   return children;