Revisiting GraphQL in 2025: A Type-Safe Stack with Pothos and Relay

This article explores building a GraphQL server in 2025 using a modern, type-safe stack. We'll cover the tooling choices, backend setup with Pothos and Prisma, and frontend integration using Relay, highlighting the benefits for developer experience and application robustness.

If you prefer GFM markdown , read it on github

code reposotory

Section 1: Setting the Stage - Choosing the Right Tools for Type Safety

This section outlines the project requirements, the specific technology stack chosen, and the critical decision-making process for selecting libraries that ensure end-to-end type safety, ultimately leading to Pothos and Relay.

When tasked with building a new GraphQL server in 2025, the core requirements mandated the use of:

Node.js

Express

GraphQL

Prisma

PostgreSQL

TypeScript

The primary challenge was identifying tools that integrate seamlessly and provide strong end-to-end type safety guarantees. In an ideal scenario, the GraphQL types would be directly derived from the database schema managed by Prisma, minimizing type drift and manual synchronization efforts.

After evaluating several options, the choice narrowed down to two main contenders for building the GraphQL schema layer on top of Prisma:

Nexus: While a popular choice in the past, it appeared to lack support for the latest versions of Prisma at the time of evaluation, making it less suitable.

TypeGraphQL: Having used TypeGraphQL previously with TypeORM, I knew it worked well in that ecosystem. However, Prisma's schema-first approach differs significantly from TypeORM's entity-based model. I was uncertain how well Prisma's schema definition would align with the decorator-heavy, class-based approach central to TypeGraphQL.

Pothos: This library stood out due to its dedicated Prisma plugin (prisma-pothos-types), specifically designed to generate GraphQL types directly from the Prisma schema. This seemed like a natural fit for the project's goals.

Further investigation into Pothos revealed excellent support for Relay, including helpers for connections and node interfaces. This was a significant advantage, as the decision between using Relay or Apollo on the client-side was still pending. The strong type-safety features Relay offers, particularly for handling pagination and filtering, ultimately tipped the scales in its favor. Consequently, Pothos became the clear choice for the schema builder.

1// graphql/builder.ts

2import { lexicographicSortSchema, printSchema } from "graphql";

3// Generate the schema object from the Pothos builder

4export const pothosSchema = builder.toSchema();

6// Export the schema definition as a string (SDL)

7export const pothosSchemaString = printSchema(lexicographicSortSchema(pothosSchema));

10// index.ts - Server setup

11import express from 'express'; // Added import for clarity

12import { createYoga } from 'graphql-yoga'; // Added import for clarity

13import { fromNodeHeaders } from '@whatwg-node/server'; // Added import for clarity

14import { auth } from './auth'; // Assuming auth setup exists

15import { prisma } from './prismaClient'; // Assuming prisma client export exists

16import { PothosBuilderGenericType, builder, pothosSchema, pothosSchemaString } from './graphql/builder'; // Assuming builder exports exist

17// import { PrismaClient, User } from '@prisma/client'; // Assuming Prisma types import

19const app = express(); // Added instantiation

20const port = process.env.PORT || 4000; // Added port definition

22// Configure GraphQL Yoga server

