@tanstack/cta-framework-react-cra 0.43.0 → 0.44.0

package/add-ons/apollo-client/README.md

@@ -0,0 +1,150 @@
+# Apollo Client Integration
+
+This add-on integrates Apollo Client with TanStack Start to provide modern streaming SSR support for GraphQL data fetching.
+
+## Dependencies
+
+The following packages are automatically installed:
+
+- `@apollo/client` - Apollo Client core
+- `@apollo/client-integration-tanstack-start` - TanStack Start integration
+- `graphql` - GraphQL implementation
+
+## Configuration
+
+### 1. GraphQL Endpoint
+
+Configure your GraphQL API endpoint in `src/router.tsx`:
+
+```tsx
+// Configure Apollo Client
+const apolloClient = new ApolloClient({
+  cache: new InMemoryCache(),
+  link: new HttpLink({
+    uri: 'https://your-graphql-api.example.com/graphql', // Update this!
+  }),
+})
+```
+
+You can use environment variables by creating a `.env.local` file:
+
+```bash
+VITE_GRAPHQL_ENDPOINT=https://your-api.com/graphql
+```
+
+The default configuration already uses this pattern:
+
+```tsx
+uri: import.meta.env.VITE_GRAPHQL_ENDPOINT ||
+  'https://your-graphql-api.example.com/graphql'
+```
+
+## Usage Patterns
+
+### Pattern 1: Loader with preloadQuery (Recommended for SSR)
+
+Use `preloadQuery` in route loaders for optimal streaming SSR performance:
+
+```tsx
+import { gql, TypedDocumentNode } from '@apollo/client'
+import { useReadQuery } from '@apollo/client/react'
+import { createFileRoute } from '@tanstack/react-router'
+
+const MY_QUERY: TypedDocumentNode<{
+  posts: { id: string; title: string; content: string }[]
+}> = gql`
+  query GetData {
+    posts {
+      id
+      title
+      content
+    }
+  }
+`
+
+export const Route = createFileRoute('/my-route')({
+  component: RouteComponent,
+  loader: ({ context: { preloadQuery } }) => {
+    const queryRef = preloadQuery(MY_QUERY, {
+      variables: {},
+    })
+    return { queryRef }
+  },
+})
+
+function RouteComponent() {
+  const { queryRef } = Route.useLoaderData()
+  const { data } = useReadQuery(queryRef)
+
+  return <div>{/* render your data */}</div>
+}
+```
+
+### Pattern 2: useSuspenseQuery
+
+Use `useSuspenseQuery` directly in components with automatic suspense support:
+
+```tsx
+import { gql, TypedDocumentNode } from '@apollo/client'
+import { useSuspenseQuery } from '@apollo/client/react'
+import { createFileRoute } from '@tanstack/react-router'
+
+const MY_QUERY: TypedDocumentNode<{
+  posts: { id: string; title: string }[]
+}> = gql`
+  query GetData {
+    posts {
+      id
+      title
+    }
+  }
+`
+
+export const Route = createFileRoute('/my-route')({
+  component: RouteComponent,
+})
+
+function RouteComponent() {
+  const { data } = useSuspenseQuery(MY_QUERY)
+
+  return <div>{/* render your data */}</div>
+}
+```
+
+### Pattern 3: Manual Refetching
+
+```tsx
+import { useQueryRefHandlers, useReadQuery } from '@apollo/client/react'
+
+function MyComponent() {
+  const { queryRef } = Route.useLoaderData()
+  const { refetch } = useQueryRefHandlers(queryRef)
+  const { data } = useReadQuery(queryRef)
+
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+      {/* render data */}
+    </div>
+  )
+}
+```
+
+## Important Notes
+
+### SSR Optimization
+
+The integration automatically handles:
+
+- Query deduplication across server and client
+- Streaming SSR with `@defer` directive support
+- Proper cache hydration
+
+## Learn More
+
+- [Apollo Client Documentation](https://www.apollographql.com/docs/react)
+- [@apollo/client-integration-tanstack-start](https://www.npmjs.com/package/@apollo/client-integration-tanstack-start)
+
+## Demo
+
+Visit `/demo/apollo-client` in your application to see a working example of Apollo Client integration.

package/add-ons/apollo-client/assets/src/routes/demo.apollo-client.tsx

@@ -0,0 +1,75 @@
+import { gql, TypedDocumentNode } from '@apollo/client'
+import { useReadQuery } from '@apollo/client/react'
+import { createFileRoute } from '@tanstack/react-router'
+import React from 'react'
+
+// Example GraphQL query - replace with your own schema
+const EXAMPLE_QUERY: TypedDocumentNode<{
+  continents: { __typename: string; code: string; name: string }
+}> = gql`
+  query ExampleQuery {
+    continents {
+      code
+      name
+    }
+  }
+`
+
+export const Route = createFileRoute('/demo/apollo-client')({
+  component: RouteComponent,
+  loader: ({ context: { preloadQuery } }) => {
+    // Preload the query in the loader for optimal performance
+    const queryRef = preloadQuery(EXAMPLE_QUERY, {
+      variables: {},
+    })
+    return {
+      queryRef,
+    }
+  },
+})
+
+function RouteComponent() {
+  const { queryRef } = Route.useLoaderData()
+  const { data } = useReadQuery(queryRef)
+
+  return (
+    <div className="p-4">
+      <h2 className="text-2xl font-bold mb-4">Apollo Client Demo</h2>
+      <div className="bg-blue-100 border border-blue-400 text-blue-700 px-4 py-3 rounded mb-4">
+        <p className="font-bold">Apollo Client is configured!</p>
+        <p className="text-sm mt-2">
+          This demo uses{' '}
+          <code className="bg-blue-200 px-1 rounded">preloadQuery</code> in the
+          loader and{' '}
+          <code className="bg-blue-200 px-1 rounded">useReadQuery</code> in the
+          component for optimal streaming SSR performance.
+        </p>
+      </div>
+      <div className="bg-gray-100 p-4 rounded">
+        <h3 className="font-bold mb-2">Query Result:</h3>
+        <pre className="text-sm overflow-x-auto">
+          {JSON.stringify(data, null, 2)}
+        </pre>
+      </div>
+      <div className="mt-4 text-sm text-gray-600">
+        <p>📝 Next steps:</p>
+        <ul className="list-disc ml-6 mt-2">
+          <li>
+            Configure your GraphQL endpoint in{' '}
+            <code className="bg-gray-200 px-1 rounded">src/router.tsx</code>
+          </li>
+          <li>Replace the example query with your actual GraphQL schema</li>
+          <li>
+            Learn more:{' '}
+            <a
+              href="https://www.apollographql.com/docs/react"
+              className="text-blue-600 hover:underline"
+            >
+              Apollo Client Docs
+            </a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  )
+}

package/add-ons/apollo-client/info.json

@@ -0,0 +1,19 @@
+{
+  "name": "Apollo Client",
+  "description": "Integrate Apollo Client with streaming SSR support for GraphQL data fetching.",
+  "phase": "add-on",
+  "modes": ["file-router"],
+  "type": "add-on",
+  "priority": 15,
+  "link": "https://github.com/apollographql/apollo-client-integrations/tree/main/packages/tanstack-start",
+  "dependsOn": ["start"],
+  "routes": [
+    {
+      "icon": "Network",
+      "url": "/demo/apollo-client",
+      "name": "Apollo Client",
+      "path": "src/routes/demo.apollo-client.tsx",
+      "jsName": "ApolloClientDemo"
+    }
+  ]
+}

package/add-ons/apollo-client/package.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": {
+    "@apollo/client": "^4.0.0",
+    "@apollo/client-integration-tanstack-start": "^0.14.2-rc.0",
+    "graphql": "^16.10.0",
+    "rxjs": "^7.8.2"
+  }
+}

