create-stitchkit 0.2.0 → 0.3.0

package/template/e2e/starter.spec.ts

@@ -1,6 +1,11 @@
 import { appIdentity } from '@app/config/identity';
+import { systemContract } from '@app/shared';
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
+import { createClient, createHttpClient } from 'stitchkit';
+import { loadToolingEnv } from '../scripts/tooling-env';
+
+const toolingEnv = loadToolingEnv();
 
 test('renders the hydrated starter application and catalogue', async ({ page }) => {
   await page.goto('/en');
@@ -12,6 +17,18 @@ test('renders the hydrated starter application and catalogue', async ({ page })
   await expect(page.getByRole('heading', { level: 1 })).toContainText('UI components');
 });
 
+test('calls the live backend through the typed contract client', async () => {
+  const client = createClient(
+    systemContract,
+    createHttpClient({
+      baseUrl: `${toolingEnv.NEXT_PUBLIC_API_URL}/api`,
+      credentials: 'omit',
+    }),
+  );
+
+  await expect(client.status()).resolves.toEqual({ status: 'ok' });
+});
+
 test('publishes complete page metadata and a reachable Open Graph card', async ({
   page,
   request,

package/template/ecosystem.dev.config.cjs

@@ -5,18 +5,6 @@ const identity = require('./app.config.json');
 config({ path: path.join(__dirname, '.env'), quiet: true });
 
 const frontendArgs = ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'];
-if (process.env.DEV_HTTPS_CERT && process.env.DEV_HTTPS_KEY) {
-  frontendArgs.push(
-    '--experimental-https',
-    '--experimental-https-key',
-    process.env.DEV_HTTPS_KEY,
-    '--experimental-https-cert',
-    process.env.DEV_HTTPS_CERT,
-  );
-  if (process.env.DEV_HTTPS_CA) {
-    frontendArgs.push('--experimental-https-ca', process.env.DEV_HTTPS_CA);
-  }
-}
 
 module.exports = {
   apps: [

package/template/package.json

@@ -7,12 +7,11 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.45.0"
+    "stitchkit": "^0.46.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
-    "dev:lan": "bun scripts/dev-lan.ts",
-    "check": "bun run db:generate && bun run check:authored && bun run --filter '*' check",
+    "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
     "test": "bun run --filter '*' test",
     "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
@@ -27,6 +26,7 @@
     "cli": "bun packages/backend/src/cli.ts",
     "tools": "bun packages/backend/src/tools.ts",
     "runtime:smoke": "bun scripts/runtime-smoke.ts",
+    "surface:snapshot": "bun scripts/surface-snapshot.ts",
     "e2e": "playwright test",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
@@ -44,8 +44,10 @@
     "@modelcontextprotocol/client": "^2.0.0",
     "@playwright/test": "^1.55.0",
     "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
     "oxc-parser": "^0.143.0",
     "socket.io-client": "^4.8.3",
+    "stitchkit": "catalog:",
     "typescript": "^7.0.2",
     "zod": "^4.4.3"
   },

package/template/packages/backend/src/index.ts

@@ -6,7 +6,6 @@ import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
 import { prisma } from './lib/db';
 import { createSurface } from './surface';
 import { onError } from './transport/errors';
-import { createLanOnboardingRoutes } from './transport/lan-onboarding';
 
 async function main(): Promise<void> {
   const { services, socket } = await createSurface();
@@ -32,7 +31,6 @@ async function main(): Promise<void> {
       socket.route,
       openApiRoute('/openapi.json', openApi),
       createMcpHttpRoute({ path: '/mcp', handler: mcp }),
-      ...createLanOnboardingRoutes(),
       {
         method: 'GET',
         path: '/health',
@@ -40,16 +38,6 @@ async function main(): Promise<void> {
       },
     ],
     wrapFetch: (fetch) => wrapInRequestContext(fetch),
-    bun:
-      env.DEV_HTTPS_CERT && env.DEV_HTTPS_KEY
-        ? {
-            tls: {
-              cert: Bun.file(env.DEV_HTTPS_CERT),
-              key: Bun.file(env.DEV_HTTPS_KEY),
-              ...(env.DEV_HTTPS_CA && { ca: Bun.file(env.DEV_HTTPS_CA) }),
-            },
-          }
-        : undefined,
   });
 
   async function shutdown(): Promise<void> {
@@ -61,9 +49,7 @@ async function main(): Promise<void> {
 
   process.once('SIGTERM', shutdown);
   process.once('SIGINT', shutdown);
-  console.log(
-    `API listening on ${env.DEV_HTTPS_CERT ? 'https' : 'http'}://127.0.0.1:${env.API_PORT}`,
-  );
+  console.log(`API listening on http://127.0.0.1:${env.API_PORT}`);
 }
 
 main().catch((error: unknown) => {

package/template/packages/backend/src/surface-manifest.test.ts

@@ -1,19 +1,35 @@
 import { describe, expect, test } from 'bun:test';
-import { defineContract } from 'stitchkit/contract';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createContractFactory } from 'stitchkit/contract';
 import { generateOpenApiDocument, implement } from 'stitchkit/server';
 import { z } from 'zod';
-import { assertSurfaceConformance, buildSurfaceManifest } from './surface-manifest';
+import { discoverCliCommands, discoverMcpTools } from '../../../scripts/surface-conformance';
+import {
+  assertManifestMatchesSnapshot,
+  assertSurfaceConformance,
+  buildSurfaceManifest,
+} from './surface-manifest';
+
+const NoteParamsSchema = z.object({ id: z.string() });
+const NoteSchema = z.object({ id: z.string() });
+// Same address and presence flags as NoteSchema — a different TYPE, for the
+// snapshot-digest test. Named here, never inline in a contract (the template's
+// own schema-separate-from-contract policy).
+const RetypedNoteSchema = z.object({ id: z.number() });
+const { defineContract } = createContractFactory<'public'>();
 
 const service = implement(
   defineContract(
-    { prefix: 'notes' },
+    { prefix: 'notes', scope: 'public' },
     {
       read: {
         method: 'GET',
         path: '/:id',
         desc: 'Read a note',
-        params: z.object({ id: z.string() }),
-        output: z.object({ id: z.string() }),
+        params: NoteParamsSchema,
+        output: NoteSchema,
+        expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
       },
     },
   ),
@@ -31,32 +47,191 @@ describe('surface conformance', () => {
       {
         service: 'notes',
         action: 'read',
+        scope: 'public',
+        hasInput: false,
+        hasOutput: true,
+        inputShape: null,
+        outputShape: expect.stringMatching(/^[0-9a-f]{16}$/),
         http: [{ method: 'GET', path: '/api/notes/{id}' }],
-        tools: { AGENT: 'read_note', MCP: 'read_note' },
+        tools: { AGENT: 'read_note', CLI: 'read_note', MCP: 'read_note' },
       },
     ]);
     expect(() =>
-      assertSurfaceConformance({ manifest, openApi, mcpToolNames: ['read_note'] }),
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
+      }),
     ).not.toThrow();
   });
 
   test('fails with transport-specific expected and actual diagnostics', () => {
     const manifest = buildSurfaceManifest([service]);
     expect(() =>
-      assertSurfaceConformance({ manifest, openApi: { paths: {} }, mcpToolNames: [] }),
+      assertSurfaceConformance({
+        manifest,
+        openApi: { paths: {} },
+        mcpToolNames: [],
+        agentToolNames: [],
+        cliToolNames: [],
+      }),
     ).toThrow('HTTP/OpenAPI surface mismatch');
     expect(() =>
       assertSurfaceConformance({
         manifest: manifest.map((operation) => ({ ...operation, http: [] })),
         openApi: { paths: {} },
         mcpToolNames: ['unexpected'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
       }),
     ).toThrow('MCP discovery surface mismatch');
   });
 
+  test('missing Stitchkit metadata is an ERROR unless the standard-document mode is declared', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const standardDocument = {
+      paths: {
+        '/api/notes/{id}': {
+          get: { responses: { 200: { description: 'Success' } } },
+        },
+      },
+    };
+    const names = {
+      mcpToolNames: ['read_note'],
+      agentToolNames: ['read_note'],
+      cliToolNames: ['read_note'],
+    };
+    // A silent skip was the hole: no x-stitchkit-* keys meant no comparison at
+    // all. The default mode now refuses; opting out is an explicit decision.
+    expect(() =>
+      assertSurfaceConformance({ manifest, openApi: standardDocument, ...names }),
+    ).toThrow(/no x-stitchkit-\* contract metadata/);
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi: standardDocument,
+        ...names,
+        metadata: 'ignore',
+      }),
+    ).not.toThrow();
+  });
+
+  test('a missing AGENT tool and a missing CLI command each fail conformance', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const openApi = generateOpenApiDocument({
+      info: { title: 'Test', version: '1.0.0' },
+      groups: [{ pathPrefix: '/api', services: [service] }],
+    });
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: [],
+        cliToolNames: ['read_note'],
+      }),
+    ).toThrow('AGENT mount surface mismatch');
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: [],
+      }),
+    ).toThrow('CLI manifest surface mismatch');
+  });
+
+  test('the committed snapshot catches an expose edit that moves BOTH in-process sides together', () => {
+    // The probe that defeated the old check: removing AGENT/CLI from `expose`
+    // changes the manifest AND the in-process tool lists in lockstep. The
+    // snapshot is the anchor that does not move with the source.
+    const snapshot = buildSurfaceManifest([service]);
+    const narrowed = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            output: NoteSchema,
+            expose: ['HTTP', 'MCP'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: params.id }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([narrowed]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([service]), snapshot),
+    ).not.toThrow();
+  });
+
+  test('a schema TYPE change at the same method and path flips the shape digest', () => {
+    const snapshot = buildSurfaceManifest([service]);
+    const retyped = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            // Same address, same presence flags — different output TYPE.
+            output: RetypedNoteSchema,
+            expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: Number(params.id) }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([retyped]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+  });
+
   test('fails first on duplicate contract identity', () => {
     expect(() => buildSurfaceManifest([service, service])).toThrow(
       'Duplicate operation identity notes.read',
     );
   });
