Configurar un servidor de GraphQL dentro de una aplicación de Node.js con Express es más sencillo de lo que parece. Con apenas dos dependencias y unas pocas líneas de código, puedes tener un playground funcional donde ejecutar consultas en tiempo real. A continuación se explica paso a paso cómo lograrlo.
¿Qué dependencias necesitas para montar GraphQL en Node.js?
El punto de partida es instalar las librerías necesarias. Se requieren únicamente dos paquetes [0:30]:
- graphql: la implementación directa de JavaScript para usar GraphQL en un servidor de Node.
- apollo-server-express: una extensión que facilita servir GraphQL dentro de una aplicación Express.
Además, existe un paquete llamado apollo-server-core que ya viene incluido dentro de apollo-server-express, por lo que no es necesario instalarlo de forma explícita [1:30]. De este paquete se importa el plugin ApolloServerPluginLandingPageGraphQLPlayground, que habilita un entorno visual donde puedes ejecutar y probar tus consultas.
¿Cómo se estructura la configuración inicial de GraphQL?
Dentro del proyecto se crea una carpeta llamada graphql con un archivo index.js [1:10]. Allí se definen tres elementos fundamentales.
¿Qué son los type definitions?
La definición de tipos (typeDefs) describe la estructura de los datos que GraphQL puede devolver [2:00]. Se escribe como un string usando backticks y sigue la sintaxis propia de GraphQL:
javascript
const typeDefs = type Query { hello: String };
Este bloque declara un tipo Query con un campo hello que retorna un String. Es el esquema mínimo que Apollo Server requiere para iniciar. Sin al menos una definición de tipo, el servidor arrojará un error indicando que necesita un esquema [6:08].
¿Qué papel cumplen los resolvers?
Los resolvers son funciones que resuelven cada campo definido en los tipos [2:40]. Van ligados directamente a la definición de tipos y contienen la lógica que genera la respuesta:
javascript
const resolvers = {
Query: {
hello: () => 'Hola mundo'
}
};
Cuando alguien consulte hello, el resolver correspondiente ejecutará la función y devolverá el string "Hola mundo".
¿Cómo se crea e inicializa el servidor con Apollo?
Se define una función useGraphQL que recibe la aplicación de Express como parámetro [3:10]. Dentro de ella se crea una instancia de ApolloServer pasándole los typeDefs, los resolvers, la activación del playground y el plugin correspondiente:
javascript
const useGraphQL = async (app) => {
const server = new ApolloServer({
typeDefs,
resolvers,
playground: true,
plugins: [ApolloServerPluginLandingPageGraphQLPlayground()]
});
await server.start();
server.applyMiddleware({ app });
};
El método server.start() devuelve una promesa, lo que obliga a usar await y, por tanto, la función debe ser async [3:50]. Después de iniciar, applyMiddleware liga el servidor GraphQL a la aplicación Express que ya está corriendo.
¿Cómo se integra GraphQL con la aplicación Express existente?
En el archivo principal de la aplicación (app), donde ya existe un sistema de routing, se importa la función useGraphQL y se invoca pasándole la instancia de Express [4:20]. El patrón es similar al que se usa con las rutas: en un caso se montan endpoints REST y en el otro se monta el servidor GraphQL.
Como useGraphQL es asíncrona, la función que la contiene también debe marcarse como async y usar await [5:10]. Esto provoca un efecto en cadena: si createApp se vuelve asíncrona, en el archivo index.js principal se necesita una IIFE (Immediately Invoked Function Expression), es decir, una función anónima que se ejecuta a sí misma [5:30]:
javascript
(async () => {
await createApp();
})();
Esta técnica permite usar await en el nivel superior del archivo sin problemas.
Una vez que todo está conectado, al ejecutar npm run dev el servidor se levanta. En el navegador, accediendo a localhost:3000/graphql, aparece el playground de GraphQL [6:40]. Allí puedes escribir tu primera consulta:
graphql
{
hello
}
Y la respuesta será "Hola mundo" [7:00], confirmando que el servidor funciona correctamente.
Un detalle importante que surgió durante la configuración fue un error común: escribir typeDef en singular en lugar de typeDefs en plural [6:15]. Apollo Server espera la propiedad en plural porque representa múltiples definiciones de tipo, y sin ella no encuentra el esquema principal.
Con el servidor activo y el playground disponible, el siguiente paso natural es aprender a consumir este servidor GraphQL desde otras aplicaciones. ¿Ya probaste tu primera consulta? Comparte tu experiencia en los comentarios.