23const yoga = createYoga<{

24 req: express.Request;

25 res: express.Response;

26}>({

27 // Use Apollo Sandbox for the GraphiQL interface

28 renderGraphiQL: () => {

29 // HTML to embed Apollo Sandbox

30 return `

31 <!DOCTYPE html>

32 <html lang="en">

33 <body style="margin: 0; overflow-x: hidden; overflow-y: hidden">

34 <div id="sandbox" style="height:100vh; width:100vw;"></div>

35 <script src="https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js"></script>

36 <script>

37 new window.EmbeddedSandbox({

38 target: "#sandbox",

39 initialEndpoint: "http://localhost:${port}/graphql", // Dynamic port

40 });

41 </script>

42 </body>

43 </html>`;

44 },

45 schema: pothosSchema, // Pass the generated Pothos schema

46 // Define the context function to inject data (like authenticated user) into resolvers

47 context: async (ctx): Promise<PothosBuilderGenericType['Context']> => { // Typed context return

48 try {

49 const session = await auth.api.getSession({ // Assuming auth setup provides getSession

50 headers: fromNodeHeaders(ctx.req.headers),

51 });

52 if (!session?.user) { // Check specifically for user object in session

53 return {

54 currentUser: undefined, // Explicitly undefined if no user

55 };

56 }

57 // Provide relevant user details to the context

58 return {

59 currentUser: {

60 id: session.user.id,

61 email: session.user.email ?? undefined, // Handle potentially null email

62 name: session.user.name ?? undefined, // Handle potentially null name

63 },

64 };

65 } catch (error) {

66 console.error("Error resolving context:", error); // Add error logging

67 return { currentUser: undefined };

68 }

69 },

70 graphiql: true, // Enable GraphiQL interface

71 logging: true, // Enable logging

72 cors: true, // Enable CORS

73});

75// Bind GraphQL Yoga to the /graphql endpoint

76// @ts-expect-error - Yoga types might mismatch slightly with Express middleware types

77app.use(yoga.graphqlEndpoint, yoga);

79// Define a simple root query required by GraphQL

80builder.queryType({

81 fields: (t) => ({

82 hello: t.string({

83 resolve: () => "Hello world!",

84 }),

85 // Other root queries will be added here...

86 }),

87});

89// Placeholder for other express routes/middleware

90// app.get('/', (req, res) => res.send('Server is running!'));

92app.listen(port, () => {

93 console.log(`🚀 Server ready at http://localhost:${port}/graphql`);

94 console.log(`🚀 GraphQL Playground available at http://localhost:${port}/graphql`); // Adjusted log message

95});

1// Define the Fren (User) type first if not already defined

2// Assuming a basic User type 'Fren' exists or is defined similarly

3export const Fren = builder.prismaNode("User", { // Example Fren type definition

4 id: { field: "id" },

5 fields: (t) => ({

6 frenId: t.exposeString("id"), // Expose 'id' as 'frenId'

7 name: t.exposeString("name"),

8 email: t.exposeString("email"),

9 image: t.exposeString("image"),

10 // Add other user fields as needed

11 }),

12});

15// Define the enhanced FeedPost type using prismaNode and custom fields

16export const FeedPost = builder.prismaNode("Post", {

17 // Using a variant allows multiple GraphQL types based on the same Prisma model if needed

18 // variant: "FeedPost", // Optional: Define a variant name

19 id: { field: "id" }, // Map the 'id' field for Relay Node interface

20 fields: (t) => ({

21 postId: t.exposeString("id", { nullable: false }), // Expose DB 'id' as 'postId'

22 content: t.exposeString("content"),

23 imageUrl: t.exposeString("imageUrl", { nullable: true }), // Explicitly nullable

24 // Custom resolver for ISO string date format

25 createdAt: t.field({

26 type: "String",

27 resolve: (post) => post.createdAt.toISOString(),

28 }),

29 // Custom resolver for ISO string date format

30 updatedAt: t.field({

31 type: "String",

32 resolve: (post) => post.updatedAt.toISOString(), // Corrected: use updatedAt

33 }),

34 // Field resolving the User who posted this

35 postedBy: t.field({

36 type: Fren, // Reference the 'Fren' (User) type

37 nullable: false, // Author should always exist

38 resolve: async (parent, args, context) => {

39 // Fetch the author using the authorId from the parent Post

40 const author = await prisma.user.findUnique({

41 where: { id: parent.authorId },

42 });

43 if (!author) {

44 // Handle case where author is somehow not found, though schema constraints should prevent this

45 throw new Error(`Author not found for post ${parent.id}`);

46 }

47 return author;

48 },

49 }),

50 // Custom field to calculate the number of likes

51 likeCount: t.field({

52 type: "Int",

53 resolve: async (parent) => {

54 // Count likes associated with the parent Post's id

55 return prisma.like.count({

56 where: { postId: parent.id },

57 });

58 },

59 }),

60 // Custom field to check if the current user liked this post

61 likedByMe: t.field({

62 type: "Boolean",

63 resolve: async (parent, args, context) => {

64 // If no user is logged in, they haven't liked it

65 if (!context.currentUser?.id) return false;

66 // Check if a Like record exists for this user and post

67 const like = await prisma.like.findUnique({ // Use findUnique for efficiency

68 where: {

69 userId_postId: { // Use the @@unique constraint defined in Prisma

70 userId: context.currentUser.id,

71 postId: parent.id,

72 }

73 },

74 });

75 // Return true if a like exists, false otherwise

76 return !!like;

77 },

78 }),

79 }),

80});

