🌟 What is GraphQL?

GraphQL is a query language for APIs. Unlike REST, where you have many endpoints, GraphQL lets you ask for exactly the data you need from a single endpoint. This makes your app faster and your code cleaner.

🌟 What is Apollo Client?

Apollo Client is a powerful library that connects your React (or Next.js) app to a GraphQL server. It makes working with GraphQL easy and efficient by handling data fetching, caching, and UI updates for you.

• Fetches data from your GraphQL API using queries and mutations
• Caches data locally for fast, responsive UIs
• Manages loading and error states automatically
• Integrates deeply with React using hooks like useQuery and useMutation
• Supports file uploads, authentication, and real-time updates

import { ApolloClient, InMemoryCache } from "@apollo/client";
import { createUploadLink } from "apollo-upload-client";

const client = new ApolloClient({
  link: createUploadLink({ uri: "http://localhost:3000/graphql" }),
  cache: new InMemoryCache(),
});

🌟 What is Next.js?

Next.js is a powerful React framework for building fast, modern web applications. It extends React with features like server-side rendering (SSR), static site generation (SSG), API routes, and more—making it a popular choice for both startups and large companies.

• Server-Side Rendering (SSR): Render pages on the server for better SEO and faster initial load.
• Static Site Generation (SSG): Pre-render pages at build time for blazing-fast performance.
• API Routes: Build backend endpoints directly in your frontend project.
• File-based Routing: Create pages by adding files to the pages/ or app/ directory.
• Built-in CSS & Sass support: Style your app easily.
• Image Optimization: Automatically optimize images for performance.
• Great Developer Experience: Fast refresh, TypeScript support, and more.

🔧 Backend Setup for Testing

Before we start building the frontend, you’ll need a GraphQL backend to test against. We’ll use the GraphQL Backend repository which provides a complete Rails-based GraphQL API.

🚀 Step 1: Project Setup

This step will guide you through creating a new Next.js project, installing all required dependencies, and understanding the project structure. Follow each step carefully—even if you’re new to React or Next.js, you’ll be up and running in minutes!

npx create-next-app@latest photostock-frontend --tailwind --app --src-dir
cd photostock-frontend

npm install @apollo/client apollo-upload-client graphql

code .

npm run dev

🚀 Step 2: Apollo Client Setup

Apollo Client connects your app to the GraphQL backend.

Create a file: src/apollo/client.js

import { ApolloClient, InMemoryCache } from "@apollo/client";
import { createUploadLink } from "apollo-upload-client";

const client = new ApolloClient({
  link: createUploadLink({ uri: "http://localhost:3000/graphql" }),
  cache: new InMemoryCache(),
});

export default client;

🚀 Step 3: Add ApolloProvider

To use Apollo everywhere, wrap your app in an ApolloProvider.

Create: src/components/ApolloWrapper.js

"use client";
import { ApolloProvider } from "@apollo/client";
import client from "../apollo/client";

export default function ApolloWrapper({ children }) {
  return {children};
}

Update your root layout: src/app/layout.js

"use client";
import "./globals.css";
import ApolloWrapper from "../components/ApolloWrapper";
import { AuthProvider } from '../contexts/AuthContext';

export default function RootLayout({ children }) {
  return (
    
      
        
          
            {children}
          
         
    
  );
}

🚀 Step 4: Authentication (Login & Signup)

We’ll use React Context to manage user authentication.

Create: src/context/AuthContext.js

