Next.js & GraphQL: A Beginner’s Guide to Building Modern Web Apps

Written by

learnmodernwebdevelopment

in

In the ever-evolving landscape of web development, building efficient, scalable, and maintainable applications is paramount. GraphQL, a query language for your API, and Next.js, a React framework for production, offer a powerful combination for creating modern web applications. This tutorial will guide you through the fundamentals of integrating GraphQL into your Next.js projects, empowering you to fetch and manage data effectively.

Understanding the Problem: Data Fetching Challenges

Traditional REST APIs often lead to over-fetching or under-fetching of data. Over-fetching occurs when the server sends more data than the client needs, leading to unnecessary bandwidth usage and slower load times. Under-fetching, on the other hand, happens when the client needs to make multiple requests to retrieve all the required information. This results in increased complexity and potential performance bottlenecks. GraphQL addresses these issues by allowing clients to request precisely the data they need, nothing more, nothing less.

Why GraphQL and Next.js?

Next.js provides a robust and performant environment for building web applications. Its features, such as server-side rendering (SSR), static site generation (SSG), and optimized image handling, contribute to improved SEO, faster initial load times, and a better user experience. GraphQL complements Next.js by providing a flexible and efficient way to fetch data, making it an ideal choice for modern web development. Using GraphQL with Next.js allows you to:

  • Improve Performance: Fetch only the data your components require, reducing network overhead.
  • Enhance Developer Experience: GraphQL’s type system provides clear data contracts and autocompletion, making development smoother.
  • Increase Flexibility: Easily evolve your API without breaking existing clients.
  • Optimize SEO: Server-side rendering with GraphQL can improve search engine rankings.

Setting Up the Development Environment

Before diving into the code, ensure you have the following installed:

  • Node.js and npm (or yarn): Required for managing JavaScript packages.
  • A code editor: Such as Visual Studio Code, Sublime Text, or Atom.

Let’s start by creating a new Next.js project. Open your terminal and run the following command:

npx create-next-app nextjs-graphql-tutorial
cd nextjs-graphql-tutorial

This command creates a new Next.js project named “nextjs-graphql-tutorial” and navigates you into the project directory.

Choosing a GraphQL Server

You’ll need a GraphQL server to serve your data. There are several options available, including:

  • Apollo Server: A popular and versatile GraphQL server.
  • GraphQL Yoga: A lightweight and easy-to-use GraphQL server.
  • Hasura: A GraphQL engine that automatically generates GraphQL APIs from your database.

For this tutorial, we’ll use a simple mock GraphQL server for demonstration purposes. However, the principles apply to any GraphQL server. Create a file named `graphql/schema.js` in your project directory:

// graphql/schema.js
import { buildSchema } from 'graphql';

const schema = buildSchema(`
  type Query {
    hello: String
    books: [Book]
  }

  type Book {
    id: ID!
    title: String!
    author: String!
  }
`);

export default schema;

This code defines a GraphQL schema with a `hello` query and a `books` query. The `Book` type represents a book with an ID, title, and author. Next, create a file named `graphql/resolvers.js`:

// graphql/resolvers.js
const booksData = [
  { id: '1', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald' },
  { id: '2', title: 'Moby Dick', author: 'Herman Melville' },
];

const resolvers = {
  hello: () => 'Hello, world!',
  books: () => booksData,
};

export default resolvers;

This file contains the resolvers for the GraphQL queries. The `hello` resolver returns a simple greeting, and the `books` resolver returns a list of mock book data.

Now, let’s set up a basic GraphQL server within our Next.js application. Create a file named `pages/api/graphql.js`:

// pages/api/graphql.js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import schema from '../../graphql/schema';
import resolvers from '../../graphql/resolvers';

async function startApolloServer() {
  const server = new ApolloServer({
    typeDefs: schema,
    resolvers,
  });

  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
  });

  console.log(`🚀  Server ready at: ${url}`);
}

startApolloServer();

export default async function handler(req, res) {
  res.status(200).json({ message: 'GraphQL server started. Check the console.' });
}

This code sets up an Apollo Server and starts it on port 4000. It uses the schema and resolvers we defined earlier. The `handler` function is a Next.js API route that serves as an entry point.

To run the development server, use:

npm run dev

After running the server, you should see a message in your console indicating that the GraphQL server is ready. You can access the GraphQL playground at `http://localhost:4000` to test your queries.

Fetching Data with GraphQL in Next.js

Now that we have a GraphQL server running, let’s fetch data from it within our Next.js application. We’ll use the `graphql-request` library, a lightweight GraphQL client.

Install the library using npm or yarn:

npm install graphql-request

