Builder.io & Astro

Builder.io es un CMS visual que admite la edición de contenido mediante arrastrar y soltar para crear sitios web.

Esta receta te mostrará cómo conectar tu espacio de Builder a Astro con cero JavaScript en el lado del cliente.

Requisitos previos

Para empezar, necesitarás lo siguiente:

Una cuenta y un espacio de Builder - Si aún no tienes una cuenta, regístrate gratis y crea un nuevo espacio. Si ya tienes un espacio en Builder, siéntete libre de usarlo, pero tendrás que modificar el código para que coincida con el nombre del modelo (blogpost) y los campos de datos personalizados.
Una clave de API de Builder - Esta clave pública se utilizará para obtener tu contenido desde Builder. Lee la guía de Builder sobre cómo encontrar tu clave.

Configuración de credenciales

Para añadir tu clave de API de Builder y el nombre de tu modelo de Builder a Astro, crea un archivo .env en la raíz de tu proyecto (si no existe ya uno) y añade las siguientes variables:

BUILDER_API_PUBLIC_KEY=YOUR_API_KEY
BUILDER_BLOGPOST_MODEL='blogpost'

Ahora, deberías poder usar esta clave de API en tu proyecto.

Si deseas tener IntelliSense para tus variables de entorno, puedes crear un archivo env.d.ts en el directorio src/ y configurar ImportMetaEnv de esta manera:

interface ImportMetaEnv {
  readonly BUILDER_API_PUBLIC_KEY: string;
}

Tu proyecto ahora debería incluir estos archivos:

Directoriosrc/
- env.d.ts
.env
astro.config.mjs
package.json

Aprende más sobre las variables de entorno y los archivos .env en Astro.

Crear un blog con Astro y Builder

Crear un modelo para una publicación de blog

Las instrucciones a continuación crean un blog de Astro utilizando un modelo de Builder (Tipo: “Section”) llamado blogpost que contiene dos campos de texto requeridos: title y slug.

En la aplicación de Builder, crea el modelo que representará una publicación de blog: ve a la pestaña Models y haz clic en el botón + Create Model para crear el modelo con los siguientes campos y valores:

Tipo: Section
Nombre: “blogpost”
Descripción: “Este modelo es para una publicación de blog”

En tu nuevo modelo, utiliza el botón + New Custom Field para crear 2 campos nuevos:

Campo de texto
- Nombre: “title”
- Requerido: Sí
- Valor por defecto “Olvidé ponerle un título a esto”
(deja los otros parámetros con sus valores por defecto)
Campo de texto
- Nombre: “slug”
- Requerido: Sí
- Valor por defecto “algunos-slugs-se-toman-su-tiempo”
(deja los otros parámetros con sus valores por defecto)

Luego haz clic en el botón Save en la esquina superior derecha.

Configurar la vista previa

Para usar el editor visual de Builder, crea la página src/pages/builder-preview.astro que renderizará el componente especial <builder-component>:

Directoriosrc/
- Directoriopages/
  - builder-preview.astro
- env.d.ts
.env
astro.config.mjs
package.json

Luego añade el siguiente contenido:

---
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
---

<html lang="en">
  <head>
    <title>Preview for builder.io</title>
  </head>
  <body>
    <header>This is your header</header>

    <builder-component model={builderModel} api-key={builderAPIpublicKey}
    ></builder-component>
    <script async src="https://cdn.builder.io/js/webcomponents"></script>

    <footer>This is your footer</footer>
  </body>
</html>

En el ejemplo anterior, <builder-component> le dice a Builder dónde insertar el contenido de su CMS.

Establecer la nueva ruta como la URL de vista previa

