🚀 GraphQL Server: Apollo Server Setup

🎯 Introduction

Ready to build amazing GraphQL servers with TypeScript? 🎉 Apollo Server is your best friend for creating powerful, type-safe GraphQL APIs that’ll make your applications shine!

You’ll discover how GraphQL transforms your backend development experience. Whether you’re building social media apps 📱, e-commerce platforms 🛒, or complex data dashboards 📊, Apollo Server with TypeScript gives you the superpower of type safety and incredible developer experience.

By the end of this tutorial, you’ll be confidently building production-ready GraphQL servers! Let’s rocket into the GraphQL universe! 🚀

📚 Understanding GraphQL & Apollo Server

🤔 What is GraphQL?

GraphQL is like having a super-smart waiter at a restaurant 🍽️. Instead of bringing you a fixed menu (like REST APIs), GraphQL lets you ask for exactly what you want: “I’ll have the user’s name, email, and their last 5 posts with comments, please!” ✨

In TypeScript terms, GraphQL provides a query language for your API and a runtime for executing those queries. This means you can:

• 🎯 Fetch exactly the data you need
• 🚀 Get multiple resources in a single request
• 🛡️ Enjoy strong typing and validation
• 📖 Auto-generate documentation

💡 Why Use Apollo Server?

Here’s why developers love Apollo Server:

1. Type Safety 🔒: Perfect TypeScript integration
2. Developer Experience 💻: Amazing tooling and introspection
3. Performance ⚡: Built-in caching and optimization
4. Ecosystem 🌟: Huge community and plugin support

Real-world example: Imagine building a social media app 📱. With Apollo Server, you can create one endpoint that handles user profiles, posts, comments, and likes - all with perfect type safety! 🎯

🔧 Basic Setup and Installation

📦 Installing Dependencies

Let’s get our GraphQL server up and running:

# 🎯 Create a new project
mkdir graphql-server-tutorial
cd graphql-server-tutorial
npm init -y

# 🚀 Install Apollo Server and GraphQL
npm install apollo-server-express graphql
npm install -D typescript @types/node ts-node nodemon

# ⚡ Install additional TypeScript utilities
npm install graphql-scalars graphql-tools

🛠️ TypeScript Configuration

Create your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "module": "commonjs",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

📝 Simple Server Example

Let’s create our first GraphQL server:

// 👋 src/server.ts - Our GraphQL adventure begins!
import { ApolloServer } from 'apollo-server-express';
import { gql } from 'apollo-server-express';
import express from 'express';

// 🎨 Define our GraphQL schema
const typeDefs = gql`
  type Query {
    hello: String
    users: [User!]!
  }
  
  type User {
    id: ID!
    name: String!
    email: String!
    emoji: String!
  }
`;

// 🚀 Sample data (in real apps, this comes from a database)
const users = [
  { id: '1', name: 'Alice', email: '[email protected]', emoji: '🚀' },
  { id: '2', name: 'Bob', email: '[email protected]', emoji: '💻' },
  { id: '3', name: 'Charlie', email: '[email protected]', emoji: '🎯' }
];

// 🎯 Define resolvers - these handle the actual data fetching
const resolvers = {
  Query: {
    hello: () => 'Hello GraphQL World! 🌍',
    users: () => users
  }
};

// 🏗️ Create Apollo Server instance
const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: true, // 🔍 Enable GraphQL Playground
  playground: true
});

// 🚀 Start the server
const startServer = async (): Promise<void> => {
  const app = express();
  
  await server.start();
  server.applyMiddleware({ app });
  
  const PORT = process.env.PORT || 4000;
  
  app.listen(PORT, () => {
    console.log(`🚀 Server ready at http://localhost:${PORT}${server.graphqlPath}`);
    console.log(`🎮 GraphQL Playground available!`);
  });
};

startServer().catch(error => {
  console.error('💥 Error starting server:', error);
});

💡 Try it yourself: Start your server with npx ts-node src/server.ts and visit the GraphQL Playground!

💡 Practical Examples

🛒 Example 1: E-commerce Product Catalog

Let’s build a type-safe product catalog:

// 🛍️ src/types.ts - Define our TypeScript types
export interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
  inStock: boolean;
  emoji: string;
  description?: string;
}

export interface CartItem {
  productId: string;
  quantity: number;
  addedAt: Date;
}

