Sådan skriver du et Gatsby-kilde-plugin (med kattefakta)

Der er mange gode plugins, der allerede er skrevet til Gatsby. Du skal være i stand til at vælge stort set enhver datakilde, fra lokale Markdown-filer til Wordpress til Contentful, og have noget, der kører temmelig hurtigt. Den måde, du trækker ind data fra en ekstern kilde og omdanner dem til GraphQL-aktiverbare ting er faktisk ret interessant, så i dag vil jeg gerne tage dig fra nul-til-kat-fakta i Gatsby.

“Lavt fokusfotografering af brun kat” af James Sutton på Unsplash

Valg af en API

Der er mange gratis API'er, som du kan spørge efter for eksempel projekter, eller du kan have dine egne, som du vil forbruge i Gatsby. Du kan finde en liste over dem på Todd Motto's GitHub, hvis du vil have et let sted at starte. Jeg vil tage det indlysende valg fra denne liste: Cat Facts.

Plan for angreb

Inden vi kommer i gang, kan jeg godt lide at have en idé om de opgaver, jeg har brug for. Jeg kan godt lide at gøre alt på GitHub og bruge dets funktioner til min fordel. Jeg har skrevet om dette før, hvis du gerne vil have flere detaljer om at udnytte GitHub til personlige projekter. Ved at anvende den nye opbevaringsmetode kan vi begynde at strukturere vores trin.

  1. Opret en repo ved navn gatsby-source- *
  2. Grundlæggende projektopsætning
  3. Hent data i gatsby-node.js
  4. Opret noder fra data
  5. Prøve!

Du kan installere dit plugin fra GitHub, linke det med npm eller teste din gatsby-node.js direkte i et eksisterende projekt.

Hold det enkelt

Der er en masse smarte ting, du kan gøre i kilde plugins. Tjek nogle af de populære i Gatsby-repo som Contentful eller Wordpress, hvis du vil se den avancerede taktik. Da jeg i dag vil have Cat Facts i Gatsby, så snart jeg kan, vil jeg bruge den mindst mulig levedygtige tilgang. Jeg synes, dette er en god måde at lære!

Projektopsætning

Betragt dit plugin som sin egen npm-pakke. Det vil have sin egen package.json, og du kan lægge stort set alt hvad du har brug for derinde, inklusive dine egne afhængigheder og hjælpescripts. Hvis du planlægger at indsende dit plugin til den officielle Gatsby-repo, er det bedst at følge deres retningslinjer, men for nu kan vi bare leve vores drømme i en separat repo.

Kildekoder i Gatsby

Før vi går og henter vores data, er vi nødt til at vide, hvor vi kan sætte denne kode. I vores gatsby-node.js-fil, uanset om det er i dit projekt eller plugins rodmappe, kan vi eksportere en navngivet variabel kildeNoder. Det tager faktisk en funktion, som giver os nogle smarte parametre at arbejde med. Disse funktioner fortæller Gatsby på magisk vis, hvordan vi kan forvandle vores mystiske kattefakta til data, der kan stilles til spørgsmål. Vi kommer lidt foran, så indtil videre kan vi bare bruge en tom async-funktion. Hvis du vil stoppe og læse lidt på async / afvente, kan du se denne artikel.

Tid til at tale med

Vi har brug for et bibliotek for at hjælpe Node-miljøet med at hente data. Vælg din favorit, jeg går selv med knudehentning.

Den enkleste måde at se nogle resultater på er bare at console.log i din funktion, som vises i gatsby udvikle kommandoen. Så lad os se nogle kattefakta i vores konsol med denne kode i gatsby-node.js.

// gatsby-node.js
const fetch = kræver ('node-fetch');
exports.sourceNodes = async () => {
const catFacts = afventer hentning ('');
// .all er dataene fra kattefakta-API'et
// Dette ville være et godt sted at udføre nogle fejlhåndtering
catFacts.all.forEach (catFact => {
// .text er kattefakta
console.log ('\\ n \\ n', catFact.text);
});
}

Sørg for at navngive dine variabler i overensstemmelse med de data, du bruger!

For at teste din funktion skal du køre gatsby udvikle, og du skal se din terminal spytte nogle data ud. Alt, hvad vi har gjort, er at vise os selv, at vi kan få data, vi har endnu ikke sendt noget af det til Gatsby. Det er her vi vender tilbage til Gatsby-node-forretningen!