package/add-ons/apollo-client/small-logo.svg

@@ -0,0 +1,11 @@
+<svg width="238" height="238" viewBox="0 0 238 238" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_3682_2767)">
+<path d="M169.918 151.249L164.506 135.869L157.379 115.617L152.223 100.96L145.474 81.779L137.633 59.5H99.6029L93.5324 76.7516L88.1203 92.1321L61.2402 168.518H86.3228L94.1915 146.222H132.229L125.479 127.04H100.913L106.069 112.384L116.837 81.779L118.618 76.7134L120.398 81.779L150.906 168.5L150.913 168.518H175.995L169.918 151.249Z" fill="#15252D"/>
+<path d="M222.007 60.4327C221.377 59.3152 220.328 58.4938 219.092 58.1493C217.857 57.8048 216.534 57.9653 215.417 58.5956C214.299 59.2259 213.478 60.2743 213.133 61.5102C212.789 62.7461 212.949 64.0682 213.58 65.1858C226.408 87.9957 230.592 114.663 225.366 140.306C220.141 165.948 205.854 188.851 185.122 204.822C164.39 220.792 138.6 228.761 112.472 227.271C86.3451 225.78 61.6284 214.93 42.8471 196.706C24.0658 178.481 12.4764 154.102 10.2003 128.032C7.92431 101.961 15.1139 75.9426 30.4531 54.7395C45.7923 33.5363 68.2548 18.567 93.7287 12.5717C119.203 6.57632 145.984 9.95607 169.169 22.0923C168.426 25.5125 168.92 29.0854 170.561 32.1766C172.202 35.2678 174.886 37.6774 178.136 38.9777C181.385 40.278 184.99 40.3849 188.311 39.2794C191.632 38.1739 194.453 35.9275 196.275 32.9389C198.097 29.9504 198.801 26.4131 198.262 22.9548C197.723 19.4966 195.976 16.3412 193.331 14.0486C190.687 11.7561 187.315 10.4748 183.815 10.4321C180.316 10.3895 176.914 11.5883 174.214 13.8157C149.014 0.453404 119.841 -3.37605 92.0453 3.02956C64.2498 9.43517 39.6953 25.6465 22.8848 48.6905C6.07431 71.7345 -1.86527 100.066 0.522193 128.49C2.90965 156.914 15.4641 183.525 35.8831 203.442C56.3021 223.359 83.2168 235.247 111.691 236.926C140.166 238.605 168.291 229.963 190.91 212.584C213.528 195.205 229.123 170.255 234.835 142.308C240.547 114.362 235.992 85.2934 222.007 60.4333V60.4327Z" fill="#15252D"/>
+</g>
+<defs>
+<clipPath id="clip0_3682_2767">
+<rect width="237.236" height="237.236" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/add-ons/convex/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
-    "@convex-dev/react-query": "0.0.0-alpha.11",
+    "@convex-dev/react-query": "0.1.0",
     "convex": "^1.27.3",