// 📦 src/data.ts - Mock database
export const products: Product[] = [
  {
    id: '1',
    name: 'TypeScript Hoodie',
    price: 49.99,
    category: 'clothing',
    inStock: true,
    emoji: '👕',
    description: 'Comfy hoodie for TypeScript lovers!'
  },
  {
    id: '2',
    name: 'GraphQL Mug',
    price: 19.99,
    category: 'accessories',
    inStock: true,
    emoji: '☕',
    description: 'Perfect for your morning coffee and queries!'
  },
  {
    id: '3',
    name: 'React Stickers Pack',
    price: 9.99,
    category: 'accessories',
    inStock: false,
    emoji: '⚛️',
    description: 'Decorate your laptop with React pride!'
  }
];

// 🛒 src/schema.ts - Enhanced schema with products
import { gql } from 'apollo-server-express';

export const typeDefs = gql`
  type Query {
    products: [Product!]!
    product(id: ID!): Product
    productsByCategory(category: String!): [Product!]!
    searchProducts(query: String!): [Product!]!
  }
  
  type Mutation {
    addToCart(productId: ID!, quantity: Int = 1): CartResponse!
    removeFromCart(productId: ID!): CartResponse!
  }
  
  type Product {
    id: ID!
    name: String!
    price: Float!
    category: String!
    inStock: Boolean!
    emoji: String!
    description: String
    formattedPrice: String! # 💡 Computed field
  }
  
  type CartResponse {
    success: Boolean!
    message: String!
    cartItems: [CartItem!]!
  }
  
  type CartItem {
    productId: ID!
    quantity: Int!
    addedAt: String!
    product: Product!
  }
`;

// 🎯 src/resolvers.ts - Type-safe resolvers
import { products, Product, CartItem } from './data';

// 🛒 Simple in-memory cart (use Redis/DB in production!)
let cart: CartItem[] = [];

export const resolvers = {
  Query: {
    // 📦 Get all products
    products: (): Product[] => products,
    
    // 🎯 Get single product by ID
    product: (_: any, { id }: { id: string }): Product | undefined => {
      return products.find(product => product.id === id);
    },
    
    // 🏷️ Filter products by category
    productsByCategory: (_: any, { category }: { category: string }): Product[] => {
      return products.filter(product => 
        product.category.toLowerCase() === category.toLowerCase()
      );
    },
    
    // 🔍 Search products by name or description
    searchProducts: (_: any, { query }: { query: string }): Product[] => {
      const searchTerm = query.toLowerCase();
      return products.filter(product => 
        product.name.toLowerCase().includes(searchTerm) ||
        product.description?.toLowerCase().includes(searchTerm)
      );
    }
  },
  
  Mutation: {
    // ➕ Add item to cart
    addToCart: (_: any, { productId, quantity }: { productId: string; quantity: number }) => {
      const product = products.find(p => p.id === productId);
      
      if (!product) {
        return {
          success: false,
          message: `❌ Product not found!`,
          cartItems: cart
        };
      }
      
      if (!product.inStock) {
        return {
          success: false,
          message: `😔 ${product.emoji} ${product.name} is out of stock!`,
          cartItems: cart
        };
      }
      
      // 🔄 Update existing item or add new one
      const existingItem = cart.find(item => item.productId === productId);
      if (existingItem) {
        existingItem.quantity += quantity;
      } else {
        cart.push({
          productId,
          quantity,
          addedAt: new Date()
        });
      }
      
      return {
        success: true,
        message: `✅ Added ${product.emoji} ${product.name} to cart!`,
        cartItems: cart
      };
    },
    
    // ➖ Remove item from cart
    removeFromCart: (_: any, { productId }: { productId: string }) => {
      const initialLength = cart.length;
      cart = cart.filter(item => item.productId !== productId);
      
      const removed = cart.length < initialLength;
      
      return {
        success: removed,
        message: removed ? '✅ Item removed from cart!' : '❌ Item not found in cart!',
        cartItems: cart
      };
    }
  },
  
  // 🎨 Field resolvers for computed properties
  Product: {
    formattedPrice: (product: Product): string => {
      return `$${product.price.toFixed(2)} 💰`;
    }
  },
  
  CartItem: {
    // 🔗 Resolve the product for each cart item
    product: (cartItem: CartItem): Product | undefined => {
      return products.find(p => p.id === cartItem.productId);
    }
  }
};