1// src/pages/FeedPage.tsx - Root component for the feed view

2import React from 'react';

3import { useLazyLoadQuery } from 'react-relay';

4import { MainFeedContainerQuery } from './__generated__/MainFeedContainerQuery.graphql'; // Import generated types

5import { MainFeedQuery } from './MainFeed'; // Import the query definition

6import { MainFeed } from '../components/MainFeed'; // Import the component using the fragment

8export function FeedPage() { // Renamed component for clarity

9 // Fetch the initial data for the page using the main query

10 const queryData = useLazyLoadQuery<MainFeedContainerQuery>(MainFeedQuery, { first: 10 }); // Fetch initial 10 posts

12 return (

13 <div className="w-full py-4">

14 {/* Pass the query data (specifically the part matching the fragment) to the MainFeed component */}

15 <MainFeed queryRef={queryData} />

16 </div>

17 );

18}

21// src/components/MainFeed.tsx - Component rendering the list of posts

22import React from 'react';

23import { useFragment } from 'react-relay';

24import { MainFeed_feedPosts$key } from './__generated__/MainFeed_feedPosts.graphql'; // Import fragment type

25import { MainFeedFragment } from './MainFeed'; // Import fragment definition (assuming it's here or imported)

26import { PostCard } from "./FeedCard"; // Import the child component

28interface FeedProps {

29 queryRef: MainFeed_feedPosts$key; // Prop type expects the fragment $key

30}

32export function MainFeed({ queryRef }: FeedProps) { // Renamed component

33 // Use the useFragment hook to read data defined by the MainFeedFragment

34 const data = useFragment(

35 MainFeedFragment,

36 queryRef

37 );

39 // Extract post nodes safely

40 const posts = data?.feedPosts?.edges?.map(edge => edge?.node) ?? []; // Use optional chaining and nullish coalescing

42 // Render the list of posts, passing each post's data (as a fragment ref) to PostCard

43 return (

44 <div className="w-full max-w-2xl mx-auto">

45 {posts.map((post) => post && (

46 // Pass the individual post fragment reference to the PostCard

47 <PostCard key={post.id} postRef={post} />

48 ))}

49 {/* Pagination controls will be added later */}

50 </div>

51 );

52}

55// src/components/FeedCard.tsx - Component rendering a single post

56import React from 'react';

57import { useFragment } from 'react-relay';

58import { FeedCard_post$key } from "./__generated__/FeedCard_post.graphql"; // Import fragment type

59import { FeedCardFragment } from './FeedCard'; // Import fragment definition (assuming it's here or imported)

60// Assuming Card components are imported from a UI library like ShadCN/UI

61import { Card, CardContent /* ... other Card parts */ } from '@/components/ui/card';

64interface PostCardProps {

65 postRef: FeedCard_post$key; // Prop type expects the fragment $key for a single post

66 // viewer?: BetterAuthViewer; // Example of passing other props if needed

67}

