The Definitive cross-platform Guide for React Server Components and GraphQL

// shared/schema.js\n// Shared GraphQL schema for cross-platform React RSC + GraphQL app\n// Uses graphql/graphql-js (https://github.com/graphql/graphql-js) v16.8.1\nimport {\n  GraphQLSchema,\n  GraphQLObjectType,\n  GraphQLString,\n  GraphQLInt,\n  GraphQLFloat,\n  GraphQLList,\n  GraphQLError,\n  GraphQLNonNull,\n} from 'graphql';\n\n// Custom error class for consistent error handling across platforms\nclass ProductNotFoundError extends GraphQLError {\n  constructor(productId) {\n    super(`Product with ID ${productId} not found`);\n    this.extensions = {\n      code: 'PRODUCT_NOT_FOUND',\n      productId,\n      timestamp: new Date().toISOString(),\n    };\n  }\n}\n\n// Mock product data store (replace with database in production)\nconst mockProducts = [\n  { id: '1', name: 'Wireless Headphones', price: 129.99, stock: 42, category: 'electronics' },\n  { id: '2', name: 'Organic Cotton T-Shirt', price: 24.99, stock: 156, category: 'apparel' },\n  { id: '3', name: 'Stainless Steel Water Bottle', price: 34.99, stock: 89, category: 'home' },\n];\n\n// Define Product GraphQL type with non-null constraints for required fields\nconst ProductType = new GraphQLObjectType({\n  name: 'Product',\n  description: 'E-commerce product with inventory data',\n  fields: () => ({\n    id: { type: new GraphQLNonNull(GraphQLString), description: 'Unique product identifier' },\n    name: { type: new GraphQLNonNull(GraphQLString), description: 'Display name of product' },\n    price: { type: new GraphQLNonNull(GraphQLFloat), description: 'Retail price in USD' },\n    stock: { type: new GraphQLNonNull(GraphQLInt), description: 'Current inventory count' },\n    category: { type: new GraphQLNonNull(GraphQLString), description: 'Product category for filtering' },\n  }),\n});\n\n// Root Query type with error-handling resolver logic\nconst RootQueryType = new GraphQLObjectType({\n  name: 'Query',\n  description: 'Root query type for product data',\n  fields: () => ({\n    products: {\n      type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ProductType))),\n      description: 'Fetch all products, optionally filtered by category',\n      args: {\n        category: { type: GraphQLString, description: 'Optional category to filter products' },\n      },\n      resolve: (parent, args) => {\n        try {\n          if (args.category) {\n            const filtered = mockProducts.filter(p => p.category === args.category);\n            if (filtered.length === 0) {\n              throw new GraphQLError(`No products found for category: ${args.category}`, {\n                extensions: { code: 'CATEGORY_EMPTY', category: args.category },\n              });\n            }\n            return filtered;\n          }\n          return mockProducts;\n        } catch (err) {\n          // Re-throw GraphQL errors directly, wrap others in generic error\n          if (err instanceof GraphQLError) throw err;\n          throw new GraphQLError('Failed to fetch products', {\n            extensions: { code: 'FETCH_ERROR', originalError: err.message },\n          });\n        }\n      },\n    },\n    product: {\n      type: ProductType,\n      description: 'Fetch single product by ID',\n      args: {\n        id: { type: new GraphQLNonNull(GraphQLString), description: 'Product ID to fetch' },\n      },\n      resolve: (parent, args) => {\n        try {\n          const product = mockProducts.find(p => p.id === args.id);\n          if (!product) throw new ProductNotFoundError(args.id);\n          return product;\n        } catch (err) {\n          if (err instanceof GraphQLError) throw err;\n          throw new GraphQLError('Failed to fetch product', {\n            extensions: { code: 'FETCH_ERROR', originalError: err.message },\n          });\n        }\n      },\n    },\n  }),\n});\n\n// Export final schema for use in RSC server, Expo client, and Next.js API routes\nexport const schema = new GraphQLSchema({\n  query: RootQueryType,\n  // Mutation type omitted for brevity, add in production\n});\n\n// Validate schema on startup (only runs in Node.js environments)\nif (typeof process !== 'undefined' && process.env.NODE_ENV !== 'test') {\n  try {\n    // Schema validation ensures no missing required fields\n    const { validateSchema } = require('graphql');\n    const errors = validateSchema(schema);\n    if (errors.length > 0) {\n      console.error('Schema validation failed:', errors);\n      process.exit(1);\n    }\n    console.log('✅ Shared GraphQL schema validated successfully');\n  } catch (err) {\n    console.error('Schema validation error:', err);\n  }\n}\n