🎯 Try it yourself: Query for products and add them to your cart using GraphQL Playground!

🎮 Example 2: Gaming Leaderboard System

Let’s create a fun gaming system:

// 🏆 src/gaming-schema.ts
import { gql } from 'apollo-server-express';

export const gamingTypeDefs = gql`
  extend type Query {
    leaderboard: [Player!]!
    player(id: ID!): Player
    topPlayers(limit: Int = 10): [Player!]!
  }
  
  extend type Mutation {
    createPlayer(input: CreatePlayerInput!): Player!
    updateScore(playerId: ID!, points: Int!): ScoreUpdate!
    addAchievement(playerId: ID!, achievement: String!): Player!
  }
  
  type Player {
    id: ID!
    username: String!
    email: String!
    score: Int!
    level: Int!
    achievements: [String!]!
    avatar: String!
    createdAt: String!
    rank: Int! # 🏆 Computed field
  }
  
  input CreatePlayerInput {
    username: String!
    email: String!
    avatar: String!
  }
  
  type ScoreUpdate {
    success: Boolean!
    message: String!
    player: Player!
    leveledUp: Boolean!
  }
`;

// 🎮 Gaming resolvers
export const gamingResolvers = {
  Query: {
    leaderboard: (): GamingPlayer[] => {
      return gamingPlayers.sort((a, b) => b.score - a.score);
    },
    
    player: (_: any, { id }: { id: string }): GamingPlayer | undefined => {
      return gamingPlayers.find(player => player.id === id);
    },
    
    topPlayers: (_: any, { limit }: { limit: number }): GamingPlayer[] => {
      return gamingPlayers
        .sort((a, b) => b.score - a.score)
        .slice(0, limit);
    }
  },
  
  Mutation: {
    createPlayer: (_: any, { input }: { input: CreatePlayerInput }) => {
      const newPlayer: GamingPlayer = {
        id: Date.now().toString(),
        username: input.username,
        email: input.email,
        score: 0,
        level: 1,
        achievements: ['🌟 Welcome to the Game!'],
        avatar: input.avatar,
        createdAt: new Date().toISOString()
      };
      
      gamingPlayers.push(newPlayer);
      console.log(`🎮 New player joined: ${input.avatar} ${input.username}`);
      
      return newPlayer;
    },
    
    updateScore: (_: any, { playerId, points }: { playerId: string; points: number }) => {
      const player = gamingPlayers.find(p => p.id === playerId);
      
      if (!player) {
        throw new Error('❌ Player not found!');
      }
      
      const oldLevel = player.level;
      player.score += points;
      
      // 📈 Level up every 1000 points
      const newLevel = Math.floor(player.score / 1000) + 1;
      const leveledUp = newLevel > oldLevel;
      
      if (leveledUp) {
        player.level = newLevel;
        player.achievements.push(`🏆 Reached Level ${newLevel}!`);
      }
      
      return {
        success: true,
        message: leveledUp 
          ? `🎉 Level up! ${player.avatar} ${player.username} is now level ${newLevel}!`
          : `✨ +${points} points for ${player.avatar} ${player.username}!`,
        player,
        leveledUp
      };
    }
  },
  
  Player: {
    // 🏆 Calculate player rank
    rank: (player: GamingPlayer): number => {
      const sortedPlayers = gamingPlayers.sort((a, b) => b.score - a.score);
      return sortedPlayers.findIndex(p => p.id === player.id) + 1;
    }
  }
};

🚀 Advanced Concepts

🔐 Authentication & Context

Add authentication to your GraphQL server:

// 🛡️ src/auth.ts - Authentication utilities
import jwt from 'jsonwebtoken';

export interface AuthUser {
  id: string;
  email: string;
  role: 'user' | 'admin';
}

export interface Context {
  user?: AuthUser;
  isAuthenticated: boolean;
}

export const createContext = ({ req }: { req: any }): Context => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  
  if (!token) {
    return { isAuthenticated: false };
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET || 'secret') as AuthUser;
    return {
      user: decoded,
      isAuthenticated: true
    };
  } catch (error) {
    return { isAuthenticated: false };
  }
};