69export function PostCard({ postRef }: PostCardProps) { // Removed viewer prop for simplicity

70 // Use useFragment to read the data defined by FeedCardFragment

71 const postData = useFragment<FeedCard_post$key>(FeedCardFragment, postRef);

73 // Early return if postData is somehow null/undefined (though Relay usually prevents this if ref is valid)

74 if (!postData) {

75 return null;

76 }

78 // Example: Using derived data or formatting

79 // const postIdFirstChars = postData?.id.substring(0, 2).toUpperCase();

81 return (

82 <Card className="w-full mb-4 border-none bg-base-300">

83 <CardContent className="pt-6">

84 {/* Display post content, author info, like button, etc. using postData */}

85 <p>{postData.content}</p>

86 {/* ... other card elements ... */}

87 <span>Likes: {postData.likeCount}</span>

88 <span>{postData.likedByMe ? 'You liked this' : 'Like'}</span>

89 </CardContent>

90 </Card>

91 )

92}

1// src/components/MainFeed.tsx - Updated component using usePaginationFragment

2import React from 'react';

3// Import the specific pagination query type generated by @refetchable

4import { MainFeedPaginationQuery } from "./__generated__/MainFeedPaginationQuery.graphql";

5import { MainFeed_feedPosts$key } from './__generated__/MainFeed_feedPosts.graphql';

6import { usePaginationFragment } from 'react-relay';

7import { PostCard } from "./FeedCard";

8import { MainFeedFragment } from './MainFeed'; // Import fragment definition

9// Assuming Button and Loader components are imported

10import { Button } from '@/components/ui/button';

11import { Loader2 } from 'lucide-react';

13interface FeedProps {

14 queryRef: MainFeed_feedPosts$key;

15}

17export function MainFeed({ queryRef }: FeedProps) {

18 // Use usePaginationFragment hook

19 const {

20 data, // The accumulated data for the connection

21 loadNext, // Function to load the next page

22 hasNext, // Boolean indicating if more pages exist

23 isLoadingNext // Boolean indicating if the next page is currently loading

24 } = usePaginationFragment<MainFeedPaginationQuery, MainFeed_feedPosts$key>(

25 MainFeedFragment, // The fragment definition

26 queryRef // The fragment reference passed from the parent

27 );

29 // Function to trigger loading more posts

30 const loadMorePosts = () => {

31 // Prevent multiple requests or loading if no more data

32 if (isLoadingNext || !hasNext) return;

33 loadNext(5); // Load the next 5 items (or adjust count as needed)

34 };

36 // Extract post nodes from the accumulated data

37 const posts = data?.feedPosts?.edges?.map(edge => edge?.node) ?? [];

39 return (

40 <div className="w-full max-w-2xl mx-auto">

41 {posts.map((post) => post && (

42 <PostCard key={post.id} postRef={post} />

43 ))}

45 {/* Display a "Load More" button if there's a next page */}

46 {hasNext && (

47 <div className="flex justify-center my-4">

48 <Button onClick={loadMorePosts} variant="outline" disabled={isLoadingNext}>

49 {isLoadingNext ? (

50 <>

51 <Loader2 className="mr-2 h-4 w-4 animate-spin" />

52 Loading more posts...

53 </>

54 ) : (

55 "Load More Posts"

56 )}

57 </Button>

58 </div>

59 )}

60 </div>

61 );

62}

1// src/components/PostDialogs.tsx - Usage of create mutation

2import { useMutation, ConnectionHandler } from 'react-relay';

3import { PostDialogsCreateMutation } from './__generated__/PostDialogsCreateMutation.graphql'; // Generated type

5// Inside your component...

6const [commitCreateMutation, isCreating] = useMutation<PostDialogsCreateMutation>(createPostMutation);

7// Assuming 'setError' state hook exists

8const setError = (e: Error | null) => { /* ... */ };

9// Assuming PostFormData type exists

10type PostFormData = { content: string; imageUrl?: string };