"use client";
import { createContext, useContext, useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { gql, useLazyQuery, useMutation } from "@apollo/client";

// GraphQL queries and mutations (matching the backend schema)
const LOGIN_MUTATION = gql`
  mutation SignIn($input: SignInInput!) {
    signIn(input: $input) {
      token
      user { id email }
    }
  }
`;
const SIGNUP_MUTATION = gql`
  mutation SignUp($input: SignUpInput!) {
    signUp(input: $input) { id email }
  }
`;
const ME_QUERY = gql`
  query { me { id email } }
`;

const AuthContext = createContext();

export function AuthProvider({ children }) {
  const router = useRouter();
  const [user, setUser] = useState(null);
  const [token, setToken] = useState(null);
  const [signInMutation] = useMutation(LOGIN_MUTATION);
  const [signUpMutation] = useMutation(SIGNUP_MUTATION);
  const [loadUser] = useLazyQuery(ME_QUERY, {
    fetchPolicy: "network-only",
    onCompleted: (data) => setUser(data.me),
    onError: () => logout(),
  });

  useEffect(() => {
    const storedToken = typeof window !== "undefined" ? localStorage.getItem("token") : null;
    if (storedToken) {
      setToken(storedToken);
      loadUser({ context: { headers: { Authorization: `Bearer ${storedToken}` } } });
    }
  }, []);

  const login = async (email, password) => {
    const res = await signInMutation({ variables: { input: { email, password } } });
    const t = res.data.signIn.token;
    setToken(t);
    localStorage.setItem("token", t);
    setUser(res.data.signIn.user);
    router.push("/dashboard");
  };

  const signup = async (email, password) => {
    await signUpMutation({ variables: { input: { email, password } } });
    await login(email, password);
  };

  const logout = () => {
    setToken(null);
    setUser(null);
    localStorage.removeItem("token");
    router.push("/login");
  };

  return (
    
      {children}
    
  );
}

export const useAuth = () => useContext(AuthContext);

Wrap your app with AuthProvider in layout.js:

{`import { AuthProvider } from './path/to/AuthProvider';

export default function RootLayout({ children }) {
  return (
    
      {children}
    
  );
}`}

🚀 Step 5: Fetching Data (Queries)

Let’s show a list of photos from the backend.

In src/app/page.js:

 {
    if (token) {
      loadPhotos({
        variables: { limit, offset, titleContains: search },
        context: { headers: { Authorization: `Bearer ${token}` } },
      });
    }
  }, [token, offset, search]);

  // ... render your UI here ...
}

🚀 Step 6: Mutating Data (Like, Upload)

Liking a photo:

const TOGGLE_LIKE = gql`
  mutation LikePhoto($input: LikePhotoInput!) {
    likePhoto(input: $input) { liked }
  }
`;

const [likePhoto] = useMutation(TOGGLE_LIKE, {
  context: { headers: { Authorization: `Bearer ${token}` } },
  onCompleted: (data) => setLiked(data.likePhoto.liked),
  onError: (err) => alert(err.message),
});

const handleLike = async () => {
  if (!user) return;
  await likePhoto({ variables: { input: { photoId: photo.id } } });
};

Uploading a photo:

const UPLOAD_PHOTO = gql`
  mutation UploadPhoto($input: UploadPhotoInput!) {
    uploadPhoto(input: $input) { id title imageUrl }
  }
`;

const [uploadPhoto, { loading, error }] = useMutation(UPLOAD_PHOTO);

const handleSubmit = async (e) => {
  e.preventDefault();
  if (!image) return alert("Please select an image");
  await uploadPhoto({
    variables: { input: { title, image } },
    context: { headers: { Authorization: `Bearer ${token}` } },
  });
};

🚀 Step 7: UI and Styling

• Use Tailwind CSS for easy, responsive design.
• Use React components for cards, modals, and forms.
• Show loading and error states for a better user experience.

🚀 Step 8: Testing with the Backend

Running Both Applications

📚 GraphQL Frontend Vocabulary & Terminology

type Photo {
  id: ID!
  title: String!
  imageUrl: String!
  user: User!
}

type User {
  id: ID!
  email: String!
  name: String
}

photos {
  id      # This is a field
  title   # This is a field
}

type Photo {
  id: ID!           # Scalar
  title: String!    # Scalar
  likesCount: Int   # Scalar
}

type Photo {
  id: ID!
  user: User!  # Object type (not scalar)
}

interface Media {
  id: ID!
  title: String!
}

type Photo implements Media {
  id: ID!
  title: String!
  imageUrl: String!
}

union SearchResult = Photo | User | Comment

enum PhotoCategory {
  NATURE
  URBAN
  PORTRAIT
}

input AddPhotoInput {
  title: String!
  image: Upload!
}

query GetPhotos {
  photos @include(if: $showPhotos) {
    id
    title
  }
}

query GetPhotos {
  photos {
    id
    title
  }
}

mutation AddPhoto($input: AddPhotoInput!) {
  addPhoto(input: $input) {
    id
    title
  }
}

subscription OnPhotoAdded {
  photoAdded {
    id
    title
  }
}

fragment PhotoFields on Photo {
  id
  title
  imageUrl
}

query GetPhotos {
  photos {
    ...PhotoFields
  }
}

query GetPhoto($id: ID!) {
  photo(id: $id) {
    id
    title
  }
}

photos(limit: 10, offset: 0) {
  id
  title
}

query {
  recentPhotos: photos(limit: 5) {
    id
    title
  }
  popularPhotos: photos(sortBy: "likes") {
    id
    title
  }
}