+
+  test('a broken /mcp endpoint rejects discovery — even when zero tools are expected', async () => {
+    const broken = Bun.serve({
+      port: 0,
+      fetch: () => new Response('not the MCP endpoint', { status: 404 }),
+    });
+    try {
+      await expect(discoverMcpTools(`http://127.0.0.1:${broken.port}`, [])).rejects.toThrow();
+    } finally {
+      broken.stop(true);
+    }
+  });
+
+  test('the CLI surface observed from the SPAWNED process matches the committed snapshot', async () => {
+    // External observation against the external anchor — neither side is the
+    // in-process `services` object, so they cannot move together.
+    const root = join(import.meta.dir, '../../..');
+    const commands = await discoverCliCommands(root);
+    const snapshot = SurfaceSnapshotCliSchema.parse(
+      JSON.parse(
+        await readFile(join(root, 'packages/backend/src/surface.snapshot.json'), 'utf8'),
+      ),
+    );
+    const expected = snapshot
+      .flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : []))
+      .sort();
+    expect([...commands].sort()).toEqual(expected);
+  });
 });
+
+const SurfaceSnapshotCliSchema = z.array(
+  z.object({ tools: z.object({ CLI: z.string().optional() }) }),
+);

package/template/packages/backend/src/surface-manifest.ts