12const handleCreateSubmit = (data: PostFormData) => {

13 setError(null);

14 commitCreateMutation({

15 variables: {

16 content: data.content,

17 imageUrl: data.imageUrl || undefined, // Use undefined if optional

18 },

19 // Updater function to manually insert the new post into the connection

20 updater: (store) => {

21 // Get the newly created post edge from the mutation response payload

22 const payload = store.getRootField("createPost"); // Matches mutation name

23 const newEdge = payload?.getLinkedRecord("newPostEdge"); // Matches field in mutation response

25 if (!newEdge) {

26 console.error("Failed to get new edge from createPost mutation payload");

27 return;

28 }

30 // Get the connection record from the store

31 const root = store.getRoot();

32 // Use the connection key defined in the @connection directive

33 const connection = ConnectionHandler.getConnection(

34 root,

35 "MainFeed_feedPosts" // Must match the key in MainFeedFragment @connection

36 );

38 if (!connection) {

39 console.error("Failed to find connection MainFeed_feedPosts in store");

40 return;

41 }

43 // Insert the new edge at the beginning of the connection

44 ConnectionHandler.insertEdgeBefore(connection, newEdge);

45 },

46 onError: (error) => {

47 setError(error);

48 console.error("Create post failed:", error);

49 }

50 });

51};

1// src/components/PostDialogs.tsx - Usage of delete mutation

2import { useMutation, ConnectionHandler } from 'react-relay';

3import { PostDialogsDeleteMutation } from './__generated__/PostDialogsDeleteMutation.graphql';

5// Inside your component, assuming 'post' object with 'id' (global Relay ID) exists

6// const post: { id: string, postId: string /* ... other fields */ };

7const [commitDeleteMutation, isDeleting] =

8 useMutation<PostDialogsDeleteMutation>(deletePostMutation);

9const setError = (e: Error | null) => { /* ... */ };

11const handleDeletePost = () => {

12 setError(null);

14 commitDeleteMutation({

15 variables: {

16 id: post.id, // Pass the global Relay ID

17 },

18 // Updater function to remove the node from the connection

19 updater: (store) => {

20 // Get the ID of the deleted post from the payload

21 const payload = store.getRootField("deletePost");

22 const deletedId = payload?.getValue("deletedPostId"); // Matches field in mutation

24 if (typeof deletedId !== 'string') {

25 console.error("Could not get deletedPostId from payload");

26 return;

27 }

29 // Get the connection

30 const root = store.getRoot();

31 const connection = ConnectionHandler.getConnection(root, "MainFeed_feedPosts");

33 if (!connection) {

34 console.error("Failed to find connection MainFeed_feedPosts in store");

35 return;

36 }

38 // Remove the node using its ID

39 ConnectionHandler.deleteNode(connection, deletedId);

40 },

41 // Optimistic updater removes the item from the UI immediately

42 optimisticUpdater: (store) => {

43 const root = store.getRoot();

44 const connection = ConnectionHandler.getConnection(root, "MainFeed_feedPosts");

45 if (connection) {

46 // Remove the node optimistically using its known ID

47 ConnectionHandler.deleteNode(connection, post.id);

48 }

49 },

50 onError: (error) => {

51 setError(error);

52 console.error("Delete post failed:", error);

53 }

54 });

55};

Revisiting GraphQL in 2025: A Type-Safe Stack with Pothos and Relay

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

Building Android Widgets in Expo with Custom Native Modules

Revisiting GraphQL in 2025: A Type-Safe Stack with Pothos and Relay

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

Building Android Widgets in Expo with Custom Native Modules

Section 1: Setting the Stage - Choosing the Right Tools for Type Safety

Section 2: Backend Implementation - Pothos, Prisma, and Express Integration

Section 3: Frontend Integration - Consuming the API with Relay Fragments

More posts

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

Building Android Widgets in Expo with Custom Native Modules

More posts

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

Building Android Widgets in Expo with Custom Native Modules

Section 1: Setting the Stage - Choosing the Right Tools for Type Safety

Section 2: Backend Implementation - Pothos, Prisma, and Express Integration

Section 3: Frontend Integration - Consuming the API with Relay Fragments

Section 4: Advanced Relay - Effortless Pagination and Mutation Handling