Next, create a new component or modify an existing one (e.g., `pages/index.js`) to fetch and display the data. Here’s an example:

// pages/index.js
import { useState, useEffect } from 'react';
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('http://localhost:4000'); // Replace with your server URL

const GET_BOOKS = gql`
  query GetBooks {
    books {
      id
      title
      author
    }
  }
`;

export default function Home() {
  const [books, setBooks] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const data = await client.request(GET_BOOKS);
        setBooks(data.books);
      } catch (err) {
        setError(err);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h2>Book List</h2>
      <ul>
        {books.map((book) => (
          <li>
            {book.title} by {book.author}
          </li>
        ))}
      </ul>
    </div>
  );
}

In this example:

  • We import `GraphQLClient` and `gql` from `graphql-request`.
  • We create a `GraphQLClient` instance, pointing to our GraphQL server.
  • We define a GraphQL query (`GET_BOOKS`) using the `gql` template literal.
  • We use the `useEffect` hook to fetch the data when the component mounts.
  • Inside the `useEffect` hook, we use `client.request()` to send the query to the server and update the component’s state with the fetched data.
  • We render the book data in a list.

Save the file and check your browser. You should now see the list of books fetched from your GraphQL server.

Error Handling

Robust error handling is crucial for a production-ready application. When fetching data, always consider potential errors. The provided example includes basic error handling using a `try…catch` block. You can enhance this by:

  • Displaying user-friendly error messages: Instead of raw error messages, provide clear and informative messages to the user.
  • Logging errors: Log errors to your server for debugging and monitoring.
  • Implementing retry mechanisms: If the request fails due to a temporary issue, retry the request after a delay.
  • Using a dedicated error boundary component: Catch errors in child components and display a fallback UI.

Here’s an example of improved error handling:


// pages/index.js
import { useState, useEffect } from 'react';
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('http://localhost:4000');

const GET_BOOKS = gql`
  query GetBooks {
    books {
      id
      title
      author
    }
  }
`;

export default function Home() {
  const [books, setBooks] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const data = await client.request(GET_BOOKS);
        setBooks(data.books);
      } catch (err) {
        console.error('GraphQL Error:', err);
        setError('Failed to fetch books. Please try again later.');
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <div>
      <h2>Book List</h2>
      <ul>
        {books.map((book) => (
          <li>
            {book.title} by {book.author}
          </li>
        ))}
      </ul>
    </div>
  );
}

Server-Side Rendering (SSR) with GraphQL

Server-side rendering (SSR) is a powerful feature of Next.js that can significantly improve SEO and initial load times. With SSR, the server renders the initial HTML for your page, including the data fetched from your GraphQL API. This allows search engine crawlers to easily index your content and provides a faster user experience.

To implement SSR with GraphQL, you’ll use the `getServerSideProps` function in your Next.js page component. This function runs on the server before the page is rendered. Here’s how to fetch data using GraphQL within `getServerSideProps`:


// pages/ssr-books.js
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('http://localhost:4000');

const GET_BOOKS = gql`
  query GetBooks {
    books {
      id
      title
      author
    }
  }
`;

export async function getServerSideProps() {
  try {
    const data = await client.request(GET_BOOKS);
    return {
      props: { books: data.books },
    };
  } catch (error) {
    console.error('GraphQL SSR Error:', error);
    return {
      props: { books: [], error: 'Failed to fetch books' },
    };
  }
}

export default function SSRBooks({ books, error }) {
  if (error) return <p>Error: {error}</p>;

  return (
    <div>
      <h2>Book List (SSR)</h2>
      <ul>
        {books.map((book) => (
          <li>
            {book.title} by {book.author}
          </li>
        ))}
      </ul>
    </div>
  );
}

In this example:

  • We define the same `GET_BOOKS` query.
  • We define the `getServerSideProps` function, which fetches the data from the GraphQL server.
  • We return the fetched data as props to the component.
  • We handle potential errors within `getServerSideProps`.
  • In the component, we access the `books` prop and render the list.

Static Site Generation (SSG) with GraphQL

Static Site Generation (SSG) is another powerful feature of Next.js that can significantly improve performance. With SSG, the HTML is generated at build time, and served directly from a CDN. This is ideal for content that doesn’t change frequently. You can integrate GraphQL with SSG using the `getStaticProps` function.

Here’s how to fetch data using GraphQL within `getStaticProps`:


// pages/ssg-books.js
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('http://localhost:4000');

const GET_BOOKS = gql`
  query GetBooks {
    books {
      id
      title
      author
    }
  }
`;