@@ -1,14 +1,29 @@
+import { createHash } from 'node:crypto';
 import type { HttpMethod } from 'stitchkit/contract';
 import type { OpenApiDocument, ServiceDef } from 'stitchkit/server';
 import { listToolNames } from 'stitchkit/tools';
+import { z } from 'zod';
 
 export interface SurfaceManifestOperation {
   service: string;
   action: string;
+  scope: string;
+  hasInput: boolean;
+  hasOutput: boolean;
+  /** Digest of the input JSON Schema — a TYPE change flips it, not just presence. */
+  inputShape: string | null;
+  /** Digest of the output JSON Schema. */
+  outputShape: string | null;
   http: Array<{ method: HttpMethod; path: string }>;
   tools: Partial<Record<'MCP' | 'AGENT' | 'CLI', string>>;
 }
 
+function schemaShape(schema: z.ZodType | undefined, io: 'input' | 'output'): string | null {
+  if (!schema) return null;
+  const document = z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+  return createHash('sha256').update(JSON.stringify(document)).digest('hex').slice(0, 16);
+}
+
 function joinPath(...parts: Array<string | undefined>): string {
   const joined = parts
     .filter((part): part is string => Boolean(part))
@@ -58,6 +73,11 @@ export function buildSurfaceManifest(
       operations.set(key, {
         service: service.name,
         action: method.key,
+        scope: method.scope ?? service.scope,
+        hasInput: Boolean(method.inputSchema),
+        hasOutput: Boolean(method.outputSchema),
+        inputShape: schemaShape(method.inputSchema, 'input'),
+        outputShape: schemaShape(method.outputSchema, 'output'),
         http:
           !method.expose || method.expose.includes('HTTP')
             ? [
@@ -89,29 +109,112 @@ export function buildSurfaceManifest(
   );
 }
 
+/**
+ * Compare the LIVE manifest against the committed snapshot — the external
+ * anchor that a source-level change (an `expose` edit, a schema type change, a
+ * scope change) cannot move along with itself. Regenerate deliberately with
+ * `bun run surface:snapshot` and review the diff.
+ */
+export function assertManifestMatchesSnapshot(
+  manifest: readonly SurfaceManifestOperation[],
+  snapshot: readonly SurfaceManifestOperation[],
+): void {
+  const actual = JSON.stringify(manifest, null, 2);
+  const expected = JSON.stringify(snapshot, null, 2);
+  if (actual !== expected) {
+    throw new Error(
+      `Declared surface diverged from the committed snapshot — if the change is intended, regenerate it with "bun run surface:snapshot" and review the diff.\nsnapshot: ${expected}\nactual: ${actual}`,
+    );
+  }
+}
+
 export function assertSurfaceConformance({
   manifest,
   openApi,
   mcpToolNames,
+  agentToolNames,
+  cliToolNames,
+  metadata = 'require',
 }: {
   manifest: readonly SurfaceManifestOperation[];
   openApi: Pick<OpenApiDocument, 'paths'>;
   mcpToolNames: readonly string[];
+  agentToolNames: readonly string[];
+  cliToolNames: readonly string[];
+  /**
+   * `'require'` (default) — the OpenAPI document must carry `x-stitchkit-*`
+   * metadata and it is compared; `'ignore'` — an explicitly declared mode for
+   * standard documents. A silent skip is not an option.
+   */
+  metadata?: 'require' | 'ignore';
 }): void {
+  const openApiOperations = Object.entries(openApi.paths).flatMap(([path, item]) =>
+    Object.entries(item)
+      .filter(([method]) => ['get', 'post', 'put', 'patch', 'delete', 'head'].includes(method))
+      .map(([method, operation]) => ({ method: method.toUpperCase(), path, operation })),
+  );
   assertSameSet(
     'HTTP/OpenAPI',
     manifest.flatMap((operation) =>
       operation.http.map((entry) => `${entry.method}:${entry.path}`),
     ),
-    Object.entries(openApi.paths).flatMap(([path, item]) =>
-      Object.keys(item)
-        .filter((method) => ['get', 'post', 'put', 'patch', 'delete', 'head'].includes(method))
-        .map((method) => `${method.toUpperCase()}:${path}`),
-    ),
+    openApiOperations.map(({ method, path }) => `${method}:${path}`),
   );
+  const carriesContractMetadata = openApiOperations.some(({ operation }) =>
+    OpenApiOperationMetadataPresenceSchema.parse(operation),
+  );
+  if (metadata === 'require' && openApiOperations.length > 0 && !carriesContractMetadata) {
+    throw new Error(
+      'OpenAPI document carries no x-stitchkit-* contract metadata — pass metadata: "ignore" only for a deliberately standard document',
+    );
+  }
+  if (metadata === 'require' && carriesContractMetadata) {
+    assertSameSet(
+      'HTTP/OpenAPI contract metadata',
+      manifest.flatMap((operation) =>
+        operation.http.map(
+          (entry) =>
+            `${entry.method}:${entry.path}:${operation.scope}:${operation.hasInput}:${operation.hasOutput}`,
+        ),
+      ),
+      openApiOperations.map(({ method, path, operation }) => {
+        const metadata = OpenApiOperationMetadataSchema.parse(operation);
+        return `${method}:${path}:${metadata['x-stitchkit-scope']}:${metadata['x-stitchkit-has-input']}:${metadata['x-stitchkit-has-output']}`;
+      }),
+    );
+  }
   assertSameSet(
     'MCP discovery',
     manifest.flatMap((operation) => (operation.tools.MCP ? [operation.tools.MCP] : [])),
     mcpToolNames,
   );
+  assertSameSet(
+    'AGENT mount',
+    manifest.flatMap((operation) => (operation.tools.AGENT ? [operation.tools.AGENT] : [])),
+    agentToolNames,
+  );
+  assertSameSet(
+    'CLI manifest',
+    manifest.flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : [])),
+    cliToolNames,
+  );
 }
+
+const OpenApiOperationMetadataSchema = z.object({
+  'x-stitchkit-scope': z.string(),
+  'x-stitchkit-has-input': z.boolean(),
+  'x-stitchkit-has-output': z.boolean(),
+});
+
+const OpenApiOperationMetadataPresenceSchema = z
+  .object({
+    'x-stitchkit-scope': z.unknown().optional(),
+    'x-stitchkit-has-input': z.unknown().optional(),
+    'x-stitchkit-has-output': z.unknown().optional(),
+  })
+  .transform(
+    (metadata) =>
+      metadata['x-stitchkit-scope'] !== undefined ||
+      metadata['x-stitchkit-has-input'] !== undefined ||
+      metadata['x-stitchkit-has-output'] !== undefined,
+  );

package/template/packages/backend/src/surface.snapshot.json

@@ -0,0 +1,18 @@
+[
+  {
+    "service": "system",
+    "action": "status",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "58b078ade3ee6167",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/system/status"
+      }
+    ],
+    "tools": {}
+  }
+]