Copia la URL completa de tu vista previa, incluyendo el protocolo, a tu portapapeles (por ejemplo, https://{tu host}/builder-preview).
Ve a la pestaña Models en tu espacio de Builder, elige el modelo que has creado y pega la URL del paso 1 en el campo Preview URL. Asegúrate de que la URL esté completa e incluya el protocolo, por ejemplo https://.
Haz clic en el botón Save en la esquina superior derecha.

Probar la configuración de la URL de vista previa

Asegúrate de que tu sitio esté activo (por ejemplo, que tu servidor de desarrollo se esté ejecutando) y que la ruta /builder-preview esté funcionando.
En tu espacio de Builder, bajo la pestaña Content, haz clic en New para crear una nueva entrada de contenido para tu modelo blogpost.
En el editor de Builder que se acaba de abrir, deberías poder ver la página builder-preview.astro con un gran botón Add Block en el centro.

Crear una publicación de blog

En el editor visual de Builder, crea una nueva entrada de contenido con los siguientes valores:
- title: ‘First post, woohoo!’
- slug: ‘first-post-woohoo’
Completa tu publicación usando el botón Add Block y añade un campo de texto con algo de contenido para la publicación.
En el campo de texto sobre el editor, dale un nombre a tu entrada. Así es como se mostrará en la aplicación de Builder.
Cuando estés listo, haz clic en el botón Publish en la esquina superior derecha.
Crea tantas publicaciones como quieras, asegurándote de que todas las entradas de contenido contengan un title y un slug, así como algo de contenido para la publicación.

Mostrar una lista de publicaciones de blog

Añade el siguiente contenido a src/pages/index.astro para obtener y mostrar una lista de todos los títulos de las publicaciones, cada uno enlazando a su propia página:

---

const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;

const { results: posts } = await fetch(
  `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    fields: ["data.slug", "data.title"].join(","),
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---

<html lang="en">
  <head>
    <title>Blog Index</title>
  </head>
  <body>
    <ul>
      {
        posts.flatMap(({ data: { slug, title } }) => (
          <li>
            <a href={`/posts/${slug}`}>{title}</a>
          </li>
        ))
      }
    </ul>
  </body>
</html>

Obtener datos a través de la API de contenido devuelve un array de objetos que contienen los datos de cada publicación. El parámetro de consulta fields le dice a Builder qué datos se incluyen (ver código resaltado). slug y title deben coincidir con los nombres de los campos de datos personalizados que has añadido a tu modelo de Builder.

El array posts devuelto por la solicitud muestra una lista de títulos de publicaciones de blog en la página de inicio. Las rutas de página individuales se crearán en el siguiente paso.

¡Ve a tu ruta de índice y deberías poder ver una lista de enlaces, cada uno con el título de una publicación de blog!

Mostrar una única publicación de blog

Crea la página src/pages/posts/[slug].astro que generará dinámicamente una página para cada publicación.

Directoriosrc/
- Directoriopages/
  - index.astro
  - Directorioposts/
    [slug].astro
- env.d.ts
.env
astro.config.mjs
package.json

Este archivo debe contener:

Una función getStaticPaths() para obtener información del slug desde Builder y crear una ruta estática para cada publicación de blog.
Un fetch() a la API de Builder utilizando el identificador slug para devolver el contenido y los metadatos de la publicación (por ejemplo, un title).
Un <Fragment /> en la plantilla para renderizar el contenido de la publicación como HTML.

Cada uno de estos está resaltado en el siguiente fragmento de código.

---
export async function getStaticPaths() {
  const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
  const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
  const { results: posts } = await fetch(
    `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams(
      {
        apiKey: builderAPIpublicKey,
        fields: ["data.slug", "data.title"].join(","),
        cachebust: "true",
      }
    ).toString()}`
  )
    .then((res) => res.json())
    .catch
    // ...catch some errors...);
    ();
  return posts.map(({ data: { slug, title } }) => ({
    params: { slug },
    props: { title },
  }))
}
const { slug } = Astro.params;
const { title } = Astro.props;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
// Builder's API requires this field but for this use case the url doesn't seem to matter - the API returns the same HTML
const encodedUrl = encodeURIComponent("moot");
const { html: postHTML } = await fetch(
  `https://cdn.builder.io/api/v1/qwik/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    url: encodedUrl,
    "query.data.slug": slug,
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---
<html lang="en">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <header>This is your header</header>
    <article>
      <Fragment set:html={postHTML} />
    </article>
    <footer>This is your footer</footer>
  </body>
</html>

Ahora, al hacer clic en un enlace de tu ruta de índice, se te dirigirá a la página de la publicación de blog individual.

Publicando tu sitio

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

Reconstruir al haber cambios en Builder

Si tu proyecto utiliza el modo estático por defecto de Astro, necesitarás configurar un webhook para activar una nueva compilación cuando tu contenido cambie. Si utilizas Netlify o Vercel como tu proveedor de alojamiento, puedes utilizar su función de webhook para activar una nueva compilación cada vez que hagas clic en Publish en el editor de Builder.

Netlify

Ve al panel de control de tu sitio, luego a Site Settings y haz clic en Build & deploy.
En la pestaña Continuous Deployment, busca la sección Build hooks y haz clic en Add build hook.
Proporciona un nombre para tu webhook y selecciona la rama en la que deseas activar la compilación. Haz clic en Save y copia la URL generada.

Vercel

Ve al panel de control de tu proyecto y haz clic en Settings.
En la pestaña Git, busca la sección Deploy Hooks.
Proporciona un nombre para tu webhook y la rama en la que deseas activar la compilación. Haz clic en Add y copia la URL generada.

Añadir un webhook a Builder

En tu panel de control de Builder, ve a tu modelo blogpost. Bajo Show More Options, selecciona Edit Webhooks en la parte inferior.
Añade un nuevo webhook haciendo clic en Webhook. Pega la URL generada por tu proveedor de alojamiento en el campo Url.
Haz clic en Show Advanced debajo del campo de URL y activa la opción para seleccionar Disable Payload. Con el payload desactivado, Builder envía una solicitud POST más simple a tu proveedor de alojamiento, lo que puede ser útil a medida que tu sitio crece. Haz clic en Done para guardar esta selección.

Con este webhook configurado, cada vez que hagas clic en el botón Publish en el editor de Builder, tu proveedor de alojamiento reconstruirá tu sitio, y Astro obtendrá los datos recién publicados por ti. ¡No hay nada más que hacer que sentarse y publicar ese fantástico contenido!

Recursos oficiales

Echa un vistazo al proyecto inicial oficial de Builder.io, que utiliza Astro y SolidJS.
La guía de inicio rápido oficial de Builder cubre tanto el uso de la API REST como la obtención de datos a través de una integración con un framework de JavaScript como Qwik, React o Vue.
El explorador de API de Builder puede ayudarte si necesitas resolver problemas con tus llamadas a la API.