create-velox-app 0.4.6 → 0.4.9

package/src/templates/source/web/main.tsx

@@ -1,19 +1,18 @@
+import { createRouter, RouterProvider } from '@tanstack/react-router';
+import { VeloxProvider } from '@veloxts/client/react';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { RouterProvider, createRouter } from '@tanstack/react-router';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
 import { routeTree } from './routeTree.gen';
 import './styles/global.css';
 
-// Create query client for data fetching
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60, // 1 minute
-      retry: 1,
-    },
-  },
-});
+// Import router type from API for full type safety
+import type { AppRouter } from '../../api/src/index.js';
+/* @if auth */
+// Import routes directly from backend - no manual duplication needed
+import { routes } from '../../api/src/index.js';
+
+/* @endif auth */
 
 // Create router with route tree
 const router = createRouter({ routeTree });
@@ -25,14 +24,65 @@ declare module '@tanstack/react-router' {
   }
 }
 
+/* @if auth */
+// Dynamic headers for auth - fetches token on each request
+const getAuthHeaders = () => {
+  const token = localStorage.getItem('token');
+  return token ? { Authorization: `Bearer ${token}` } : {};
+};
+
+// Automatic token refresh on 401 responses
+const handleUnauthorized = async (): Promise<boolean> => {
+  const refreshToken = localStorage.getItem('refreshToken');
+  if (!refreshToken) return false;
+
+  try {
+    const res = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    });
+
+    if (!res.ok) {
+      // Refresh failed - clear tokens
+      localStorage.removeItem('token');
+      localStorage.removeItem('refreshToken');
+      return false;
+    }
+
+    const data = (await res.json()) as { accessToken: string; refreshToken: string };
+    localStorage.setItem('token', data.accessToken);
+    localStorage.setItem('refreshToken', data.refreshToken);
+    return true; // Retry the original request
+  } catch {
+    // Network error during refresh
+    return false;
+  }
+};
+/* @endif auth */
+
 // Render application
 const rootElement = document.getElementById('root');
 if (!rootElement) throw new Error('Root element not found');
 
 createRoot(rootElement).render(
   <StrictMode>
-    <QueryClientProvider client={queryClient}>
+    {/* @if default */}
+    <VeloxProvider<AppRouter> config={{ baseUrl: '/api' }}>
+      <RouterProvider router={router} />
+    </VeloxProvider>
+    {/* @endif default */}
+    {/* @if auth */}
+    <VeloxProvider<AppRouter>
+      config={{
+        baseUrl: '/api',
+        headers: getAuthHeaders,
+        routes,
+        onUnauthorized: handleUnauthorized,
+      }}
+    >
       <RouterProvider router={router} />
-    </QueryClientProvider>
+    </VeloxProvider>
+    {/* @endif auth */}
   </StrictMode>
 );

package/src/templates/source/web/package.json

@@ -10,17 +10,19 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "@tanstack/react-router": "1.140.0",
-    "@tanstack/react-query": "5.90.12"
+    "@tanstack/react-query": "5.90.12",
+    "@tanstack/react-router": "1.140.5",
+    "@veloxts/client": "__VELOXTS_VERSION__",
+    "react": "19.2.1",
+    "react-dom": "19.2.1",
+    "react-error-boundary": "5.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.1.6",
-    "@types/react-dom": "19.1.5",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "5.1.2",
-    "@tanstack/router-plugin": "1.140.0",
-    "vite": "6.4.1",
+    "@tanstack/router-plugin": "1.140.5",
+    "vite": "7.2.7",
     "typescript": "5.9.3"
   }
 }

package/src/templates/source/web/routes/__root.tsx

@@ -1,24 +1,63 @@
-import { createRootRoute, Outlet, Link } from '@tanstack/react-router';
+import { createRootRoute, Link, Outlet } from '@tanstack/react-router';
+/* @if auth */
+import { useQuery } from '@veloxts/client/react';
+
+import type { AppRouter } from '../../../api/src/index.js';
 import styles from '@/App.module.css';