// 🚀 Enhanced server with authentication
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: createContext,
  formatError: (error) => {
    console.error('🚨 GraphQL Error:', error);
    return error;
  }
});

🎯 Custom Scalars & Directives

Add custom types for better validation:

// ✨ src/scalars.ts - Custom scalar types
import { GraphQLScalarType, Kind } from 'graphql';
import { GraphQLError } from 'graphql';

export const EmailType = new GraphQLScalarType({
  name: 'Email',
  description: 'Email custom scalar type',
  serialize(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    return value;
  },
  parseValue(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(value)) {
      throw new GraphQLError('Invalid email format 📧');
    }
    
    return value;
  },
  parseLiteral(ast): string {
    if (ast.kind !== Kind.STRING) {
      throw new GraphQLError('Email must be a string literal');
    }
    return ast.value;
  }
});

// 🎨 Enhanced schema with custom scalars
const advancedTypeDefs = gql`
  scalar Email
  scalar DateTime
  
  type User {
    id: ID!
    name: String!
    email: Email! # 🎯 Using our custom scalar
    createdAt: DateTime!
  }
`;

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: N+1 Query Problem

// ❌ This causes N+1 queries - avoid this!
const badResolvers = {
  User: {
    posts: async (user: User) => {
      // 💥 This runs a separate query for each user!
      return await Post.findByUserId(user.id);
    }
  }
};

// ✅ Use DataLoader to batch requests!
import DataLoader from 'dataloader';

const postLoader = new DataLoader(async (userIds: string[]) => {
  const posts = await Post.findByUserIds(userIds);
  // 🎯 Group posts by user ID
  return userIds.map(userId => 
    posts.filter(post => post.userId === userId)
  );
});

const goodResolvers = {
  User: {
    posts: (user: User) => postLoader.load(user.id) // ✅ Batched!
  }
};

🤯 Pitfall 2: Not Handling Errors Properly

// ❌ Poor error handling
const badResolver = {
  product: async (_: any, { id }: { id: string }) => {
    const product = await db.findProduct(id);
    return product; // 💥 What if product is null?
  }
};

// ✅ Proper error handling with meaningful messages
const goodResolver = {
  product: async (_: any, { id }: { id: string }) => {
    try {
      const product = await db.findProduct(id);
      
      if (!product) {
        throw new GraphQLError(
          `🔍 Product with ID ${id} not found!`,
          { extensions: { code: 'PRODUCT_NOT_FOUND' } }
        );
      }
      
      return product;
    } catch (error) {
      console.error('Database error:', error);
      throw new GraphQLError('💥 Something went wrong fetching the product!');
    }
  }
};

🛠️ Best Practices

1. 🎯 Use TypeScript Types: Generate types from your schema with GraphQL Code Generator
2. 🔐 Secure Your Queries: Implement query depth limiting and rate limiting
3. 📊 Monitor Performance: Use Apollo Studio for real-time monitoring
4. 🚀 Cache Strategically: Implement caching at resolver and response levels
5. ✅ Test Thoroughly: Write unit tests for resolvers and integration tests for queries

// 🎯 Example with GraphQL Code Generator types
import { Resolvers } from './generated/graphql';

const typedResolvers: Resolvers = {
  Query: {
    users: () => users, // ✅ Fully typed!
  },
  User: {
    posts: (user) => getPosts(user.id) // ✅ TypeScript knows user structure!
  }
};

🧪 Hands-On Exercise

🎯 Challenge: Build a Social Media GraphQL API

Create a complete social media backend with GraphQL:

📋 Requirements:

• ✅ Users can register and login 🔐
• ✅ Users can create, edit, and delete posts 📝
• ✅ Users can follow/unfollow other users 👥
• ✅ Users can like and comment on posts 💬
• ✅ Real-time subscriptions for new posts 🔄
• ✅ Each feature needs proper emoji representation! 🎨

🚀 Bonus Points:

• Add image upload for posts 📸
• Implement hashtag system 🏷️
• Create trending posts algorithm 📈
• Add notification system 🔔

💡 Solution

// 🎯 Complete social media GraphQL server!
import { gql } from 'apollo-server-express';

