gatsby plugin meilisearch
v0.3.1 ?
Un plugin pour indexer votre contenu Gatsby vers Meilisearch basé sur des requêtes graphQL
Pour comprendre Meilisearch et son fonctionnement, consultez la documentation de Meilisearch.
Pour comprendre Gatsby et son fonctionnement, consultez la documentation de Gatsby.
Dites adieu au déploiement de serveur et aux mises à jour manuelles avec Meilisearch Cloud. Commencez avec un essai gratuit de 14 jours ! Aucune carte de crédit requise.
Dans votre application Gatsby, ajoutez le package :
Avec npm :
npm install gatsby-plugin-meilisearch Avec yarn :
yarn add gatsby-plugin-meilisearchIl existe de nombreuses façons simples de télécharger et d’exécuter une instance Meilisearch.
Par exemple, si vous utilisez Docker :
docker pull getmeili/meilisearch:latest # Fetch the latest version of Meilisearch image from Docker Hub
docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest meilisearch --master-key=masterKey Avec cette commande, host de votre instance Meilisearch est http://localhost:7700 et votre clé principale est masterKey
Si vous n'avez pas de Gatsby en cours d'exécution, vous pouvez soit lancer le [playground présent dans ce projet)(./playground/README.md), soit créer un projet Gatsby.
Exécutez votre application si elle n'est pas encore en cours d'exécution :
gatsby developMaintenant que votre application Gatsby est exécutée, vous avez accès aux URL suivantes :
http://localhost:8000/ URL de votre application Web.http://localhost:8000/___graphql : URL vers l'outil GraphiQL où vous pouvez créer des requêtes graphQL sur le terrain de jeu et les demander. Vous devriez maintenant avoir une application Gatsby en cours d'exécution avec gatsby-plugin-meilisearch installé et une instance Meilisearch en cours d'exécution.
Configurons notre plugin pour qu'il fonctionne ! Dans cet exemple, nous allons récupérer l'URL de chaque page de notre site Web Gatsby et les indexer dans Meilisearch.
Pour faire fonctionner le plugin, ouvrez le fichier de configuration gatsby-config.js situé à la racine de votre projet Gatsby. Toute la configuration a lieu dans ce fichier.
Tout d’abord, vous devez ajouter vos informations d’identification Meilisearch.
Les qualifications sont composées de :
host : L'URL de votre instance Meilisearch en cours d'exécution.api_key : La clé master ou une autre key avec l'autorisation d'ajouter des documents dans MeiliSearch. En savoir plus sur les autorisations et les clés API ici.search ne doivent jamais être utilisées sur votre front-end. Pour la recherche, utilisez la clé Default Search Key disponible sur la route key ou créez une clé API personnalisée avec uniquement des droits de recherche.
Ajoutez les informations d'identification de la manière suivante dans votre fichier gatsby-config.js :
{
plugins : [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
} ,
} ,
]
}Consultez cette section si vous ne savez pas quelles sont vos informations d'identification.
L'étape suivante consiste à définir quelles données nous souhaitons ajouter dans Meilisearch et comment. Cela se produit dans le champ indexes .
Le champ indexes est un tableau qui peut être composé de plusieurs objets index. Chaque objet d'index contient les informations suivantes :
indexUid : Le nom de l'index dans lequel les données sont ajoutées.
Définissons l'uid d'index sur pages_url . Lors de la construction, l'index pages_url est créé dans Meilisearch.
indexUid: ' pages_url ' si pages_url existait déjà, il est supprimé et recréé lors de la construction
query : requête GraphQL récupérant les données à ajouter dans Meilisearch
Fournissons la requête graphQL qui récupère les URL des pages de notre application.
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` , Après avoir exécuté cette requête, nous recevons un objet data contenant les éléments suivants :
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
} transformer : Transformez les données récupérées dans un format compatible avec Meilisearch.
Maintenant que nous avons récupéré les données avec le champ query , elles ne sont pas encore prêtes à être envoyées à Meilisearch.
À l'aide d'une fonction transformer , nous pouvons transformer les données récupérées dans un format compatible.
Le premier problème des données récupérées est que les documents à envoyer à Meilisearch sont imbriqués, alors qu'ils devraient être à la racine d'un tableau. Le contenu des nodes doit donc être à la racine.
{
data : {
allSitePages : {
nodes : [
{
'path' : '/404/'
} ,
]
}
}
}devrait devenir :
[
{
'path' : '/404/'
} ,
{
'path' : '/'
} ,
]Le deuxième problème est que chaque document dans Meilisearch nécessite un identifiant unique appelé clé primaire.
Ainsi, chaque document a besoin d'un champ unique appelé id . Par exemple:
{
'id' : 1
'path' : '/404/'
} ,Pour ce faire, nous devons utiliser la méthode transformer pour créer le tableau final compatible d’objets :
{
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
} Dans cette fonction, nous mappons sur data.allSitePage.nodes afin de renvoyer un tableau d'objets pouvant être indexés par Meilisearch. Nous ajoutons un champ id car Meilisearch en a besoin pour l'indexation. Comme nous n'avons ici aucun champ pouvant être utilisé comme id , nous utilisons l'index de l'élément actuel dans le tableau.
Si vous souhaitez en savoir plus sur ces options ( indexUid , query et transformer ) consultez les options d'index
Après avoir rempli ces champs, votre configuration Meilisearch devrait ressembler à ceci :
plugins: [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
indexes : [
{
indexUid : 'pages_url' ,
transformer : ( data ) =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,
} ,
] ,
} ,
} ,
] ; Le gatsby-plugin-meilisearch récupère et ajoute vos données à Meilisearch sur votre build Gatsby.
gatsby buildAprès la compilation, un message dans votre terminal confirme que votre contenu a été indexé avec succès :
success gatsby-plugin-meilisearch - x.xxxs - Documents added to MeilisearchSi vous avez besoin d'outils pour intégrer une expérience de recherche sur votre application, nous disposons d'outils qui peuvent vous aider :
Dans le fichier gatsby-config.js, le plugin Meilisearch accepte les options suivantes :
host (obligatoire) Le champ host est l'adresse où votre instance Meilisearch est exécutée. gatsby-plugin-meilisearch en a besoin pour communiquer avec votre instance Meilisearch et lui envoyer vos données.
apiKey (facultatif) Le champ apiKey contient la clé API si l'instance Meilisearch est protégée par mot de passe.
skipIndexing (facultatif)Cette option vous permet de créer votre site Web sans indexation vers Meilisearch. Par défaut, false
batchSize (facultatif)Le nombre de documents qui doivent être inclus dans chaque lot. Par défaut à 1000
settings (facultatif)Si vous souhaitez transmettre des paramètres à votre instance Meilisearch, vous pouvez le faire ici. En savoir plus sur les paramètres Meilisearch
indexes (obligatoire) Le champ indexes est un tableau d'objets, chacun d'eux représente comment ajouter des données à un index spécifique
Vous pouvez avoir un ou plusieurs objets index dans indexes , ce qui peut être utile si vous souhaitez indexer différents contenus dans différents index (ou plusieurs données différentes dans le même index).
Chaque objet index doit contenir les champs suivants :
indexUid (obligatoire)
C'est le nom de votre index Meilisearch. Il s'agit d'un champ obligatoire car c'est là que les données récupérées sont ajoutées dans Meilisearch. Par exemple, si votre indexUid est pages_url , votre contenu sera indexé dans l'index pages_url dans Meilisearch. Si vous fournissez un nom d'index qui existe déjà, l'index sera supprimé et recréé.
Exemple:
indexUid: ' pages_url 'Vous pouvez en savoir plus sur les index sur notre documentation.
query (obligatoire)
C'est la requête graphQL qui sera exécutée afin de récupérer vos données. Votre requête peut être très spécifique selon les plugins que vous utilisez. Si vous n'êtes pas sûr de votre requête, vous pouvez utiliser l'outil GraphiQL (http://localhost:8000/___graphql) fourni par Gatsby en mode développement pour vous aider à la construire.
Exemple:
query: `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` , Vous pouvez également consulter le fichier de configuration de notre terrain de jeu pour avoir un exemple de requête graphQL utilisant le plugin gatsby-plugin-mdx .
transformer (obligatoire)
Il s'agit d'une fonction qui transforme les données récupérées avant de les envoyer à Meilisearch.
Après avoir exécuté la requête graphQL, un objet de données est reçu avec une structure qui peut différer d'un projet à l'autre, selon la requête que vous avez fournie. Comme Meilisearch nécessite un identifiant unique à la racine de chaque document et doit éviter les objets imbriqués, vous devrez transformer votre objet de données en conséquence. La fonction transformer est le bon endroit pour le faire.
Exemple:
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) , Sans utiliser la fonction transformer , les données ressembleront à ceci :
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
} Après avoir utilisé la fonction transformer comme dans l'exemple ci-dessus, les données ressembleront à ceci et seront prêtes pour l'indexation :
[
{
id : 0 ,
path : '/404/' ,
} ,
{
id : 1 ,
path : '/404.html' ,
} ,
{
id : 2 ,
path : '/' ,
} ,
] ;Si vous souhaitez en savoir plus sur la structure des documents de Meilisearch, vous pouvez le faire dans notre documentation.
Exemple d'utilisation complet :
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
skipIndexing : false ,
batchSize : 1000 ,
options : {
settings : {
searchableAttributes : [ "*" ] ,
} ,
} ,
indexes : [
{
indexUid : 'my_index' ,
transformer : ( ) => { } ,
query : ``
} ,
] ,
} Versions Gatsby prises en charge :
(Ce plugin peut fonctionner avec les anciennes versions de Gatsby, mais celles-ci ne sont ni testées ni officiellement prises en charge pour le moment.)
Versions Meilisearch prises en charge :
Ce package garantit la compatibilité avec la version v1.x de Meilisearch, mais certaines fonctionnalités peuvent ne pas être présentes. Veuillez vérifier les problèmes pour plus d'informations.
Versions nœuds/NPM :
Nous vous recommandons de toujours utiliser la dernière version de Gatsby pour démarrer vos nouveaux projets .
Toute nouvelle contribution est plus que bienvenue dans ce projet !
Si vous souhaitez en savoir plus sur le flux de travail de développement ou si vous souhaitez contribuer, veuillez consulter nos directives de contribution pour des instructions détaillées !