import { ApolloClient, InMemoryCache } from "@apollo/client";

import { ApolloProvider } from "@apollo/client";

const { data, loading, error } = useQuery(GET_PHOTOS);

const [addPhoto, { loading, error }] = useMutation(ADD_PHOTO);

const { data } = useSubscription(PHOTO_ADDED);

const [getPhotos, { data }] = useLazyQuery(GET_PHOTOS);

const cache = new InMemoryCache();

// Raw: { photos: [{ id: "1", user: { id: "1", name: "John" } }] }
// Normalized: { "Photo:1": { id: "1", user: "User:1" }, "User:1": { id: "1", name: "John" } }

const cache = new InMemoryCache({
  typePolicies: {
    Photo: {
      keyFields: ["id"]
    }
  }
});

fields: {
  displayTitle: {
    read(existing, { readField }) {
      const title = readField("title");
      return title ? title.toUpperCase() : "";
    }
  }
}

optimisticResponse: {
  addPhoto: {
    id: "temp-id",
    title: "New Photo",
    __typename: "Photo"
  }
}

update: (cache, { data }) => {
  cache.modify({
    fields: {
      photos: (existing = []) => [...existing, data.addPhoto]
    }
  });
}

refetchQueries: [{ query: GET_PHOTOS }]

fetchPolicy: "cache-first" // cache-and-network, network-only, cache-only, no-cache

errorPolicy: "all" // ignore, none

context: { headers: { Authorization: `Bearer ${token}` } }

// GraphQL requests are always POST to /graphql
fetch("/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query, variables })
});

query GetPhotos {
  photos { id title }
}

query IntrospectionQuery {
  __schema {
    types { name fields { name type { name } } }
  }
}

http://localhost:3000/graphiql

{
  "errors": [
    {
      "message": "Photo not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["photo"]
    }
  ]
}

if (error.networkError) {
  console.log("Network error:", error.networkError);
}

// Error: Field "invalidField" doesn't exist on type "Photo"

if (error.graphQLErrors?.some(e => e.extensions?.code === 'UNAUTHENTICATED')) {
  // Redirect to login
}

if (error.graphQLErrors?.some(e => e.extensions?.code === 'FORBIDDEN')) {
  // Show access denied
}

# Bad: Could cause N+1
query GetPhotos {
  photos {
    id
    user {  # Separate query for each photo
      id
      name
    }
  }
}

// Backend solution to prevent N+1
const userLoader = new DataLoader(async (userIds) => {
  return await User.findByIds(userIds);
});

type PhotoConnection {
  edges: [PhotoEdge!]!
  pageInfo: PageInfo!
}

type PhotoEdge {
  node: Photo!
  cursor: String!
}

query GetPhotos($cursor: String) {
  photos(first: 10, after: $cursor) {
    edges {
      cursor
      node { id title }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

query GetPhotos($offset: Int, $limit: Int) {
  photos(offset: $offset, limit: $limit) {
    id
    title
  }
}

scalar Upload

type Mutation {
  uploadPhoto(file: Upload!): Photo!
}

// Apollo Upload Client handles this automatically
const [uploadPhoto] = useMutation(UPLOAD_PHOTO);

const wsLink = new WebSocketLink({
  uri: "ws://localhost:3000/graphql"
});

subscription OnPhotoLiked($photoId: ID!) {
  photoLiked(photoId: $photoId) {
    id
    likesCount
  }
}

// Backend: pubsub.publish('PHOTO_LIKED', { photoId, likesCount });
// Frontend: subscription listens for 'PHOTO_LIKED' events

// Merging user service + photo service schemas

// Multiple services, one unified GraphQL API

npx graphql-codegen --config codegen.yml

http://localhost:3000/graphql-playground

// Schema registry, metrics, and debugging tools

🚀 Step 9: Next Steps & Resources

• Try adding new features (comments, user profiles, etc.)
• Learn more about GraphQL and Apollo Client:
• Apollo Client Docs
• GraphQL.org Learn
• Next.js Docs
• Explore the Backend Tutorial for deeper GraphQL understanding

🎉 Congratulations!

You’ve built a modern, full-featured GraphQL frontend that connects to a Rails backend. You now know how to:

• Set up Apollo Client in Next.js
• Connect to a GraphQL backend
• Authenticate users with GraphQL
• Query and mutate data
• Upload files
• Build a beautiful, responsive UI

Keep experimenting and happy coding! 🚀