Det kan være lidt forvirrende, at vi er i filen gatsby-node.js ved hjælp af node-hente og oprette noder til data. Faktisk er det bestemt forvirrende. Lad os afklare.

  • gatsby-node.js er en fil, som Gatsby kører i Node.js. Det er valgfrit, men du kan gøre ting som at hente dine egne data.
  • node-fetch er en måde at bruge det Fetch API, du måske har set i browsere, men i Node.js.
  • En Gatsby-knude er et stykke data, som du kan spørge via GraphQL i din app.

Hvis du bruger et andet API og får fejl, skal du sørge for at bruge de rigtige taster. Jeg har en .all og .text, der muligvis ikke fungerer til din ikke-kat-fakta-api.

Gør data til Gatsby-noder

Nu er vi klar til at bruge de parametre, vi talte om på sourceNodes-funktionen for et stykke tid siden. Vi kan nu ændre vores funktionssignatur på denne måde:

- export.sourceNodes = async () => {
+ exports.sourceNodes = async ({handlinger, createNodeId, createContentDigest}) => {

Vi vil bruge hver af disse nye parametre til at hjælpe os med at oprette data, som Gatsby kan forstå. Mens vi opretter disse nye stykker data, er det vigtigt at bemærke, at Gatsby forstår en bestemt type data. Vi har talt om Gatsby-noden, så lad os nu se på strukturen. Ved hjælp af vores parametre og Cat Facts-data kan vi nu gøre dette:

const query = vente på hentning ('');
// Behandle data til noder.
catFacts.all.forEach (catFact => {
const nodeContent = JSON.stringify (catFact);
  const nodeMeta = {
// kattens faktiske unikke id er i _id
id: createNodeId (`kat-fakta - $ {catFact._id}`),
    forælder: null,
    børn: [],
    internt: {
// dette vil være vigtigt for at finde noden
type: 'CatFacts',
indhold: node Indhold,
        contentDigest: createContentDigest (catFact),
      },
    };
    const node = Object.assign ({}, catFact, nodeMeta);
// fjern dette, når det fungerer!
console.log ('\\ n \\ n', catFact.text);
    createNode (node);
});

Med denne kode skulle vi være i stand til at få Cat Facts ind i vores app. Jeg har forladt konsolloggen der, så du kan se nogle feedback i konsollen.

Testning i en Gatsby-app

Der er nogle få måder, vi kan hente ind i disse data for at sikre, at de fungerer. Vi kan placere vores Cat Facts-kode i gatsby-node.js-filen i vores test, projekt, men det er bedst at bruge npm-link med vores plugin repo og testprojekt, så vi får en bedre idé om, hvordan det vil fungere i produktionen. For at gøre det kan du blot køre en kommando fra din testapps rodkatalog:

npm-link ../gatsby-source-cat-facts

I din gatsby-config.js-fil skal du tilføje gatsby-source-cat-fakta til dit plugins-array. Har du endnu ikke en? Her er en simpel version for at komme i gang:

// gatsby-config.js
module.exports = {
plugins: ['gatsby-source-kat-fakta']
};

Den nemmeste måde at se, om vores Cat Facts blev indlæst korrekt, er at køre gatsby-udvikling og gå over til dit GraphiQL-værktøj, som som standard er placeret på http: // localhost: 8000 / ___ graphql. Hvis alt er gået efter planen, skal du kunne køre denne forespørgsel:

{
  allCatFacts {
    catFacts: kanter {
      catFact: node {
        tekst
        upvotes {
          bruger
        }
      }
    }
  }
}

Kanter og knudepunkter er den måde, som GraphQL beskriver de elementer, der mere ofte tænkes på som array-poster. Den JSON, vi får tilbage, har faktisk kanter som en matrix og noder som emnerne, men jeg vil gerne omdøbe dem i forespørgslen for at gøre React-koden mere læsbar.

Med denne forespørgsel skulle du se dine friske fakta, og de er klar til at indlæse i din Gatsby-app!

Sidste berøring

Jeg har tilføjet et par ting og offentliggjort mine gatsby-kilde-katte-fakta til npm, så du kan lege med det selv! Tjek repoen for de tilføjelser, jeg har lavet for at gøre det npm klar, hvis det er et skridt, du vil tage med dit eget plugin.

Fortæl mig på Twitter @_cwlsn, hvordan processen var, og hvis du har spørgsmål!