const socialMediaTypeDefs = gql`
  type Query {
    me: User
    posts: [Post!]!
    post(id: ID!): Post
    users: [User!]!
    trendingPosts: [Post!]!
  }
  
  type Mutation {
    register(input: RegisterInput!): AuthPayload!
    login(input: LoginInput!): AuthPayload!
    createPost(input: CreatePostInput!): Post!
    likePost(postId: ID!): Post!
    addComment(postId: ID!, content: String!): Comment!
    followUser(userId: ID!): User!
  }
  
  type Subscription {
    postAdded: Post!
    commentAdded(postId: ID!): Comment!
  }
  
  type User {
    id: ID!
    username: String!
    email: String!
    avatar: String!
    bio: String
    posts: [Post!]!
    followers: [User!]!
    following: [User!]!
    followerCount: Int!
    followingCount: Int!
    createdAt: String!
  }
  
  type Post {
    id: ID!
    content: String!
    author: User!
    likes: [User!]!
    comments: [Comment!]!
    likeCount: Int!
    commentCount: Int!
    hashtags: [String!]!
    createdAt: String!
    updatedAt: String!
  }
  
  type Comment {
    id: ID!
    content: String!
    author: User!
    post: Post!
    createdAt: String!
  }
  
  type AuthPayload {
    token: String!
    user: User!
  }
  
  input RegisterInput {
    username: String!
    email: String!
    password: String!
    avatar: String!
  }
  
  input LoginInput {
    email: String!
    password: String!
  }
  
  input CreatePostInput {
    content: String!
  }
`;

// 🚀 Social media resolvers with type safety
const socialMediaResolvers = {
  Query: {
    me: (_: any, __: any, context: Context) => {
      if (!context.isAuthenticated) {
        throw new GraphQLError('🔐 Please log in first!');
      }
      return getUserById(context.user!.id);
    },
    
    posts: () => getAllPosts(),
    
    trendingPosts: () => {
      return getAllPosts()
        .sort((a, b) => b.likeCount - a.likeCount)
        .slice(0, 10);
    }
  },
  
  Mutation: {
    createPost: async (_: any, { input }: { input: CreatePostInput }, context: Context) => {
      if (!context.isAuthenticated) {
        throw new GraphQLError('🔐 Please log in to create posts!');
      }
      
      // 🏷️ Extract hashtags from content
      const hashtags = input.content.match(/#\w+/g) || [];
      
      const post = await createPost({
        ...input,
        authorId: context.user!.id,
        hashtags: hashtags.map(tag => tag.slice(1)) // Remove #
      });
      
      // 🔄 Publish to subscribers
      pubsub.publish('POST_ADDED', { postAdded: post });
      
      return post;
    },
    
    likePost: async (_: any, { postId }: { postId: string }, context: Context) => {
      if (!context.isAuthenticated) {
        throw new GraphQLError('🔐 Please log in to like posts!');
      }
      
      const post = await toggleLike(postId, context.user!.id);
      return post;
    }
  },
  
  Subscription: {
    postAdded: {
      subscribe: () => pubsub.asyncIterator(['POST_ADDED'])
    }
  },
  
  // 🎨 Field resolvers
  Post: {
    likeCount: (post: Post) => post.likes.length,
    commentCount: (post: Post) => post.comments.length,
    hashtags: (post: Post) => post.hashtags.map(tag => `#${tag}`)
  },
  
  User: {
    followerCount: (user: User) => user.followers.length,
    followingCount: (user: User) => user.following.length
  }
};

console.log('🎉 Social media GraphQL server ready!');

🎓 Key Takeaways

You’ve mastered GraphQL with Apollo Server! Here’s what you can now do:

• ✅ Create GraphQL servers with confidence and type safety 💪
• ✅ Design flexible schemas that adapt to client needs 🛡️
• ✅ Implement resolvers like a pro developer 🎯
• ✅ Handle authentication and advanced features 🐛
• ✅ Build production-ready APIs with TypeScript! 🚀

Remember: GraphQL isn’t just a query language - it’s a new way of thinking about APIs that puts the client in control! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered Apollo Server with TypeScript!

Here’s your journey forward:

1. 💻 Build a complete GraphQL API for your next project
2. 🚀 Explore GraphQL subscriptions for real-time features
3. 📚 Learn about GraphQL federation for microservices
4. 🌟 Contribute to the GraphQL community!

Your GraphQL adventure is just beginning! Keep querying, keep building, and remember - with great power comes great responsibility! 🕷️🚀

Happy GraphQL coding! 🎉🚀✨