package/template/packages/backend/src/surface.ts

@@ -1,7 +1,8 @@
 import { env } from '@app/config';
 import { createSocketIOServer } from 'stitchkit/server';
+import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
   const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN } });
-  return { socket, services: [] };
+  return { socket, services: [createSystemService()] };
 }

package/template/packages/backend/src/tools.ts

@@ -5,11 +5,14 @@ const { services, socket } = await createSurface();
 
 try {
   const surface = { services };
+  const toolNames = listToolNames(surface)
+    .filter((tool) => tool.transports.some((transport) => transport !== 'HTTP'))
+    .map((tool) => tool.name);
   console.log(
     JSON.stringify(
       {
         manifest: buildToolManifest({ services, transport: 'AGENT' }),
-        names: listToolNames(surface),
+        names: toolNames,
         transports: summarizeTransports(surface),
       },
       null,

package/template/packages/backend/src/transport/errors.ts

@@ -11,6 +11,7 @@ const codeMap: Record<StitchErrorCode, string> = {
   CONFLICT: 'conflict',
   RATE_LIMITED: 'rate_limited',
   INTERNAL_SERVER_ERROR: 'internal_error',
+  REALTIME_CONTRACT_VIOLATION: 'internal_error',
 };
 
 export const onError = createErrorHook({

package/template/packages/backend/src/transport/system-service.ts

@@ -0,0 +1,8 @@
+import { type SystemStatus, systemContract } from '@app/shared';
+import { implement } from 'stitchkit/server';
+
+export function createSystemService() {
+  return implement(systemContract, {
+    status: (): SystemStatus => ({ status: 'ok' }),
+  });
+}

package/template/packages/config/src/server.ts

@@ -16,10 +16,7 @@ export const env = createEnv({
     INTERNAL_API_URL: z.url(),
     NEXT_PUBLIC_WEB_URL: z.url(),
     LOG_FORMAT: z.enum(['pretty', 'json']).default('pretty'),
-    CORS_ORIGIN: z.string().min(1).default('*'),
-    DEV_HTTPS_CERT: z.string().min(1).optional(),
-    DEV_HTTPS_KEY: z.string().min(1).optional(),
-    DEV_HTTPS_CA: z.string().min(1).optional(),
+    CORS_ORIGIN: z.url(),
     ...featureServerSchema,
   },
   runtimeEnv: process.env,

package/template/packages/frontend/package.json

@@ -12,7 +12,6 @@
   },
   "dependencies": {
     "@app/config": "workspace:*",
-    "@app/db": "workspace:*",
     "@app/shared": "workspace:*",
     "@radix-ui/react-alert-dialog": "^1.1.23",
     "@radix-ui/react-avatar": "^1.2.6",

package/template/packages/frontend/src/lib/query-client.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'bun:test';
+import { getQueryClient } from './query-client';
+
+describe('query dehydration policy', () => {
+  test('includes successful prefetched data and pending streamed queries', () => {
+    const queryClient = getQueryClient();
+    queryClient.setQueryData(['prefetched-project'], { id: 'project-1' });
+    void queryClient.prefetchQuery({
+      queryKey: ['pending-project'],
+      queryFn: () => new Promise(() => undefined),
+    });
+
+    const shouldDehydrate = queryClient.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
+    if (!shouldDehydrate) throw new Error('dehydration policy is required');
+    const successful = queryClient.getQueryCache().find({ queryKey: ['prefetched-project'] });
+    const pending = queryClient.getQueryCache().find({ queryKey: ['pending-project'] });
+    if (!successful || !pending) throw new Error('test queries were not created');
+
+    expect(shouldDehydrate(successful)).toBe(true);
+    expect(shouldDehydrate(pending)).toBe(true);
+  });
+});

package/template/packages/frontend/src/lib/query-client.ts

@@ -1,11 +1,19 @@
-import { isServer, QueryClient } from '@tanstack/react-query';
+import { defaultShouldDehydrateQuery, isServer, QueryClient } from '@tanstack/react-query';
 import { cache } from 'react';
 
 function createQueryClient(): QueryClient {
   return new QueryClient({
     defaultOptions: {
       queries: { staleTime: 30_000, retry: 1 },
-      dehydrate: { shouldDehydrateQuery: (query) => query.state.status === 'pending' },
+      dehydrate: {
+        // `pending` queries dehydrate too: a server component may kick off a
+        // prefetch without awaiting it, and streaming SSR hands the in-flight
+        // promise to the client, which resumes it instead of refetching. The
+        // default predicate would drop exactly those queries and reintroduce
+        // the client-side loading flash.
+        shouldDehydrateQuery: (query) =>
+          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
+      },
     },
   });
 }

package/template/packages/frontend/tsconfig.json

@@ -8,6 +8,12 @@
     "plugins": [{ "name": "next" }],
     "paths": { "@/*": ["./src/*"] }
   },
-  "include": ["next-env.d.ts", "src/**/*.ts", "src/**/*.tsx", ".next/types/**/*.ts"],
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
   "exclude": ["node_modules"]
 }