// app/products/page.jsx\n// React Server Component (RSC) for product listing page\n// Uses Next.js 14.2.3 (https://github.com/vercel/next.js) with RSC enabled by default\nimport { graphql } from 'graphql';\nimport { schema } from '../../shared/schema';\nimport ProductCard from './ProductCard';\nimport ErrorBoundary from './ErrorBoundary';\n\n// GraphQL query for product listing (executed server-side in RSC)\nconst PRODUCTS_QUERY = `\n  query GetProducts($category: String) {\n    products(category: $category) {\n      id\n      name\n      price\n      stock\n      category\n    }\n  }\n`;\n\n// Server-side data fetching function (runs in RSC context, no client JS)\nasync function fetchProducts(category = null) {\n  try {\n    // Execute GraphQL query directly against shared schema in server context\n    const result = await graphql({\n      schema,\n      source: PRODUCTS_QUERY,\n      variableValues: { category },\n      // Context for future auth/database integration\n      contextValue: { user: null, db: null },\n    });\n\n    if (result.errors) {\n      // Throw first GraphQL error for error boundary to catch\n      throw new Error(result.errors[0].message, { cause: result.errors });\n    }\n\n    return result.data.products;\n  } catch (err) {\n    // Log server-side error for observability (use Sentry/DataDog in production)\n    console.error('[RSC Product Fetch] Failed to fetch products:', err);\n    throw new Error(`Failed to load products: ${err.message}`, { cause: err });\n  }\n}\n\n// RSC default export (server-rendered, no client-side JS for initial load)\nexport default async function ProductsPage({ searchParams }) {\n  // Extract category filter from URL search params (server-side)\n  const category = searchParams?.category || null;\n  let products = [];\n  let error = null;\n\n  try {\n    products = await fetchProducts(category);\n  } catch (err) {\n    error = err;\n  }\n\n  return (\n    \n      \n        Product Catalog\n        {category && (Filtered: {category})}\n      \n\n      {/* Category filter links (server-rendered, no client JS) */}\n      \n        \n          All\n        \n        \n          Electronics\n        \n        \n          Apparel\n        \n        \n          Home\n        \n      \n\n      {/* Error boundary for graceful failure */}\n      Failed to load products. Please try again.}>\n        {error ? (\n          Error: {error.message}\n        ) : (\n          \n            {products.map(product => (\n              \n            ))}\n          \n        )}\n      \n    \n  );\n}\n\n// Generate static params for ISR (Incremental Static Regeneration) if needed\nexport async function generateStaticParams() {\n  return ['electronics', 'apparel', 'home'].map(category => ({ category }));\n}\n\n// Set revalidation period for ISR (60 seconds)\nexport const revalidate = 60;\n