export async function getStaticProps() {
  try {
    const data = await client.request(GET_BOOKS);
    return {
      props: { books: data.books },
      revalidate: 10, // Revalidate the data every 10 seconds
    };
  } catch (error) {
    console.error('GraphQL SSG Error:', error);
    return {
      props: { books: [], error: 'Failed to fetch books' },
      revalidate: 10,
    };
  }
}

export default function SSGBooks({ books, error }) {
  if (error) return <p>Error: {error}</p>;

  return (
    <div>
      <h2>Book List (SSG)</h2>
      <ul>
        {books.map((book) => (
          <li>
            {book.title} by {book.author}
          </li>
        ))}
      </ul>
    </div>
  );
}

In this example:

  • We define the same `GET_BOOKS` query.
  • We define the `getStaticProps` function, which fetches the data from the GraphQL server during the build process.
  • We return the fetched data as props to the component.
  • We handle potential errors within `getStaticProps`.
  • We use the `revalidate` option to configure Incremental Static Regeneration (ISR), which allows Next.js to regenerate the page at a specified interval.
  • In the component, we access the `books` prop and render the list.

Common Mistakes and How to Fix Them

When integrating GraphQL with Next.js, you might encounter some common issues. Here are a few and how to address them:

  • Incorrect GraphQL Endpoint: Double-check that your GraphQL client is configured with the correct URL of your GraphQL server. A typo in the URL can prevent data fetching.
  • Schema Errors: Ensure your GraphQL schema is correctly defined on the server-side. Errors in the schema will cause queries to fail. Use a tool like the GraphQL Playground to test your queries and validate your schema.
  • CORS Issues: If your Next.js application and GraphQL server are on different domains, you might encounter Cross-Origin Resource Sharing (CORS) issues. Configure your server to allow requests from your Next.js application’s origin, or use a proxy.
  • Incorrect Query Syntax: GraphQL queries are case-sensitive and have a specific syntax. Use a GraphQL IDE (like the Playground) to test your queries before implementing them in your Next.js components.
  • Missing Dependencies: Make sure you have installed all necessary dependencies, such as `graphql-request` and any libraries required by your GraphQL server.

Advanced Topics

Once you’re comfortable with the basics, you can explore more advanced topics:

  • GraphQL Mutations: Learn how to use mutations to modify data on your server (e.g., creating, updating, or deleting books).
  • Pagination: Implement pagination to handle large datasets efficiently.
  • Subscriptions: Use GraphQL subscriptions for real-time updates.
  • Authentication and Authorization: Secure your GraphQL API with authentication and authorization mechanisms.
  • Caching: Implement caching strategies to improve performance and reduce server load.

Key Takeaways

  • GraphQL offers a more efficient and flexible way to fetch data compared to traditional REST APIs.
  • Next.js provides a robust and performant environment for building web applications.
  • Integrating GraphQL with Next.js involves setting up a GraphQL server, using a GraphQL client, and fetching data in your components.
  • Server-side rendering (SSR) and Static Site Generation (SSG) with GraphQL can improve SEO and performance.
  • Always handle errors and consider advanced topics like mutations, pagination, and authentication for more complex applications.

FAQ

Here are some frequently asked questions about using GraphQL with Next.js:

  1. What is the difference between GraphQL and REST?

    REST APIs typically fetch all the data for a resource, even if the client only needs a subset. GraphQL allows clients to request specific data, reducing over-fetching and improving performance. GraphQL also provides a type system and a query language, making it more flexible and developer-friendly.

  2. How do I choose between SSR and SSG with GraphQL?

    Choose SSR if your data changes frequently and needs to be up-to-date. Choose SSG if your data is relatively static and doesn’t change often. SSG provides better performance and SEO, while SSR offers more flexibility for dynamic content.

  3. What is Apollo Client, and why didn’t you use it?

    Apollo Client is a popular GraphQL client library. While it offers advanced features like caching and state management, this tutorial used `graphql-request` for simplicity and to focus on the core concepts of fetching data with GraphQL in Next.js. You can certainly use Apollo Client in your Next.js projects if you need its advanced features.

  4. How can I debug GraphQL queries in Next.js?

    Use the GraphQL Playground (if your server provides one) to test your queries and validate your schema. Check your browser’s developer console for any network errors or GraphQL-related errors. Use `console.log` statements to debug your code and inspect the data fetched from the API.

By using GraphQL with Next.js, you have the potential to build performant, maintainable, and scalable web applications. The combination of Next.js’s powerful features and GraphQL’s efficient data fetching capabilities makes for a great development experience. Remember to always consider error handling, performance optimization, and the specific needs of your project as you continue to build out your applications. With the knowledge gained from this guide, you are well-equipped to start building modern web applications with GraphQL and Next.js.

More posts