Come creare un server GraphQL utilizzando i percorsi API Next.js

Next.js ti offre la migliore esperienza di sviluppo con tutte le funzionalità necessarie per la produzione. Fornisce una soluzione semplice per creare la tua API utilizzando le route API Next.js.

In questa guida, impareremo prima cosa sono le API Routes, quindi creeremo un server GraphQL che recupera i dati dall'API Github usando le API Routes Next.js.

Per ottenere il massimo da questo tutorial, è necessaria almeno una conoscenza di base di GraphQL. La conoscenza di Apollo Server aiuterebbe ma non è obbligatoria. Questo tutorial andrebbe a vantaggio di coloro che desiderano estendere le proprie competenze React o Next.js sul lato server ed essere in grado di creare anche la loro prima app full-stack con Next.js e GraphQL.

Quindi, tuffiamoci.

Cosa sono le route API di Next.js?

Next.js è un framework che abilita il rendering di app React sul client e/o sul server. Dalla versione 9, Next.js può ora essere utilizzato per creare API con Node.js, Express, GrapQL e così via. Next.js utilizza il file system per trattare i file all'interno della cartella pages/api come endpoint API. Ciò significa che, ora, sarai in grado di accedere al tuo endpoint API sull'URL https://localhost:3000/api/your-file-name .

Se vieni da React e non hai mai utilizzato Next.js, questo potrebbe creare confusione perché Next.js è un framework React. E come già sappiamo, React viene utilizzato per creare app front-end. Allora perché usare Next.js per le app e le API di back-end?

Bene, Next.js può essere utilizzato sia sul lato client che sul lato server perché è costruito con React, Node.js, Babel e Webpack e, ovviamente, dovrebbe essere utilizzabile anche sul server. Next.js si basa sul server per abilitare i percorsi API e ti consente di utilizzare la tua lingua di backend preferita anche se tecnicamente è un framework React. Spero che tu abbia capito bene.

Finora, abbiamo imparato cosa sono le API Routes. Tuttavia, la vera domanda rimane: perché usare Next.js per costruire un Server GraphQL ? Perché non utilizzare GraphQL o Node.js per farlo? Quindi, confrontiamo le route API Next.js con le soluzioni esistenti per la creazione di API nella sezione successiva.

Percorsi API Next.js rispetto a REST e GraphQL

GraphQL e REST sono ottimi modi per creare API. Sono super popolari e utilizzati da quasi tutti gli sviluppatori al giorno d'oggi. Quindi, perché utilizzare un framework React per creare API? Bene, la risposta rapida è che le route API di Next.js hanno uno scopo diverso perché le route API ti consentono di estendere la tua app Next.js aggiungendo un back-end ad essa.

Esistono soluzioni migliori per la creazione di API come Node.js, Express, GraphQL e così via poiché si concentrano sul back-end. A mio parere, le rotte API dovrebbero essere accoppiate con un lato client per creare un'app full-stack con Next.js. Usare le API Routes per costruire una semplice API è come sottoutilizzare la potenza di Next.js perché è un framework React che ti consente di aggiungere un back-end in pochissimo tempo.

Considera il caso d'uso in cui è necessario aggiungere l'autenticazione a un'app successiva esistente. Invece di creare la parte auth da zero con Node.js o GraphQL, puoi utilizzare le route API per aggiungere l'autenticazione alla tua app e sarà ancora disponibile sull'endpoint https://localhost:3000/api/your-file-name . Le route API non aumenteranno le dimensioni del bundle lato client perché sono bundle solo lato server.

Tuttavia, le route API Next.js sono accessibili solo all'interno della stessa origine perché le route API non specificano le intestazioni Cross-Origin Resource Sharing (CORS). Puoi comunque modificare il comportamento predefinito aggiungendo CORS alla tua API, ma è una configurazione extra. Se generi la tua prossima app in modo statico utilizzando next export , non sarai in grado di utilizzare percorsi API all'interno della tua app.

Finora, abbiamo appreso quando le rotte API potrebbero essere una soluzione migliore rispetto a simili. Ora, sporchiamoci le mani e iniziamo a costruire il nostro server GraphQL.

Impostare

Per avviare una nuova app con Next.js, andremo a Create Next App. È anche possibile configurare manualmente una nuova app con Webpack. Sei più che benvenuto a farlo. Detto questo, apri la tua interfaccia della riga di comando ed esegui questo comando:

 npx create-next-app next-graphql-server

Next.js fornisce un modello di partenza per i percorsi API. Puoi usarlo eseguendo il seguente comando:

 npx create-next-app --example api-routes api-routes-app

In questo tutorial, vogliamo fare tutto da zero, motivo per cui utilizziamo Crea l'app successiva per avviare una nuova app e non il modello iniziale. Ora, struttura il progetto come segue:

 ├── pages | ├── api | | ├── graphql.js | | ├── resolvers | | | └── index.js | | └── schemas | | └── index.js | └── index.js ├── package.json └── yarn.lock

Come abbiamo detto in precedenza, la cartella api è dove risiede la nostra API o server. Poiché utilizzeremo GraphQL, abbiamo bisogno di un risolutore e di uno schema per creare un server GraphQL. L'endpoint del server sarà accessibile nel percorso /api/graphql , che è il punto di ingresso del server GraphQL.

