feat: rename createProxySSGHelpers to createServerSideHelpers (#4079

)



Co-authored-by: KATT <alexander@n1s.se>

examples/.test/ssg/src/pages/index.tsx

@@ -1,4 +1,4 @@
-import { createProxySSGHelpers } from '@trpc/react-query/ssg';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import superjson from 'superjson';
 import { appRouter } from '~/server/routers/_app';
 import { trpc } from '~/utils/trpc';
@@ -8,7 +8,7 @@ import { trpc } from '~/utils/trpc';
  * @link https://trpc.io/docs/ssg
  */
 export const getStaticProps = async () => {
-  const ssg = createProxySSGHelpers({
+  const ssg = createServerSideHelpers({
     router: appRouter,
     ctx: {},
     transformer: superjson,

examples/next-prisma-starter/src/pages/index.tsx

@@ -140,7 +140,7 @@ export default IndexPage;
 // export const getStaticProps = async (
 //   context: GetStaticPropsContext<{ filter: string }>,
 // ) => {
-//   const ssg = createProxySSGHelpers({
+//   const ssg = createServerSideHelpers({
 //     router: appRouter,
 //     ctx: await createContext(),
 //   });

examples/next-prisma-todomvc/src/pages/[filter].tsx

@@ -1,6 +1,6 @@
 import { useIsMutating } from '@tanstack/react-query';
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
-import { createProxySSGHelpers } from '@trpc/react-query/ssg';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { inferProcedureOutput } from '@trpc/server';
 import clsx from 'clsx';
 import {
@@ -369,7 +369,7 @@ export const getStaticPaths: GetStaticPaths = async () => {
 export const getStaticProps = async (
   context: GetStaticPropsContext<{ filter: string }>,
 ) => {
-  const ssg = createProxySSGHelpers({
+  const ssg = createServerSideHelpers({
     router: appRouter,
     transformer: superjson,
     ctx: await createContext(),

packages/react-query/package.json

@@ -27,24 +27,30 @@
       "require": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./ssg": {
-      "import": "./dist/ssg/index.mjs",
-      "require": "./dist/ssg/index.js",
-      "default": "./dist/ssg/index.js"
+    "./server": {
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
     },
     "./shared": {
       "import": "./dist/shared/index.mjs",
       "require": "./dist/shared/index.js",
       "default": "./dist/shared/index.js"
+    },
+    "./ssg": {
+      "import": "./dist/ssg/index.mjs",
+      "require": "./dist/ssg/index.js",
+      "default": "./dist/ssg/index.js"
     }
   },
   "files": [
     "dist",
     "src",
     "README.md",
     "package.json",
-    "ssg",
-    "shared"
+    "server",
+    "shared",
+    "ssg"
   ],
   "eslintConfig": {
     "rules": {

packages/react-query/rollup.config.ts

@@ -3,8 +3,12 @@ import { buildConfig } from '../../scripts/getRollupConfig';
 
 export const input = [
   'src/index.ts',
-  'src/ssg/index.ts',
+  'src/server/index.ts',
   'src/shared/index.ts',
+  /**
+   * @deprecated
+   */
+  'src/ssg/index.ts',
 ];
 
 export default function rollup(): RollupOptions[] {

packages/react-query/src/server/index.ts

@@ -0,0 +1,4 @@
+export { createServerSideHelpers } from './ssgProxy';
+export type { CreateSSGHelpersOptions } from './types';
+
+export type { DecoratedProcedureSSGRecord } from './ssgProxy';

packages/react-query/src/ssg/ssgProxy.ts → packages/react-query/src/server/ssgProxy.ts

@@ -17,7 +17,8 @@ import {
   createRecursiveProxy,
   inferTransformedProcedureOutput,
 } from '@trpc/server/shared';
-import { CreateSSGHelpersOptions, createSSGHelpers } from './ssg';
+import { createSSGHelpers } from '../ssg/ssg';
+import { CreateSSGHelpersOptions } from './types';
 
 type DecorateProcedure<TProcedure extends AnyProcedure> = {
   /**
@@ -63,20 +64,20 @@ type AnyDecoratedProcedure = DecorateProcedure<any>;
 /**
  * Create functions you can use for server-side rendering / static generation
  */
-export function createProxySSGHelpers<TRouter extends AnyRouter>(
+export function createServerSideHelpers<TRouter extends AnyRouter>(
   opts: CreateSSGHelpersOptions<TRouter>,
 ) {
   const helpers = createSSGHelpers(opts);
 
-  type CreateProxySSGHelpers = ProtectedIntersection<
+  type CreateServerSideHelpers = ProtectedIntersection<
     {
       queryClient: QueryClient;
       dehydrate: (opts?: DehydrateOptions) => DehydratedState;
     },
     DecoratedProcedureSSGRecord<TRouter>
   >;
 
-  return createFlatProxy<CreateProxySSGHelpers>((key) => {
+  return createFlatProxy<CreateServerSideHelpers>((key) => {
     if (key === 'queryClient') {
       return helpers.queryClient;
     }

packages/react-query/src/server/types.ts

@@ -0,0 +1,14 @@
+import {
+  AnyRouter,
+  ClientDataTransformerOptions,
+  inferRouterContext,
+} from '@trpc/server';
+import { CreateTRPCReactQueryClientConfig } from '../shared';
+
+interface CreateSSGHelpersOptionsBase<TRouter extends AnyRouter> {
+  router: TRouter;
+  ctx: inferRouterContext<TRouter>;
+  transformer?: ClientDataTransformerOptions;
+}
+export type CreateSSGHelpersOptions<TRouter extends AnyRouter> =
+  CreateSSGHelpersOptionsBase<TRouter> & CreateTRPCReactQueryClientConfig;

packages/react-query/src/ssg/index.tsx

@@ -0,0 +1,16 @@
+export {
+  /**
+   * @deprecated use `@trpc/react/server` instead
+   */
+  type CreateSSGHelpersOptions,
+  /**
+   * @deprecated use `@trpc/react/server` instead
+   */
+  type DecoratedProcedureSSGRecord,
+  /**
+   * @deprecated use `import { createServerSideHelpers } from "@trpc/react/server"`;
+   */
+  createServerSideHelpers as createProxySSGHelpers,
+} from '../server';
+
+export { createSSGHelpers } from './ssg';

packages/react-query/src/ssg/ssg.ts

@@ -6,26 +6,17 @@ import {
 } from '@tanstack/react-query';
 import {
   AnyRouter,
-  ClientDataTransformerOptions,
   callProcedure,
   inferHandlerInput,
   inferProcedureOutput,
-  inferRouterContext,
 } from '@trpc/server';
 import { getArrayQueryKey } from '../internals/getArrayQueryKey';
-import { CreateTRPCReactQueryClientConfig, getQueryClient } from '../shared';
-
-interface CreateSSGHelpersOptionsBase<TRouter extends AnyRouter> {
-  router: TRouter;
-  ctx: inferRouterContext<TRouter>;
-  transformer?: ClientDataTransformerOptions;
-}
-export type CreateSSGHelpersOptions<TRouter extends AnyRouter> =
-  CreateSSGHelpersOptionsBase<TRouter> & CreateTRPCReactQueryClientConfig;
+import { CreateSSGHelpersOptions } from '../server/types';
+import { getQueryClient } from '../shared';
 
 /**
  * Create functions you can use for server-side rendering / static generation
- * @deprecated use `createProxySSGHelpers` instead
+ * @deprecated use `createServerSideHelpers` instead
  */
 export function createSSGHelpers<TRouter extends AnyRouter>(
   opts: CreateSSGHelpersOptions<TRouter>,

packages/tests/server/___packages.ts

@@ -10,6 +10,8 @@ vi.mock('@trpc/client', () => mock_trpcClient);
 
 import * as mock_trpcReact from '../../react-query/src';
 vi.mock('@trpc/react-query', () => mock_trpcReact);
+import * as mock_trpcReact__server from '../../react-query/src/server';
+vi.mock('@trpc/react-query/server', () => mock_trpcReact__server);
 import * as mock_trpcReact__ssg from '../../react-query/src/ssg';
 vi.mock('@trpc/react-query/ssg', () => mock_trpcReact__ssg);
 import * as mock_trpcReact__shared from '../../react-query/src/shared';
@@ -18,4 +20,10 @@ vi.mock('@trpc/react-query/shared', () => mock_trpcReact__shared);
 import * as mock_trpcNext from '../../next/src';
 vi.mock('@trpc/next', () => mock_trpcNext);
 
-export { mock_trpcServer as trpcServer, mock_trpcClient as trpcClient, mock_trpcReact as trpcReact, mock_trpcReact__ssg as trpcReact__ssg };
+export { 
+  mock_trpcServer as trpcServer,
+  mock_trpcClient as trpcClient,
+  mock_trpcReact as trpcReact,
+  mock_trpcReact__ssg as trpcReact__ssg,
+  mock_trpcReact__server as trpcReact__server 
+};

packages/tests/server/react/createClient.test.tsx

@@ -2,8 +2,8 @@ import { routerToServerAndClientNew } from '../___testHelpers';
 import { createQueryClient } from '../__queryClient';
 import { QueryClientProvider } from '@tanstack/react-query';
 import { render, waitFor } from '@testing-library/react';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { createTRPCReact, httpBatchLink } from '@trpc/react-query/src';
-import { createProxySSGHelpers } from '@trpc/react-query/src/ssg';
 import { initTRPC } from '@trpc/server/src';
 import { konn } from 'konn';
 import React, { ReactNode, useState } from 'react';
@@ -70,7 +70,7 @@ test('createClient()', async () => {
 test('useDehydratedState()', async () => {
   const { App, proxy, router } = ctx;
 
-  const ssg = createProxySSGHelpers({ router, ctx: {} });
+  const ssg = createServerSideHelpers({ router, ctx: {} });
   const res = await ssg.hello.fetch();
   expect(res).toBe('world');
   const dehydratedState = ssg.dehydrate();

packages/tests/server/react/deprecated/dehydrate.test.tsx

@@ -0,0 +1,44 @@
+import { createAppRouter } from '../__testHelpers';
+import { createProxySSGHelpers } from '@trpc/react-query/src/ssg';
+
+let factory: ReturnType<typeof createAppRouter>;
+beforeEach(() => {
+  factory = createAppRouter();
+});
+afterEach(async () => {
+  await factory.close();
+});
+
+test('dehydrate', async () => {
+  const { db, appRouter } = factory;
+  const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+
+  await ssg.allPosts.prefetch();
+  await ssg.postById.prefetch('1');
+
+  const dehydrated = ssg.dehydrate().queries;
+  expect(dehydrated).toHaveLength(2);
+
+  const [cache, cache2] = dehydrated;
+  expect(cache!.queryHash).toMatchInlineSnapshot(
+    `"[[\\"allPosts\\"],{\\"type\\":\\"query\\"}]"`,
+  );
+  expect(cache!.queryKey).toMatchInlineSnapshot(`
+    Array [
+      Array [
+        "allPosts",
+      ],
+      Object {
+        "type": "query",
+      },
+    ]
+  `);
+  expect(cache!.state.data).toEqual(db.posts);
+  expect(cache2!.state.data).toMatchInlineSnapshot(`
+    Object {
+      "createdAt": 0,
+      "id": "1",
+      "title": "first post",
+    }
+  `);
+});

packages/tests/server/react/infiniteQuery.test.tsx

@@ -3,7 +3,7 @@ import { Post, createAppRouter } from './__testHelpers';
 import { QueryClientProvider } from '@tanstack/react-query';
 import { render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { createProxySSGHelpers } from '@trpc/react-query/src/ssg';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { expectTypeOf } from 'expect-type';
 import React, { Fragment, useState } from 'react';
 
@@ -377,7 +377,7 @@ describe('Infinite Query', () => {
 
   test('prefetchInfiniteQuery()', async () => {
     const { appRouter } = factory;
-    const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+    const ssg = createServerSideHelpers({ router: appRouter, ctx: {} });
 
     {
       await ssg.paginatedPosts.prefetchInfinite({ limit: 1 });

packages/tests/server/react/ssg.test.ts

@@ -1,5 +1,5 @@
 import { InfiniteData } from '@tanstack/react-query';
-import { createProxySSGHelpers } from '@trpc/react-query/src/ssg/ssgProxy';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { initTRPC } from '@trpc/server/src';
 import { expectTypeOf } from 'expect-type';
 import { z } from 'zod';
@@ -26,14 +26,14 @@ const appRouter = t.router({
 });
 
 test('fetch', async () => {
-  const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+  const ssg = createServerSideHelpers({ router: appRouter, ctx: {} });
 
   const post = await ssg.post.byId.fetch({ id: '1' });
   expectTypeOf<'__result'>(post);
 });
 
 test('fetchInfinite', async () => {
-  const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+  const ssg = createServerSideHelpers({ router: appRouter, ctx: {} });
 
   const post = await ssg.post.list.fetchInfinite({});
   expectTypeOf<InfiniteData<'__infResult'>>(post);
@@ -42,15 +42,15 @@ test('fetchInfinite', async () => {
 });
 
 test('prefetch and dehydrate', async () => {
-  const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+  const ssg = createServerSideHelpers({ router: appRouter, ctx: {} });
   await ssg.post.byId.prefetch({ id: '1' });
 
   const data = JSON.stringify(ssg.dehydrate());
   expect(data).toContain('__result');
 });
 
 test('prefetchInfinite and dehydrate', async () => {
-  const ssg = createProxySSGHelpers({ router: appRouter, ctx: {} });
+  const ssg = createServerSideHelpers({ router: appRouter, ctx: {} });
   await ssg.post.list.prefetchInfinite({});
 
   const data = JSON.stringify(ssg.dehydrate());

www/docs/nextjs/ssg-helpers.md → www/docs/nextjs/server-side-helpers.md

@@ -1,20 +1,20 @@
 ---
-id: ssg-helpers
-title: SSG Helpers
-sidebar_label: SSG Helpers
-slug: /nextjs/ssg-helpers
+id: server-side-helpers
+title: Server-Side Helpers
+sidebar_label: Server-Side Helpers
+slug: /nextjs/server-side-helpers
 ---
 
-`createProxySSGHelpers` provides you with a set of helper functions that you can use to prefetch queries on the server.
+`createServerSideHelpers` provides you with a set of helper functions that you can use to prefetch queries on the server. This is useful for SSG, but also for SSR if you opt not to use `ssr: true`.
 
 Using the helpers makes tRPC call your procedures directly on the server, without an HTTP request, similar to [server-side calls](/docs/server/server-side-calls).
 That also means that you don't have the request and response at hand like you usually do. Make sure you're instantiating the SSG helpers with a context without `req` & `res`, which are typically filled via the context creation. We recommend the concept of ["inner" and "outer" context](/docs/server/context) in that scenario.
 
 ```ts
-import { createProxySSGHelpers } from '@trpc/react-query/ssg';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { createContext } from 'server/context';
 
-const ssg = createProxySSGHelpers({
+const ssg = createServerSideHelpers({
   router: appRouter,
   ctx: await createContext(),
   transformer: superjson, // optional - adds superjson serialization
@@ -30,7 +30,7 @@ The returned functions are all wrappers around react-query functions. Please che
 ## Next.js Example
 
 ```ts title='pages/posts/[id].tsx'
-import { createProxySSGHelpers } from '@trpc/react-query/ssg';
+import { createServerSideHelpers } from '@trpc/react-query/server';
 import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
 import { createContext } from 'server/context';
 import { appRouter } from 'server/routers/_app';
@@ -40,7 +40,7 @@ import { trpc } from 'utils/trpc';
 export async function getServerSideProps(
   context: GetServerSidePropsContext<{ id: string }>,
 ) {
-  const ssg = createProxySSGHelpers({
+  const ssg = createServerSideHelpers({
     router: appRouter,
     ctx: await createContext(),
     transformer: superjson,