+/* @endif auth */
 
 export const Route = createRootRoute({
   component: RootLayout,
 });
 
 function RootLayout() {
+  /* @if auth */
+  const { data: user } = useQuery<AppRouter, 'auth', 'getMe'>(
+    'auth',
+    'getMe',
+    {},
+    { retry: false }
+  );
+  const isAuthenticated = !!user;
+  /* @endif auth */
+
   return (
     <div className={styles.app}>
       <nav className={styles.nav}>
         <div className={styles.navBrand}>
           <Link to="/" className={styles.logo}>
-            Velox TS
+            Velox TS
           </Link>
         </div>
         <div className={styles.navLinks}>
           <Link to="/" className={styles.navLink} activeProps={{ className: styles.navLinkActive }}>
             Home
           </Link>
-          <Link to="/about" className={styles.navLink} activeProps={{ className: styles.navLinkActive }}>
+          {/* @if default */}
+          <Link
+            to="/users"
+            className={styles.navLink}
+            activeProps={{ className: styles.navLinkActive }}
+          >
+            Users
+          </Link>
+          {/* @endif default */}
+          {/* @if auth */}
+          {isAuthenticated && (
+            <Link
+              to="/users"
+              className={styles.navLink}
+              activeProps={{ className: styles.navLinkActive }}
+            >
+              Users
+            </Link>
+          )}
+          {/* @endif auth */}
+          <Link
+            to="/about"
+            className={styles.navLink}
+            activeProps={{ className: styles.navLinkActive }}
+          >
             About
           </Link>
         </div>

package/src/templates/source/web/routes/about.tsx

@@ -1,4 +1,5 @@
 import { createFileRoute } from '@tanstack/react-router';
+
 import styles from '@/App.module.css';
 
 export const Route = createFileRoute('/about')({
@@ -18,12 +19,17 @@ function AboutPage() {
       <div className={styles.cards}>
         <div className={styles.card}>
           <h2>Type Safety</h2>
-          <p>End-to-end type safety without code generation. Types flow from backend to frontend automatically.</p>
+          <p>
+            End-to-end type safety without code generation. Types flow from backend to frontend
+            automatically.
+          </p>
         </div>
 
         <div className={styles.card}>
           <h2>Developer Experience</h2>
-          <p>Convention over configuration. Sensible defaults with escape hatches when you need them.</p>
+          <p>
+            Convention over configuration. Sensible defaults with escape hatches when you need them.
+          </p>
         </div>
 
         <div className={styles.card}>

package/src/templates/source/web/routes/index.auth.tsx

@@ -1,48 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useQueryClient } from '@veloxts/client/react';
 import { useState } from 'react';
-import styles from '@/App.module.css';
-
-// API helpers
-const api = {
-  get: async <T,>(path: string): Promise<T> => {
-    const token = localStorage.getItem('accessToken');
-    const res = await fetch(`/api${path}`, {
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return res.json();
-  },
-  post: async <T,>(path: string, data: unknown): Promise<T> => {
-    const token = localStorage.getItem('accessToken');
-    const res = await fetch(`/api${path}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...(token ? { Authorization: `Bearer ${token}` } : {}),
-      },
-      body: JSON.stringify(data),
-    });
-    if (!res.ok) {
-      const error = await res.json().catch(() => ({}));
-      throw new Error(error.message || `HTTP ${res.status}`);
-    }
-    return res.json();
-  },
-};
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  roles?: string[];
-}
 
-interface AuthResponse {
-  user: User;
-  accessToken: string;
-  refreshToken: string;
-}
+import styles from '@/App.module.css';
+import { api } from '@/api';
 
 export const Route = createFileRoute('/')({
   component: HomePage,
@@ -57,19 +18,13 @@ function HomePage() {
   const [error, setError] = useState('');
 
   // Check if user is logged in
-  const { data: user, isLoading } = useQuery({
-    queryKey: ['me'],
-    queryFn: () => api.get<User>('/auth/me'),
-    retry: false,
-  });
+  const { data: user, isLoading } = api.auth.getMe.useQuery({}, { retry: false });
 
-  const login = useMutation({
-    mutationFn: (data: { email: string; password: string }) =>
-      api.post<AuthResponse>('/auth/login', data),
+  const login = api.auth.createSession.useMutation({
     onSuccess: (data) => {
-      localStorage.setItem('accessToken', data.accessToken);
+      localStorage.setItem('token', data.accessToken);
       localStorage.setItem('refreshToken', data.refreshToken);
-      queryClient.invalidateQueries({ queryKey: ['me'] });
+      api.auth.getMe.invalidate(undefined, queryClient);
       setError('');
     },
     onError: (err) => {
@@ -77,13 +32,11 @@ function HomePage() {
     },
   });
 
-  const register = useMutation({
-    mutationFn: (data: { name: string; email: string; password: string }) =>
-      api.post<AuthResponse>('/auth/register', data),
+  const register = api.auth.createAccount.useMutation({
     onSuccess: (data) => {
-      localStorage.setItem('accessToken', data.accessToken);
+      localStorage.setItem('token', data.accessToken);
       localStorage.setItem('refreshToken', data.refreshToken);
-      queryClient.invalidateQueries({ queryKey: ['me'] });
+      api.auth.getMe.invalidate(undefined, queryClient);
       setError('');
     },
     onError: (err) => {
@@ -91,12 +44,11 @@ function HomePage() {
     },
   });
 
-  const logout = useMutation({
-    mutationFn: () => api.post('/auth/logout', {}),
+  const logout = api.auth.deleteSession.useMutation({
     onSuccess: () => {
-      localStorage.removeItem('accessToken');
+      localStorage.removeItem('token');
       localStorage.removeItem('refreshToken');
-      queryClient.setQueryData(['me'], null);
+      api.auth.getMe.setData({}, null, queryClient);
     },
   });
 
@@ -131,14 +83,18 @@ function HomePage() {
         <div className={styles.cards}>
           <div className={styles.card}>
             <h2>Your Profile</h2>
-            <p><strong>ID:</strong> {user.id}</p>
-            <p><strong>Roles:</strong> {user.roles?.join(', ') || 'user'}</p>
+            <p>
+              <strong>ID:</strong> {user.id}
+            </p>
+            <p>
+              <strong>Roles:</strong> {user.roles?.join(', ') || 'user'}
+            </p>
           </div>
 
           <div className={styles.card}>
             <h2>Actions</h2>
             <button
-              onClick={() => logout.mutate()}
+              onClick={() => logout.mutate({})}
               className={styles.button}
               disabled={logout.isPending}
             >
@@ -155,9 +111,7 @@ function HomePage() {
     <div className={styles.container}>
       <div className={styles.hero}>
         <h1 className={styles.title}>Welcome to VeloxTS</h1>
-        <p className={styles.subtitle}>
-          Full-stack TypeScript with authentication.
-        </p>
+        <p className={styles.subtitle}>Full-stack TypeScript with authentication.</p>
       </div>
 
       <div className={styles.authCard}>
@@ -215,14 +169,14 @@ function HomePage() {
           >
             {login.isPending || register.isPending
               ? 'Please wait...'
-              : isLogin ? 'Sign In' : 'Create Account'}
+              : isLogin
+                ? 'Sign In'
+                : 'Create Account'}
           </button>
         </form>
 
         {!isLogin && (
-          <p className={styles.formHint}>
-            Password: 12+ chars, uppercase, lowercase, number
-          </p>
+          <p className={styles.formHint}>Password: 12+ chars, uppercase, lowercase, number</p>
         )}
       </div>
     </div>

package/src/templates/source/web/routes/index.default.tsx

@@ -1,40 +1,20 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { useQuery } from '@tanstack/react-query';
-import styles from '@/App.module.css';
 
-// API helper
-const api = {
-  get: async <T,>(path: string): Promise<T> => {
-    const res = await fetch(`/api${path}`);
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return res.json();
-  },
-};
+import styles from '@/App.module.css';
+import { api } from '@/api';
 
 export const Route = createFileRoute('/')({
   component: HomePage,
 });
 
-interface HealthResponse {
-  status: string;
-  version: string;
-  timestamp: string;
-  uptime: number;
-}
-
 function HomePage() {
-  const { data: health, isLoading, error } = useQuery({
-    queryKey: ['health'],
-    queryFn: () => api.get<HealthResponse>('/health'),
-  });
+  const { data: health, isLoading, error } = api.health.check.useQuery({});
 
   return (
     <div className={styles.container}>
       <div className={styles.hero}>
         <h1 className={styles.title}>Welcome to VeloxTS</h1>
-        <p className={styles.subtitle}>
-          Full-stack TypeScript, beautifully simple.
-        </p>
+        <p className={styles.subtitle}>Full-stack TypeScript, beautifully simple.</p>
       </div>
 
       <div className={styles.cards}>
@@ -45,19 +25,19 @@ function HomePage() {
           ) : error ? (
             <p className={styles.error}>Disconnected</p>
           ) : (
-            <p className={styles.success}>
-              {health?.status === 'ok' ? 'Connected' : 'Unknown'}
-            </p>
-          )}
-          {health && (
-            <p className={styles.meta}>v{health.version}</p>
+            <p className={styles.success}>{health?.status === 'ok' ? 'Connected' : 'Unknown'}</p>
           )}
+          {health && <p className={styles.meta}>v{health.version}</p>}
         </div>
 
         <div className={styles.card}>
           <h2>Get Started</h2>
-          <p>Edit <code>apps/api/src/procedures</code> to add API endpoints.</p>
-          <p>Edit <code>apps/web/src/routes</code> to add pages.</p>
+          <p>
+            Edit <code>apps/api/src/procedures</code> to add API endpoints.
+          </p>
+          <p>
+            Edit <code>apps/web/src/routes</code> to add pages.
+          </p>
         </div>
 
         <div className={styles.card}>

package/src/templates/source/web/routes/users.tsx

@@ -0,0 +1,85 @@
+/**
+ * Users Page - Demonstrates React 19 patterns with VeloxTS
+ *
+ * Uses useSuspenseQuery with Suspense boundaries for cleaner component code.
+ * Data is guaranteed to be available when the component renders.
+ */
+
+import { createFileRoute } from '@tanstack/react-router';
+import { Suspense } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+
+import styles from '@/App.module.css';
+import { api } from '@/api';
+
+export const Route = createFileRoute('/users')({
+  component: UsersPage,
+});
+
+function UsersPage() {
+  return (
+    <div className={styles.container}>
+      <div className={styles.hero}>
+        <h1 className={styles.title}>Users</h1>
+        <p className={styles.subtitle}>Type-safe data fetching with React 19 Suspense</p>
+      </div>
+
+      <ErrorBoundary fallback={<UsersError />}>
+        <Suspense fallback={<UsersLoading />}>
+          <UsersTable />
+        </Suspense>
+      </ErrorBoundary>
+    </div>
+  );
+}
+
+/**
+ * Users table component - wrapped in Suspense
+ *
+ * With useSuspenseQuery, data is guaranteed to be available.
+ * No need for isLoading/error checks - handled by boundaries.
+ */
+function UsersTable() {
+  const { data } = api.users.listUsers.useSuspenseQuery({});
+
+  return (
+    <div className={styles.tableContainer}>
+      <table className={styles.table}>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Email</th>
+            <th>Created</th>
+          </tr>
+        </thead>
+        <tbody>
+          {data.data.map((user) => (
+            <tr key={user.id}>
+              <td>{user.name}</td>
+              <td>{user.email}</td>
+              <td>{new Date(user.createdAt).toLocaleDateString()}</td>
+            </tr>
+          ))}
+          {data.data.length === 0 && (
+            <tr>
+              <td colSpan={3} className={styles.emptyState}>
+                No users found. Create one via the API!
+              </td>
+            </tr>
+          )}
+        </tbody>
+      </table>
+      <p className={styles.meta}>
+        Page {data.meta.page} - {data.meta.total} total users
+      </p>
+    </div>
+  );
+}
+
+function UsersLoading() {
+  return <p className={styles.loading}>Loading users...</p>;
+}
+
+function UsersError() {
+  return <p className={styles.error}>Failed to load users. Please try again.</p>;
+}

package/src/templates/source/web/tsconfig.json

@@ -20,5 +20,6 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src"]
+  "include": ["src"],
+  "references": [{ "path": "../api" }]
 }

package/src/templates/source/web/vite.config.ts

@@ -1,8 +1,9 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import { tanstackRouter } from '@tanstack/router-plugin/vite';
 import path from 'node:path';
 
+import { tanstackRouter } from '@tanstack/router-plugin/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
 export default defineConfig({
   plugins: [tanstackRouter(), react()],
   resolve: {