Con questo passo avanti, ora possiamo creare lo schema GraphQL per il nostro server.

Crea gli schemi GraphQL

Come breve riassunto, uno schema GraphQL definisce la forma del grafico dei dati.

Successivamente, è necessario installare apollo-server-micro per utilizzare Apollo Server all'interno di Next.js.

 yarn add apollo-server-micro

Per npm

 npm install apollo-server-micro

Ora creiamo un nuovo schema GraphQL.

In api/schemas/index.js

 import { gql } from "apollo-server-micro"; export const typeDefs = gql` type User { id: ID login: String avatar_url: String } type Query { getUsers: [User] getUser(name: String!): User! }`

Qui, definiamo un tipo di User che descrive la forma di un utente Github. Si aspetta un id di tipo ID , un login e un avatar_url di tipo String. Quindi, utilizziamo il tipo nella query getUsers che deve restituire un array di utenti. Successivamente, ci affidiamo alla query getUser per recuperare un singolo utente. Deve ricevere il nome dell'utente per poterlo recuperare.

Con questo schema GraphQL creato, ora possiamo aggiornare il file del risolutore e creare le funzioni per eseguire queste query sopra.

Crea i risolutori GraphQL

Un risolutore GraphQL è un insieme di funzioni che consente di generare una risposta da una query GraphQL.

Per richiedere dati dall'API Github, è necessario installare la libreria axios . Quindi, apri la tua CLI ed esegui questo comando:

 yarn add axios

O quando si utilizza npm

 npm install axios

Una volta installata la libreria, aggiungiamo ora del codice significativo al file dei risolutori.

In api/resolvers/index.js

 import axios from "axios"; export const resolvers = { Query: { getUsers: async () => { try { const users = await axios.get("https://api.github.com/users"); return users.data.map(({ id, login, avatar_url }) => ({ id, login, avatar_url })); } catch (error) { throw error; } }, getUser: async (_, args) => { try { const user = await axios.get( `https://api.github.com/users/${args.name}` ); return { id: user.data.id, login: user.data.login, avatar_url: user.data.avatar_url }; } catch (error) { throw error; } } } };

Come puoi vedere qui, abbiniamo il nome delle query definito in precedenza sullo schema GraphQL con le funzioni del risolutore. La funzione getUsers ci consente di recuperare tutti gli utenti dall'API e quindi restituire un array di utenti che deve rispecchiare il tipo di User . Successivamente, utilizziamo il metodo getUser per recuperare un singolo utente con l'aiuto del nome passato come parametro.

Con questo in atto, ora abbiamo uno schema GraphQL e un risolutore GraphQL: è ora di combinarli e creare il server GraphQL.

Crea il server GraphQL

Un server GraphQL espone i tuoi dati come API GraphQL. Offre alle app dei clienti il ​​potere di richiedere esattamente i dati di cui hanno bisogno e nient'altro.

In api/graphql.js

 import { ApolloServer } from "apollo-server-micro"; import { typeDefs } from "./schemas"; import { resolvers } from "./resolvers"; const apolloServer = new ApolloServer({ typeDefs, resolvers }); export const config = { api: { bodyParser: false } }; export default apolloServer.createHandler({ path: "/api/graphql" });

Dopo aver importato ApolloServer , lo usiamo per creare una nuova istanza e quindi passiamo lo schema e il risolutore per creare un server GraphQL. Successivamente, dobbiamo dire a Next.js di non analizzare la richiesta in arrivo e lasciare che GraphQL la gestisca per noi. Infine, utilizziamo apolloServer per creare un nuovo gestore, il che significa che il percorso /api/graphql fungerà da punto di ingresso per il nostro server GraphQL.

A differenza del normale Apollo Server, Next.js gestisce per noi l'avvio del server poiché si basa sul rendering lato server. Ecco perché, qui, non dobbiamo avviare il server GraphQL da soli.

Grande! Con questo passo avanti, possiamo ora verificare se il server GraphQL funziona.

Testare il server GraphQL

Dopo aver individuato la radice del progetto, aprirlo sulla CLI, quindi eseguire questo comando:

 yarn dev

O per npm

 npm run dev

Ora, visita https://localhost:3000/api/graphql e aggiungi la query GraphQL di seguito per recuperare tutti gli utenti da Github.

 { getUsers { id login avatar_url } }

Verifichiamo se possiamo recuperare un singolo utente con questa query.

 query($name: String!){ getUser(name:$name){ login id avatar_url } }

Grande! Il nostro server funziona come previsto. Abbiamo finito di creare un server GraphQL utilizzando le route API Next.js.

Conclusione

In questo tutorial, abbiamo esaminato le route API di Next.js spiegando prima cosa sono e quindi creando un server GraphQL con Next.js. La possibilità di aggiungere un back-end alle app Next.js è una caratteristica davvero interessante. Ci permette di estendere le nostre app con un vero backend. Puoi anche andare oltre e connettere un database per creare un'API completa utilizzando i percorsi API. Next.js semplifica sicuramente la creazione di un'app full-stack con le API Routes.

Puoi visualizzare in anteprima il progetto finito su CodeSandbox.

Grazie per aver letto!

Ulteriori risorse

Queste utili risorse ti porteranno oltre lo scopo di questo tutorial.

• Presentazione delle route API (Next.js 9)
• Percorsi API Next.js
• Middleware dei percorsi API