Flotiq & Astro

Flotiq est un CMS headless conçu pour différents frontends, tels que les sites statiques, les applications mobiles et les applications web. Les développeurs et les créateurs de contenu gèrent et diffusent le contenu par le biais d’API REST et GraphQL.

Intégration avec Astro

Ce guide permet d’utiliser l’API CMS headless de Flotiq avec un projet Astro pour afficher du contenu sur votre site web.

Pré-requis

Pour commencer, vous aurez besoin de :

Un projet Astro - Vous pouvez créer un nouveau projet en utilisant la commande npm create astro@latest.
Un compte Flotiq - Si vous n’avez pas de compte, inscrivez-vous gratuitement.
Une clé API Flotiq en lecture seule - Découvrez comment obtenir votre clé.

Configuration des variables d’environnement

Ajoutez la clé API en lecture seule de votre compte Flotiq au fichier .env à la racine de votre projet Astro :

FLOTIQ_API_KEY=__VOTRE_CLE_API_FLOTIQ__

Définir un type de contenu dans Flotiq

Tout d’abord, vous devez définir un exemple de définition de type de contenu dans Flotiq pour stocker des données.

Connectez-vous à votre compte Flotiq et créez une définition de type de contenu personnalisée avec l’exemple de configuration Blog Post suivant :

Label : Blog Post
API Name : blogpost
Fields :
- Title : texte, obligatoire
- Slug : texte, obligatoire
- Content : texte enrichi, obligatoire

Ensuite, créez un ou plusieurs exemples d’objets de contenu en utilisant le type Blog Post.

Installation du SDK TypeScript de Flotiq

Pour connecter votre projet à Flotiq, installez le SDK de Flotiq en utilisant le gestionnaire de paquets de votre choix :

npm install flotiq-api-ts

pnpm add flotiq-api-ts

yarn add flotiq-api-ts

Ensuite, configurez le SDK en utilisant vos informations d’identification. Créez un nouveau fichier nommé flotiq.ts dans le répertoire src/lib de votre projet :

import { FlotiqApi } from "flotiq-api-ts";

export const flotiq = new FlotiqApi(import.meta.env.FLOTIQ_API_KEY);

Cette configuration peut maintenant être utilisée dans l’ensemble de votre projet.

Récupérer et afficher les données de Flotiq

Récupérez les données Blog Post sur une page Astro en utilisant l’API personnalisée de votre contenu BlogpostAPI :
src/pages/index.astro
```
---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
```

Affichez le contenu dans votre modèle Astro. Vous aurez accès au titre (title), slug, et contenu (content) de vos articles ainsi qu’à d’autres données internes de l’article :

---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
<html lang="fr">
  <head>
    <title>Astro</title>
  </head>
  <body>
    {posts.data?.map((post) => (
      <section>
        <a href={`/posts/${post.slug}`}>
          <h2>{post.title}</h2>
        </a>
        <div>{post.internal?.createdAt}</div>
        <div set:html={post.content}/>
      </section>
    ))}
  </body>
</html>

Démarrez le serveur de développement et visitez votre page de prévisualisation à http://localhost:4321 pour voir la liste de vos articles de blog. Chaque article renvoie à une page qui n’existe pas encore. Celles-ci seront créées à l’étape suivante.

Générer des pages individuelles

Astro prend en charge le pré-rendu de toutes vos pages à l’avance, ou la création de routes à la demande lorsqu’elles sont demandées. Suivez les instructions pour la génération de site statique ou le rendu à la demande pour créer les routes de pages pour vos articles de blog.

Génération de sites statiques

En mode génération de sites statiques (SSG), utilisez la méthode getStaticPaths() pour récupérer tous les chemins d’accès possibles aux articles de blog à partir de Flotiq.

Créez un nouveau fichier [slug].astro dans le répertoire /src/pages/posts/. Récupérez tous les articles du blog et renvoyez-les dans la méthode getStaticPaths() :

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
---

Ajoutez le modèle pour afficher un article individuel :

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
const post: Blogpost = Astro.props;
---
<html lang="fr">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visitez http://localhost:4321 et cliquez sur un article de blog lié dans votre liste. Vous pourrez alors naviguer vers la page de l’article en question.

Rendu à la demande

Si vous utilisez le mode SSR, vous devrez récupérer un seul article en vous basant sur son slug.

Créez un nouveau fichier [slug].astro dans le répertoire /src/pages/posts/. Récupérez l’article par son champ slug, en incluant la logique pour afficher une page 404 si la route n’est pas trouvée :

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---

Ajoutez le modèle pour afficher un article individuel :

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---
<html lang="fr">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visitez http://localhost:4321 et cliquez sur un article de blog lié dans votre liste. Vous pourrez alors naviguer vers la page de l’article en question.

Actualiser le SDK après des changements de type de contenu

Lorsque vous utilisez le SDK TypeScript de Flotiq (flotiq-api-ts), tous vos types de données sont correctement associés dans le projet Astro.

Si vous apportez des modifications à la structure de vos types de contenu (comme l’ajout d’un nouveau champ ou la modification d’un champ existant), vous devrez actualiser le SDK pour vous assurer que votre projet reflète les dernières mises à jour du modèle.

Pour ce faire, exécutez la commande rebuild de votre gestionnaire de paquets :

npm rebuild flotiq-api-ts

pnpm rebuild flotiq-api-ts

yarn rebuild flotiq-api-ts
// pour yarn v1 (Classic):
// yarn add flotiq-api-ts

Cette opération mettra à jour le SDK, en alignant les types d’objets, les champs et les méthodes de l’API sur votre modèle de données actuel.

Publier votre site

Pour déployer votre site web, visitez les guides de déploiement d’Astro et suivez les instructions de votre hébergeur préféré.

Redéploiement en fonction des modifications apportées à Flotiq

Pour mettre à jour votre site publié, configurez Flotiq pour qu’il envoie un webhook à votre hébergeur afin de déclencher une nouvelle compilation chaque fois que votre contenu est modifié.

Dans Flotiq, vous pouvez définir le type de contenu et les événements sur lesquels il doit se déclencher, et le configurer en conséquence. Voir la documentation des Webhooks de Flotiq pour plus de détails.