-    "lucide-react": "^0.544.0"
+    "lucide-react": "^0.561.0"
   }
 }

package/add-ons/db/assets/src/hooks/demo.useChat.ts

@@ -3,7 +3,7 @@ import { useLiveQuery } from '@tanstack/react-db'
 
 import { messagesCollection, type Message } from '@/db-collections'
 
-import type { Collection } from '@tanstack/db'
+import type { Collection } from '@tanstack/react-db'
 
 function useStreamConnection(
   url: string,

package/add-ons/db/assets/src/routes/demo/db-chat-api.ts

@@ -1,7 +1,10 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { json } from '@tanstack/react-start'
 
-import { createCollection, localOnlyCollectionOptions } from '@tanstack/db'
+import {
+  createCollection,
+  localOnlyCollectionOptions,
+} from '@tanstack/react-db'
 import { z } from 'zod'
 
 const IncomingMessageSchema = z.object({

package/add-ons/db/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@tanstack/query-db-collection": "^0.2.0",
+    "@tanstack/query-db-collection": "^1.0.8",
     "@tanstack/react-db": "^0.1.1",
     "zod": "^4.0.14"
   }

package/add-ons/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
-    "zod": "4.1.11"
+    "zod": "4.2.1"
   }
 }

package/add-ons/neon/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
     "@neondatabase/serverless": "^1.0.0",
-    "@neondatabase/vite-plugin-postgres": "^0.2.0"
+    "@neondatabase/vite-plugin-postgres": "^0.5.0"
   }
 }

package/add-ons/prisma/package.json.ejs

@@ -11,7 +11,7 @@
     "tsx": "^4.20.6"
   },
   "scripts": {<% if (addOnOption.prisma.database === 'postgres') { %>
-    "post-cta-init": "npx create-db@latest",<% } %>
+    "post-cta-init": "npx create-db@latest --user-agent tanstack/tsrouter",<% } %>
     "db:generate": "dotenv -e .env.local -- prisma generate",
     "db:push": "dotenv -e .env.local -- prisma db push",
     "db:migrate": "dotenv -e .env.local -- prisma migrate dev",

package/add-ons/sentry/assets/instrument.server.mjs

@@ -1,10 +1,17 @@
 import * as Sentry from '@sentry/tanstackstart-react'
