Setting Up Your First GraphQL Server

You will build a working GraphQL server with Node.js and Apollo Server. By the end of this topic, you will have a server running on your machine that accepts GraphQL queries.

What You Need

Install Node.js version 16 or later from nodejs.org. Node.js comes with npm, the package manager. Open a terminal and verify both are installed.

  node --version    # Should print v16 or higher
  npm --version     # Should print 6 or higher

Project Setup

Create a new folder for your project and initialize it.

  mkdir my-graphql-server
  cd my-graphql-server
  npm init -y
  npm install @apollo/server graphql

The graphql package is the core GraphQL engine. @apollo/server is the server framework that handles HTTP, parsing, and routing.

The Three Parts of Every GraphQL Server

  ┌──────────────────────────────────────────┐
  │  1. SCHEMA                               │
  │  Describes what data exists and          │
  │  what operations are allowed             │
  ├──────────────────────────────────────────┤
  │  2. RESOLVERS                            │
  │  Functions that provide the actual data  │
  │  for each field in the schema            │
  ├──────────────────────────────────────────┤
  │  3. SERVER                               │
  │  Listens for HTTP requests and connects  │
  │  the schema + resolvers together         │
  └──────────────────────────────────────────┘

Write the Server File

Create a file called index.js in your project folder with this content:

  import { ApolloServer } from '@apollo/server';
  import { startStandaloneServer } from '@apollo/server/standalone';

  // 1. Define the schema
  const typeDefs = `#graphql
    type Book {
      title: String
      author: String
    }

    type Query {
      books: [Book]
    }
  `;

  // 2. Define sample data
  const books = [
    { title: 'The Hobbit', author: 'J.R.R. Tolkien' },
    { title: 'Dune',       author: 'Frank Herbert'  },
  ];

  // 3. Define resolvers
  const resolvers = {
    Query: {
      books: () => books,
    },
  };

  // 4. Create and start the server
  const server = new ApolloServer({ typeDefs, resolvers });

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

  console.log('Server running at: ' + url);

Enable ES Modules

Open package.json and add "type": "module" so Node.js understands the import syntax.

  {
    "type": "module",
    "dependencies": {
      "@apollo/server": "...",
      "graphql": "..."
    }
  }

Run the Server

  node index.js
  # Output: Server running at: http://localhost:4000/

Open http://localhost:4000 in your browser. Apollo Server displays a built-in query playground called Apollo Sandbox. You can type and run queries directly in the browser.

Your First Query in the Playground

Type this in the playground and press the Run button:

  {
    books {
      title
      author
    }
  }

The server responds with:

  {
    "data": {
      "books": [
        { "title": "The Hobbit", "author": "J.R.R. Tolkien" },
        { "title": "Dune",       "author": "Frank Herbert"  }
      ]
    }
  }

What Just Happened

  Browser Query          Server Steps              Response
  ──────────────         ──────────────            ────────
  { books {              1. Parse query            data: {
    title                2. Validate vs schema       books: [
    author               3. Call resolver             {title,
  } }                       (returns books array)     author},
                         4. Assemble JSON             ...
                                                  ]}

Key Points

• Every GraphQL server needs three things: a schema, resolvers, and a server instance.
• Apollo Server connects these three pieces and handles the HTTP layer for you.
• Apollo Sandbox at localhost:4000 lets you test queries in the browser without any extra tools.
• The server validates every query against the schema before calling any resolver.