Concepto clave

Inicializar un proyecto Next.js con Apollo Server es como construir los cimientos de un edificio moderno donde la fachada (Next.js) y la estructura interna (Apollo Server) trabajan juntas desde el primer día. En arquitectura de software, esto representa la integración full-stack donde el frontend y el backend comparten el mismo entorno de desarrollo, permitiendo una comunicación más eficiente entre equipos y reduciendo la complejidad de despliegue.

Imagina que estás construyendo una aplicación de mensajería en tiempo real. Next.js sería la interfaz que los usuarios ven - rápida, optimizada y con renderizado del lado del servidor. Apollo Server sería el sistema de tuberías que transporta los mensajes entre usuarios, con tipado estricto que asegura que cada mensaje llegue en el formato correcto. La magia ocurre cuando ambos sistemas se configuran juntos desde el inicio, creando un entorno donde los cambios en el esquema GraphQL se reflejan inmediatamente en el frontend.

Cómo funciona en la práctica

Vamos a crear un proyecto desde cero que servirá como base para nuestra API GraphQL tipada. Sigue estos pasos fundamentales:

Crear el proyecto Next.js: Abre tu terminal y ejecuta npx create-next-app@latest mi-proyecto-graphql --typescript --tailwind --app. Esto genera una estructura con TypeScript y el App Router de Next.js 14+.
Instalar dependencias de Apollo: Navega a la carpeta del proyecto y ejecuta npm install @apollo/server graphql. Estas son las herramientas esenciales para construir nuestro servidor GraphQL.
Configurar Apollo Server en Next.js: Crea un archivo app/api/graphql/route.ts que contendrá la configuración principal. Aquí es donde definiremos nuestro esquema y resolvers.

Un ejemplo básico de configuración inicial:

import { ApolloServer } from '@apollo/server';
import { startServerAndCreateNextHandler } from '@as-integrations/next';
import { gql } from 'graphql';

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hola desde GraphQL!'
  }
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

const handler = startServerAndCreateNextHandler(server);

export { handler as GET, handler as POST };

Caso de estudio

Consideremos una plataforma de e-learning donde necesitamos mostrar cursos y lecciones. Nuestra configuración inicial debe soportar:

Entidad	Campos básicos	Tipo GraphQL
Curso	id, titulo, descripcion	type Course
Leccion	id, titulo, contenido, cursoId	type Lesson

La configuración del esquema inicial se vería así:

const typeDefs = gql`
  type Course {
    id: ID!
    titulo: String!
    descripcion: String
    lecciones: [Lesson!]!
  }

  type Lesson {
    id: ID!
    titulo: String!
    contenido: String!
    curso: Course!
  }

  type Query {
    cursos: [Course!]!
    curso(id: ID!): Course
    leccionesPorCurso(cursoId: ID!): [Lesson!]!
  }
`;

La clave aquí es definir relaciones desde el inicio. Notice cómo Lesson tiene un campo 'curso' que referencia al Course padre, estableciendo la base para resolvers complejos.

Errores comunes

Configurar Apollo Server en pages/ en lugar de app/: Next.js 13+ usa el App Router por defecto. Colocar tu servidor GraphQL en la carpeta pages causará conflictos de routing.
Olvidar los tipos de retorno en TypeScript: Apollo Server con TypeScript requiere definiciones explícitas. Siempre define interfaces para tus resolvers.
No configurar CORS para desarrollo: Durante desarrollo, tu frontend y backend corren en puertos diferentes. Configura CORS básico con cors() de Next.js.
Mezclar sintaxis de módulos: Asegúrate de usar consistentemente ES modules (import/export) en todo tu proyecto Next.js.
Ignorar el manejo de errores inicial: Implementa un formato de errores básico desde el inicio para debuggear más fácilmente.

Checklist de dominio

Proyecto Next.js creado con TypeScript y App Router funcionando
Apollo Server instalado y configurado en app/api/graphql/route.ts
Schema GraphQL básico definido con al menos un tipo y query
Resolvers implementados con funciones que retornan datos mock
Playground de GraphQL accesible en http://localhost:3000/api/graphql
Configuración de TypeScript que reconoce tipos GraphQL
Scripts de desarrollo y producción funcionando sin errores

Configurar un servidor GraphQL para una app de tareas

Vas a crear un sistema básico de gestión de tareas con GraphQL. Sigue estos pasos:

Crea un nuevo proyecto Next.js usando el comando oficial con TypeScript y Tailwind
Instala las dependencias necesarias: Apollo Server y GraphQL
Crea el archivo de ruta GraphQL en la ubicación correcta del App Router
Define un schema GraphQL con un tipo Task que tenga: id (ID!), title (String!), completed (Boolean!), y createdAt (String!)
Implementa una query tasks que retorne un array de Task
Crea un resolver que retorne al menos 3 tareas de ejemplo con datos mock
Verifica que el playground de GraphQL funcione en localhost:3000/api/graphql
Agrega una mutación createTask que acepte title y retorne la nueva tarea

Entrega: Un repositorio Git con el código funcionando y captura del playground mostrando las queries funcionando.

Pistas

Recuerda que Next.js 14+ usa el directorio 'app' por defecto, no 'pages'
Usa startServerAndCreateNextHandler para integrar Apollo con Next.js
Define interfaces TypeScript para tus resolvers para mejor autocompletado

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Inicializar un Proyecto Next.js con Apollo Server