-Sentry.init({
-  dsn: import.meta.env.VITE_SENTRY_DSN,
-  // Adds request headers and IP for users, for more info visit:
-  // https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/configuration/options/#sendDefaultPii
-  sendDefaultPii: true,
-  tracesSampleRate: 1.0,
-  replaysSessionSampleRate: 1.0,
-  replaysOnErrorSampleRate: 1.0,
-})
+
+const sentryDsn = import.meta.env?.VITE_SENTRY_DSN ?? process.env.VITE_SENTRY_DSN
+
+if (!sentryDsn) {
+  console.warn('VITE_SENTRY_DSN is not defined. Sentry is not running.')
+} else {
+  Sentry.init({
+    dsn: sentryDsn,
+    // Adds request headers and IP for users, for more info visit:
+    // https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/configuration/options/#sendDefaultPii
+    sendDefaultPii: true,
+    tracesSampleRate: 1.0,
+    replaysSessionSampleRate: 1.0,
+    replaysOnErrorSampleRate: 1.0,
+  })
+}

package/add-ons/sentry/assets/src/routes/demo/sentry.testing.tsx

@@ -285,6 +285,16 @@ function RouteComponent() {
   const [results, setResults] = useState<
     Record<string, { type: 'success' | 'error'; spanOp: string }>
   >({})
+  const [sentryConfigured, setSentryConfigured] = useState<boolean | null>(null)
+
+  useEffect(() => {
+    // Check if Sentry DSN environment variable is set
+    const hasDsn = !!import.meta.env.VITE_SENTRY_DSN
+    setSentryConfigured(hasDsn)
+  }, [])
+
+  // Don't show warning until we've checked on the client
+  const showWarning = sentryConfigured === false
 
   const handleClientError = async () => {
     setIsLoading((prev) => ({ ...prev, clientError: true }))
@@ -394,8 +404,8 @@ function RouteComponent() {
             </div>
           </div>
           <p className="text-lg text-[#A49FB5] max-w-xl mx-auto leading-relaxed">
-            Click the buttons below to trigger errors and traces, then view
-            them in your{' '}
+            Click the buttons below to trigger errors and traces, then view them
+            in your{' '}
             <a
               href="https://sentry.io"
               target="_blank"
@@ -408,6 +418,32 @@ function RouteComponent() {
           </p>
         </div>
 
+        {/* Sentry Not Initialized Warning */}
+        {showWarning && (
+          <div className="mb-8 flex items-center gap-3 bg-[#E5A000]/10 border border-[#E5A000]/30 rounded-xl px-6 py-4">
+            <svg
+              className="w-6 h-6 text-[#E5A000] flex-shrink-0"
+              fill="none"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="2"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+            >
+              <title>Warning</title>
+              <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+            </svg>
+            <div>
+              <p className="text-[#E5A000] font-medium">
+                Sentry is not initialized
+              </p>
+              <p className="text-[#A49FB5] text-sm mt-1">
+                Set the <code className="bg-[#1C1825] px-1.5 py-0.5 rounded text-[#B3A1FF]">VITE_SENTRY_DSN</code> environment variable to enable error tracking and performance monitoring.
+              </p>
+            </div>
+          </div>
+        )}
+
         {/* Features Grid */}
         <div className="grid grid-cols-1 md:grid-cols-4 gap-4 mb-12">
           <FeatureCard
@@ -463,6 +499,7 @@ function RouteComponent() {
                   variant="error"
                   onClick={handleClientError}
                   loading={isLoading.clientError}
+                  disabled={sentryConfigured === false}
                 >
                   Trigger Client Error
                 </SentryButton>
@@ -483,6 +520,7 @@ function RouteComponent() {
                   variant="primary"
                   onClick={handleClientTrace}
                   loading={isLoading.clientTrace}
+                  disabled={sentryConfigured === false}
                 >
                   Test Client Trace
                 </SentryButton>
@@ -513,6 +551,7 @@ function RouteComponent() {
                   variant="error"
                   onClick={handleServerError}
                   loading={isLoading.serverError}
+                  disabled={sentryConfigured === false}
                 >
                   Trigger Server Error
                 </SentryButton>
@@ -533,6 +572,7 @@ function RouteComponent() {
                   variant="primary"
                   onClick={handleServerTrace}
                   loading={isLoading.serverTrace}
+                  disabled={sentryConfigured === false}
                 >
                   Test Server Trace
                 </SentryButton>

package/add-ons/shadcn/package.json

@@ -2,7 +2,7 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.544.0",
+    "lucide-react": "^0.561.0",
     "tailwind-merge": "^3.0.2",
     "tw-animate-css": "^1.3.6"
   }

package/add-ons/start/assets/src/router.tsx.ejs

@@ -1,6 +1,13 @@
 import { createRouter } from '@tanstack/react-router'<% if (addOnEnabled['tanstack-query']) { %>
 import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
 import * as TanstackQuery from "./integrations/tanstack-query/root-provider";
+<% } %><% if (addOnEnabled['apollo-client']) { %>
+import {
+  routerWithApolloClient,
+  ApolloClient,
+  InMemoryCache,
+} from "@apollo/client-integration-tanstack-start";
+import { HttpLink } from "@apollo/client";
 <% } %>
 <% if (addOnEnabled.sentry) { %>
 import * as Sentry from "@sentry/tanstackstart-react";
@@ -11,22 +18,39 @@ import { routeTree } from './routeTree.gen'
 
 // Create a new router instance
 export const getRouter = () => {
+<% if (addOnEnabled['apollo-client']) { %>
+  // Configure Apollo Client
+  const apolloClient = new ApolloClient({
+    cache: new InMemoryCache(),
+    link: new HttpLink({
+      uri: import.meta.env.VITE_GRAPHQL_ENDPOINT || "https://countries.trevorblades.com/"
+    }),
+  });
+<% } %>
 <% if (addOnEnabled['tanstack-query']) { %>
-    const rqContext = TanstackQuery.getContext();
-
-    const router = createRouter({
-        routeTree,
-        context: { ...rqContext },
-        defaultPreload: "intent",
-      })
+  const rqContext = TanstackQuery.getContext();
+<% } %>
 
-    setupRouterSsrQueryIntegration({router, queryClient: rqContext.queryClient})
-<% } else { %>
   const router = createRouter({
     routeTree,
+    context: {
+<% if (addOnEnabled['apollo-client']) { %>
+      ...routerWithApolloClient.defaultContext,
+<% } %>
+<% if (addOnEnabled['tanstack-query']) { %>
+      ...rqContext,
+<% } %>
+    },
+<% if (addOnEnabled['tanstack-query'] || addOnEnabled['apollo-client']) { %>
+    defaultPreload: "intent",
+<% } else { %>
     scrollRestoration: true,
     defaultPreloadStaleTime: 0,
+<% } %>
   })
+
+<% if (addOnEnabled['tanstack-query']) { %>
+  setupRouterSsrQueryIntegration({router, queryClient: rqContext.queryClient})
 <% } %>
 
 <% if (addOnEnabled.sentry) { %>
@@ -40,5 +64,5 @@ export const getRouter = () => {
   }
 <% } %>
 
-  return router;
+  return <% if (addOnEnabled['apollo-client']) { %>routerWithApolloClient(router, apolloClient)<% } else { %>router<% } %>;
 }

package/add-ons/start/package.json

@@ -6,7 +6,7 @@
   "dependencies": {
     "@tanstack/react-router-ssr-query": "^1.131.7",
     "@tanstack/react-start": "^1.132.0",
-    "vite-tsconfig-paths": "^5.1.4",
-    "lucide-react": "^0.544.0"
+    "vite-tsconfig-paths": "^6.0.2",
+    "lucide-react": "^0.561.0"
   }
 }

package/add-ons/store/package.json

@@ -1,9 +1,9 @@
 {
   "dependencies": {
-    "@tanstack/store": "^0.7.0",
-    "@tanstack/react-store": "^0.7.0"
+    "@tanstack/store": "^0.8.0",
+    "@tanstack/react-store": "^0.8.0"
   },
   "devDependencies": {
-    "@tanstack/devtools-event-client": "^0.3.2"
+    "@tanstack/devtools-event-client": "^0.4.0"
   }
 }

package/add-ons/storybook/package.json

@@ -4,7 +4,7 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
-    "@storybook/react-vite": "^9.1.9",
-    "storybook": "^9.1.9"
+    "@storybook/react-vite": "^10.1.10",
+    "storybook": "^10.1.10"
   }
 }

package/dist/index.js

@@ -1,7 +1,6 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { registerFramework, scanAddOnDirectories, scanProjectDirectory, } from '@tanstack/cta-engine';
-import { contentChecksum } from './checksum.js';
 export function createFrameworkDefinition() {
     const baseDirectory = dirname(dirname(fileURLToPath(import.meta.url)));
     const addOns = scanAddOnDirectories([
@@ -32,10 +31,8 @@ export function createFrameworkDefinition() {
                 forceTypescript: true,
             },
         },
-        contentChecksum,
     };
 }
 export function register() {
     registerFramework(createFrameworkDefinition());
 }
-export { contentChecksum };

package/dist/types/index.d.ts

@@ -1,5 +1,3 @@
-import { contentChecksum } from './checksum.js';
 import type { FrameworkDefinition } from '@tanstack/cta-engine';
 export declare function createFrameworkDefinition(): FrameworkDefinition;
 export declare function register(): void;
-export { contentChecksum };