tomevault-io Modern Fullstack Integration Patterns
Data Flow Architecture
Overview
┌─────────────────────────────────────────────────────────────┐
│ Client │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ React/ │───▶│ State │───▶│ UI │ │
│ │ Vue │ │ (Zustand/ │ │ Render │ │
│ │ Components│ │ Pinia) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Data Fetching (React Query / SWR / Apollo) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼ HTTP / GraphQL
┌─────────────────────────────────────────────────────────────┐
│ Server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ API │───▶│ Business │───▶│ Data │ │
│ │ Routes │ │ Logic │ │ Layer │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
Next.js API Routes
Basic API Route
// app/api/products/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { productService } from '@/lib/services/product-service';
export async function GET(request: NextRequest) {
const searchParams = request.nextUrl.searchParams;
const page = parseInt(searchParams.get('page') ?? '1');
const limit = parseInt(searchParams.get('limit') ?? '10');
const category = searchParams.get('category');
try {
const products = await productService.getProducts({
page,
limit,
category: category ?? undefined,
});
return NextResponse.json(products);
} catch (error) {
console.error('Failed to fetch products:', error);
return NextResponse.json(
{ error: 'Failed to fetch products' },
{ status: 500 }
);
}
}
export async function POST(request: NextRequest) {
try {
const body = await request.json();
// Validate request body
const validationResult = validateCreateProduct(body);
if (!validationResult.success) {
return NextResponse.json(
{ errors: validationResult.errors },
{ status: 400 }
);
}
const product = await productService.createProduct(body);
return NextResponse.json(product, { status: 201 });
} catch (error) {
console.error('Failed to create product:', error);
return NextResponse.json(
{ error: 'Failed to create product' },
{ status: 500 }
);
}
}
Dynamic API Route
// app/api/products/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
interface RouteParams {
params: { id: string };
}
export async function GET(request: NextRequest, { params }: RouteParams) {
const product = await productService.getById(params.id);
if (!product) {
return NextResponse.json(
{ error: 'Product not found' },
{ status: 404 }
);
}
return NextResponse.json(product);
}
export async function PUT(request: NextRequest, { params }: RouteParams) {
const body = await request.json();
try {
const product = await productService.update(params.id, body);
return NextResponse.json(product);
} catch (error) {
if (error instanceof NotFoundError) {
return NextResponse.json(
{ error: 'Product not found' },
{ status: 404 }
);
}
throw error;
}
}
export async function DELETE(request: NextRequest, { params }: RouteParams) {
await productService.delete(params.id);
return new NextResponse(null, { status: 204 });
}
GraphQL Integration
Query Definitions
# queries/products.graphql
query GetProducts($first: Int!, $after: String, $category: String) {
products(first: $first, after: $after, category: $category) {
edges {
node {
id
name
slug
price
image {
url
alt
}
category {
name
}
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
query GetProductBySlug($slug: String!) {
product(slug: $slug) {
id
name
slug
description
price
images {
url
alt
}
category {
name
slug
}
variants {
id
name
sku
price
}
}
}
mutation AddToCart($productId: ID!, $quantity: Int!) {
addToCart(input: { productId: $productId, quantity: $quantity }) {
cart {
id
items {
product {
name
}
quantity
}
total
}
}
}
GraphQL Client Setup
// lib/graphql/client.ts
import { GraphQLClient } from 'graphql-request';
const endpoint = process.env.GRAPHQL_ENDPOINT!;
const apiKey = process.env.API_KEY!;
export const graphqlClient = new GraphQLClient(endpoint, {
headers: {
'x-api-key': apiKey,
},
});
// With error handling wrapper
export async function fetchGraphQL<T>(
query: string,
variables?: Record<string, unknown>
): Promise<T> {
try {
return await graphqlClient.request<T>(query, variables);
} catch (error) {
console.error('GraphQL Error:', error);
throw new Error('Failed to fetch data');
}
}
React Hook for GraphQL
// hooks/useProducts.ts
import { useQuery } from '@tanstack/react-query';
import { graphqlClient } from '@/lib/graphql/client';
import { GetProductsDocument } from '@/generated/graphql';
interface UseProductsOptions {
category?: string;
limit?: number;
}
export function useProducts({ category, limit = 10 }: UseProductsOptions = {}) {
return useQuery({
queryKey: ['products', { category, limit }],
queryFn: async () => {
const data = await graphqlClient.request(GetProductsDocument, {
first: limit,
category,
});
return data.products;
},
staleTime: 5 * 60 * 1000, // 5 minutes
});
}
Server Components + Client Data
Server Component with Data
// app/products/page.tsx
import { getProducts } from '@/lib/api/products';
import { ProductGrid } from '@/components/ProductGrid';
import { ProductFilters } from '@/components/ProductFilters';
interface PageProps {
searchParams: { category?: string; page?: string };
}
export default async function ProductsPage({ searchParams }: PageProps) {
const page = parseInt(searchParams.page ?? '1');
const products = await getProducts({
category: searchParams.category,
page,
limit: 12,
});
return (
<main className="container mx-auto py-8">
<h1 className="text-3xl font-bold mb-6">Products</h1>
{/* Client component for interactivity */}
<ProductFilters initialCategory={searchParams.category} />
{/* Server-rendered product grid */}
<ProductGrid products={products.items} />
{/* Client component for pagination */}
<Pagination
currentPage={page}
totalPages={products.totalPages}
/>
</main>
);
}
Client Component with Mutations
'use client';
import { useState } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
interface AddToCartButtonProps {
productId: string;
productName: string;
}
export function AddToCartButton({ productId, productName }: AddToCartButtonProps) {
const [quantity, setQuantity] = useState(1);
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: async (data: { productId: string; quantity: number }) => {
const response = await fetch('/api/cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (!response.ok) {
throw new Error('Failed to add to cart');
}
return response.json();
},
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['cart'] });
},
});
return (
<div className="flex items-center gap-4">
<input
type="number"
min="1"
max="10"
value={quantity}
=> setQuantity(parseInt(e.target.value))}
className="w-20 px-3 py-2 border rounded"
/>
<button
=> mutation.mutate({ productId, quantity })}
disabled={mutation.isPending}
className="px-6 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50"
>
{mutation.isPending ? 'Adding...' : 'Add to Cart'}
</button>
{mutation.isError && (
<span className="text-red-500">Failed to add item</span>
)}
</div>
);
}
REST API Patterns
API Client
// lib/api/client.ts
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL;
interface RequestOptions extends RequestInit {
params?: Record<string, string>;
}
class ApiClient {
private baseUrl: string;
constructor(baseUrl: string) {
this.baseUrl = baseUrl;
}
private async request<T>(
endpoint: string,
options: RequestOptions = {}
): Promise<T> {
const { params, ...init } = options;
let url = `${this.baseUrl}${endpoint}`;
if (params) {
const searchParams = new URLSearchParams(params);
url += `?${searchParams.toString()}`;
}
const response = await fetch(url, {
...init,
headers: {
'Content-Type': 'application/json',
...init.headers,
},
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new ApiError(response.status, error.message ?? 'Request failed');
}
return response.json();
}
async get<T>(endpoint: string, params?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'GET', params });
}
async post<T>(endpoint: string, data: unknown): Promise<T> {
return this.request<T>(endpoint, {
method: 'POST',
body: JSON.stringify(data),
});
}
async put<T>(endpoint: string, data: unknown): Promise<T> {
return this.request<T>(endpoint, {
method: 'PUT',
body: JSON.stringify(data),
});
}
async delete(endpoint: string): Promise<void> {
await this.request(endpoint, { method: 'DELETE' });
}
}
export const api = new ApiClient(API_BASE_URL);
Type-Safe API Hooks
// hooks/api/useProducts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '@/lib/api/client';
import type { Product, CreateProductInput, UpdateProductInput } from '@/types';
export function useProducts(params?: { category?: string; page?: number }) {
return useQuery({
queryKey: ['products', params],
queryFn: () => api.get<{ items: Product[]; total: number }>('/products', {
category: params?.category,
page: String(params?.page ?? 1),
}),
});
}
export function useProduct(id: string) {
return useQuery({
queryKey: ['products', id],
queryFn: () => api.get<Product>(`/products/${id}`),
enabled: !!id,
});
}
export function useCreateProduct() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (data: CreateProductInput) =>
api.post<Product>('/products', data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['products'] });
},
});
}
export function useUpdateProduct() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: ({ id, data }: { id: string; data: UpdateProductInput }) =>
api.put<Product>(`/products/${id}`, data),
onSuccess: (product) => {
queryClient.invalidateQueries({ queryKey: ['products'] });
queryClient.setQueryData(['products', product.id], product);
},
});
}
export function useDeleteProduct() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (id: string) => api.delete(`/products/${id}`),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['products'] });
},
});
}
Environment Variables
Configuration
# .env.local
# Server-only (not exposed to browser)
DATABASE_URL=postgresql://user:pass@localhost:5432/db
API_SECRET_KEY=sk_live_xxxxx
GRAPHQL_ENDPOINT=https://api.example.com/graphql
# Public (exposed to browser via NEXT_PUBLIC_ prefix)
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_ANALYTICS_ID=UA-XXXXX
Type-Safe Environment
// lib/env.ts
import { z } from 'zod';
const envSchema = z.object({
// Server-only
DATABASE_URL: z.string().url(),
API_SECRET_KEY: z.string().min(1),
GRAPHQL_ENDPOINT: z.string().url(),
// Public
NEXT_PUBLIC_API_URL: z.string().url(),
NEXT_PUBLIC_SITE_URL: z.string().url(),
});
// Validate at build time
const parsed = envSchema.safeParse(process.env);
if (!parsed.success) {
console.error('Invalid environment variables:', parsed.error.flatten());
throw new Error('Invalid environment variables');
}
export const env = parsed.data;
// For client-side only variables
export const publicEnv = {
apiUrl: process.env.NEXT_PUBLIC_API_URL!,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
};
Error Handling
Error Boundaries
'use client';
import { useEffect } from 'react';
interface ErrorBoundaryProps {
error: Error & { digest?: string };
reset: () => void;
}
export default function ErrorBoundary({ error, reset }: ErrorBoundaryProps) {
useEffect(() => {
// Log to error tracking service
console.error('Error:', error);
}, [error]);
return (
<div className="flex flex-col items-center justify-center min-h-[400px] p-8">
<h2 className="text-2xl font-bold text-red-600 mb-4">
Something went wrong
</h2>
<p className="text-gray-600 mb-6">
{error.message || 'An unexpected error occurred'}
</p>
<button
className="px-6 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
>
Try again
</button>
</div>
);
}
API Error Handling
// lib/errors.ts
export class ApiError extends Error {
constructor(
public status: number,
message: string,
public code?: string
) {
super(message);
this.name = 'ApiError';
}
static isApiError(error: unknown): error is ApiError {
return error instanceof ApiError;
}
}
// Usage in components
function ProductPage() {
const { data, error, isLoading } = useProduct(id);
if (isLoading) return <Skeleton />;
if (error) {
if (ApiError.isApiError(error) && error.status === 404) {
return <NotFound message="Product not found" />;
}
return <ErrorMessage error={error} />;
}
return <ProductDetails product={data} />;
}
Optimistic Updates
// hooks/useToggleFavorite.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
export function useToggleFavorite() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (productId: string) => {
const response = await fetch(`/api/favorites/${productId}`, {
method: 'POST',
});
return response.json();
},
// Optimistic update
onMutate: async (productId) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({ queryKey: ['products'] });
// Snapshot previous value
const previousProducts = queryClient.getQueryData(['products']);
// Optimistically update
queryClient.setQueryData(['products'], (old: Product[]) =>
old.map((product) =>
product.id === productId
? { ...product, isFavorite: !product.isFavorite }
: product
)
);
return { previousProducts };
},
// Rollback on error
onError: (err, productId, context) => {
queryClient.setQueryData(['products'], context?.previousProducts);
},
// Refetch after success or error
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['products'] });
},
});
}
Real-Time Updates
WebSocket Integration
// lib/websocket.ts
import { useEffect, useRef } from 'react';
import { useQueryClient } from '@tanstack/react-query';
export function useWebSocket(url: string) {
const ws = useRef<WebSocket | null>(null);
const queryClient = useQueryClient();
useEffect(() => {
ws.current = new WebSocket(url);
ws.current.onmessage = (event) => {
const message = JSON.parse(event.data);
switch (message.type) {
case 'product:updated':
queryClient.invalidateQueries({
queryKey: ['products', message.productId]
});
break;
case 'cart:updated':
queryClient.invalidateQueries({ queryKey: ['cart'] });
break;
case 'notification':
// Handle notification
break;
}
};
ws.current.onclose = () => {
// Reconnect logic
setTimeout(() => {
ws.current = new WebSocket(url);
}, 3000);
};
return () => {
ws.current?.close();
};
}, [url, queryClient]);
return {
send: (data: unknown) => {
ws.current?.send(JSON.stringify(data));
},
};
}
SSR vs SSG vs ISR
Static Generation (SSG)
// For content that rarely changes
// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
const posts = await getPosts();
return posts.map((post) => ({ slug: post.slug }));
}
export default async function BlogPost({ params }: { params: { slug: string } }) {
const post = await getPost(params.slug);
return <Article post={post} />;
}
Incremental Static Regeneration (ISR)
// For content that updates periodically
// app/products/page.tsx
export const revalidate = 60; // Revalidate every 60 seconds
export default async function ProductsPage() {
const products = await getProducts();
return <ProductGrid products={products} />;
}
Server-Side Rendering (SSR)
// For personalized or real-time data
// app/dashboard/page.tsx
export const dynamic = 'force-dynamic';
export default async function DashboardPage() {
const user = await getCurrentUser();
const data = await getDashboardData(user.id);
return <Dashboard user={user} data={data} />;
}
Preview Mode / Draft Content
// app/api/preview/route.ts
import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';
export async function GET(request: NextRequest) {
const searchParams = request.nextUrl.searchParams;
const secret = searchParams.get('secret');
const slug = searchParams.get('slug');
if (secret !== process.env.PREVIEW_SECRET) {
return NextResponse.json({ error: 'Invalid token' }, { status: 401 });
}
// Enable draft mode
draftMode().enable();
// Redirect to the page
redirect(slug ?? '/');
}
// app/api/exit-preview/route.ts
export async function GET() {
draftMode().disable();
redirect('/');
}
// lib/api/content.ts
import { draftMode } from 'next/headers';
export async function getContent(slug: string) {
const { isEnabled: isDraft } = draftMode();
// Fetch draft or published content based on mode
const content = await cms.getContent(slug, {
preview: isDraft,
});
return content;
}
Converted and distributed by TomeVault — claim your Tome and manage your conversions.