Flotiq & Astro

Flotiq es un CMS headless diseñado para varios frontends, como sitios estáticos, aplicaciones móviles y web. Los desarrolladores y creadores de contenido gestionan y distribuyen contenido a través de APIs basadas en REST y GraphQL.

Integración con Astro

Esta guía utilizará la API de Flotiq headless CMS con un proyecto de Astro para mostrar contenido en tu sitio web.

Requisitos previos

Para empezar, necesitarás:

Un proyecto de Astro - Puedes crear un nuevo proyecto usando el comando npm create astro@latest.
Una cuenta de Flotiq - Si no tienes una cuenta, regístrate gratis.
Clave de API de solo lectura de Flotiq - Descubre cómo obtener tu clave.

Configurar las variables de entorno

Añade la clave de API de solo lectura de tu cuenta de Flotiq al archivo .env en la raíz de tu proyecto de Astro:

FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__

Definir un tipo de contenido en Flotiq

Primero, necesitas definir un ejemplo de Definición de Tipo de Contenido en Flotiq para almacenar datos.

Log in a tu cuenta de Flotiq y crea una Definición de Tipo de Contenido personalizada con la siguiente configuración de ejemplo para Blog Post:

Etiqueta: Blog Post
Nombre de API: blogpost
Fields:
- Título: texto, requerido
- Slug: texto, requerido
- Contenido: texto enriquecido, requerido

Luego, crea uno o más Objetos de Contenido de ejemplo utilizando este tipo de Blog Post.

Instalar el SDK de Flotiq para TypeScript

To conectar tu proyecto con Flotiq, instala el SDK de Flotiq utilizando el gestor de paquetes de tu elección:

npm install flotiq-api-ts

pnpm add flotiq-api-ts

yarn add flotiq-api-ts

A continuación, configura el SDK utilizando tus credenciales. Crea un nuevo archivo llamado flotiq.ts dentro del directorio src/lib de tu proyecto:

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

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

Esta configuración ahora se puede utilizar en todo tu proyecto.

Obtener y mostrar datos de Flotiq

Obtén los datos del Blog Post en una página de Astro utilizando la API personalizada de tu contenido BlogpostAPI:
src/pages/index.astro
```
---
import { flotiq } from "../lib/flotiq";

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

Muestra el contenido en tu plantilla de Astro. Tendrás acceso al title, slug y content de tus publicaciones, así como a otros datos internos de la publicación:

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

const posts = await flotiq.BlogpostAPI.list();
---
<html lang="en">
  <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>

Inicia el servidor de desarrollo y visita la vista previa de tu página en http://localhost:4321 para ver la lista de tus publicaciones de blog. Cada publicación enlazará a una página que aún no existe. Estas se crearán en el siguiente paso.

Generar páginas individuales

Astro admite tanto el prerenderizado de todas tus páginas con anticipación, como la creación de rutas bajo demanda cuando se solicitan. Sigue las instrucciones para la generación de sitios estáticos o el renderizado bajo demanda para construir las rutas de página para tus publicaciones de blog.

Generación de sitios estáticos

En el modo de generación de sitios estáticos (SSG), usa el método getStaticPaths() para obtener todas las rutas posibles de publicaciones de blog desde Flotiq.

Crea un nuevo archivo [slug].astro en el directorio /src/pages/posts/. Obtén todas las publicaciones de blog y devuélvelas dentro del método 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
  })) || []
}
---

Añade la plantilla para mostrar una publicación individual:

---
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="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visita http://localhost:4321 y haz clic en una publicación de blog vinculada en tu lista. Ahora podrás navegar a la página de la publicación individual.

Renderizado bajo demanda

Si estás utilizando el modo SSR, necesitarás obtener una sola publicación basada en su slug.

Crea un nuevo archivo [slug].astro en el directorio /src/pages/posts/. Obtén la publicación por su campo slug, incluyendo la lógica para mostrar una página 404 cuando no se encuentre la ruta:

---
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');
}
---

Añade la plantilla para mostrar una publicación individual:

---
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="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visita http://localhost:4321 y haz clic en una publicación de blog vinculada en tu lista. Ahora podrás navegar a la página de la publicación individual.

Actualizar el SDK tras cambios en el tipo de contenido

Al usar el SDK de Flotiq para TypeScript (flotiq-api-ts), todos tus tipos de datos se mapean con precisión en el proyecto de Astro.

Si realizas cambios en la estructura de tus tipos de contenido (como añadir un nuevo campo o modificar uno existente), deberás actualizar el SDK para asegurarte de que tu proyecto refleje las últimas actualizaciones del modelo.

Para hacer esto, ejecuta el comando de reconstrucción para tu gestor de paquetes:

npm rebuild flotiq-api-ts

pnpm rebuild flotiq-api-ts

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

Esto actualizará el SDK, alineando los tipos de objetos, campos y métodos de la API con tu modelo de datos actual.

Publicar tu sitio

Para desplegar tu sitio web, visita las guías de despliegue de Astro y sigue las instrucciones de tu proveedor de alojamiento preferido.

Volver a desplegar al realizar cambios en Flotiq

Para actualizar tu sitio publicado, configura Flotiq para enviar un webhook a tu proveedor de alojamiento para activar una reconstrucción cada vez que cambie tu contenido.

En Flotiq, puedes definir qué tipo de contenido y eventos deben activarlo, y configurarlo en consecuencia. Consulta la documentación de Webhooks de Flotiq para obtener más detalles.