// shared/graphql-client.js\n// Cross-platform GraphQL client for Expo (iOS/Android) and Next.js client components\n// Uses graphql-request v6.1.0 (https://github.com/prisma/graphql-request) for lightweight fetching\nimport { GraphQLClient } from 'graphql-request';\nimport { ProductNotFoundError } from './errors';\n\n// Environment-specific GraphQL endpoint (configured via expo-constants for mobile)\nconst getGraphQLEndpoint = () => {\n  if (typeof window !== 'undefined') {\n    // Web client: use relative API route\n    return '/api/graphql';\n  }\n  // Expo mobile: use environment variable or fallback to local dev server\n  const { Constants } = require('expo-constants');\n  return Constants.manifest?.extra?.graphqlEndpoint || 'http://localhost:3000/api/graphql';\n};\n\n// Initialize client with error handling and retry logic\nclass CrossPlatformGraphQLClient {\n  constructor() {\n    this.client = new GraphQLClient(getGraphQLEndpoint(), {\n      headers: {\n        'Content-Type': 'application/json',\n      },\n      // Retry failed requests (max 2 retries for network errors)\n      fetch: this.retryFetch.bind(this),\n    });\n  }\n\n  // Retry logic for transient network failures\n  async retryFetch(url, options, retries = 2) {\n    try {\n      const response = await fetch(url, options);\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n      return response;\n    } catch (err) {\n      if (retries <= 0) throw err;\n      console.warn(`Retrying GraphQL request (${retries} left):`, err.message);\n      await new Promise(resolve => setTimeout(resolve, 1000 * (3 - retries))); // Exponential backoff\n      return this.retryFetch(url, options, retries - 1);\n    }\n  }\n\n  // Generic request method with error normalization\n  async request(query, variables = {}) {\n    try {\n      const data = await this.client.request(query, variables);\n      return { data, error: null };\n    } catch (err) {\n      // Normalize GraphQL errors to consistent format\n      const normalizedError = this.normalizeError(err);\n      console.error('[GraphQL Client] Request failed:', normalizedError);\n      return { data: null, error: normalizedError };\n    }\n  }\n\n  // Normalize errors across platforms (web, iOS, Android)\n  normalizeError(err) {\n    if (err.response?.errors) {\n      // GraphQL errors from server\n      const firstError = err.response.errors[0];\n      return {\n        message: firstError.message,\n        code: firstError.extensions?.code || 'GRAPHQL_ERROR',\n        originalError: firstError,\n      };\n    }\n    if (err instanceof ProductNotFoundError) {\n      return {\n        message: err.message,\n        code: 'PRODUCT_NOT_FOUND',\n        originalError: err,\n      };\n    }\n    // Network or unknown errors\n    return {\n      message: err.message || 'Unknown error occurred',\n      code: 'NETWORK_ERROR',\n      originalError: err,\n    };\n  }\n}\n\n// Export singleton instance for shared use across platforms\nexport const graphqlClient = new CrossPlatformGraphQLClient();\n\n// Example query for product details (used in both web client components and Expo screens)\nexport const PRODUCT_DETAIL_QUERY = `\n  query GetProduct($id: String!) {\n    product(id: $id) {\n      id\n      name\n      price\n      stock\n      category\n    }\n  }\n`;\n\n// Helper function to fetch product details with error handling\nexport async function fetchProductDetails(productId) {\n  const { data, error } = await graphqlClient.request(PRODUCT_DETAIL_QUERY, { id: productId });\n  if (error) throw new Error(error.message, { cause: error });\n  if (!data.product) throw new ProductNotFoundError(productId);\n  return data.product;\n}\n

// Correct RSC data fetching (no client imports)\nimport { graphql } from 'graphql';\nimport { schema } from './shared/schema';\n\nasync function getServerData() {\n  const { data } = await graphql({ schema, source: '{ products { id } }' });\n  return data;\n}

// CI schema validation (GitHub Actions step)\n- name: Validate GraphQL Schema\n  run: |\n    node -e \"const { validateSchema, schema } = require('./shared/schema'); const errors = validateSchema(schema); if (errors.length) { console.error(errors); process.exit(1); }\"

// RSC page with ISR (60 second revalidation)\nexport const revalidate = 60;\n\nexport default async function Page() {\n  const data = await graphql({ schema, source: '{ products { id } }' });\n  return {JSON.stringify(data)};\n}

rsc-graphql-cross-platform/\n├── shared/                  # Shared code across platforms\n│   ├── schema.js             # Shared GraphQL schema (Step 1)\n│   ├── graphql-client.js     # Cross-platform GraphQL client (Step 3)\n│   └── errors.js             # Shared error classes\n├── next-app/                 # Next.js web app (RSC)\n│   ├── app/\n│   │   ├── products/         # RSC product page (Step 2)\n│   │   │   ├── page.jsx\n│   │   │   └── ProductCard.jsx\n│   │   └── api/\n│   │       └── graphql/      # GraphQL API route for web client\n│   │           └── route.js\n├── expo-app/                 # Expo mobile app (iOS/Android)\n│   ├── app/\n│   │   ├── (tabs)/\n│   │   │   └── products/     # Expo product screen\n│   │   │       └── index.jsx\n│   │   └── _layout.jsx\n│   └── package.json\n├── package.json              # Root monorepo package.json\n├── turbo.json                # Turborepo config for monorepo\n└── README.md                 # Setup instructions