Inicializar un Proyecto Next.js con Apollo Server

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:

1. 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+.
2. 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.
3. 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

1. Proyecto Next.js creado con TypeScript y App Router funcionando
2. Apollo Server instalado y configurado en app/api/graphql/route.ts
3. Schema GraphQL básico definido con al menos un tipo y query
4. Resolvers implementados con funciones que retornan datos mock
5. Playground de GraphQL accesible en http://localhost:3000/api/graphql
6. Configuración de TypeScript que reconoce tipos GraphQL
7. 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:

1. Crea un nuevo proyecto Next.js usando el comando oficial con TypeScript y Tailwind
2. Instala las dependencias necesarias: Apollo Server y GraphQL
3. Crea el archivo de ruta GraphQL en la ubicación correcta del App Router
4. Define un schema GraphQL con un tipo Task que tenga: id (ID!), title (String!), completed (Boolean!), y createdAt (String!)
5. Implementa una query tasks que retorne un array de Task
6. Crea un resolver que retorne al menos 3 tareas de ejemplo con datos mock
7. Verifica que el playground de GraphQL funcione en localhost:3000/api/graphql
8. 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.

Práctica acompañada: Una interfaz web de principio a fin

Estado, formularios y una API pequeña. Usa este cuaderno como práctica complementaria de la ruta; el material original de la lección continúa siendo tu referencia.

Práctica: cuatro pruebas de comportamiento

Prueba un título normal, solo espacios, 121 caracteres y una falla de red simulada. Registra la respuesta y el estado de la interfaz. Repite usando solo teclado: debes llegar al campo, enviarlo y encontrar el error sin usar el ratón.

Después agrega una segunda tarea y cambia el orden de la lista. Comprueba que cada botón sigue actuando sobre el elemento correcto. Si trabajas con microservicios, dibuja qué servicio posee el dato y qué ocurre si la dependencia no responde. No necesitas una infraestructura distribuida para aprender a definir tiempos de espera y errores comprensibles.

Comprueba tu entrega

Entrega el código, el contrato de API y evidencia de las cuatro pruebas. Indica si los datos se guardan o desaparecen al recargar. Una demostración en memoria debe decirlo para que nadie confunda un prototipo con almacenamiento persistente.

• Abrir el cuaderno ilustrado de 7 páginas
• Descargar PDF, ejercicios y plantillas de esta ruta
• MDN: aprendizaje de desarrollo web · recurso externo
• CS50 Web: HTML y CSS · inglés · video complementario externo