Storyblok y Astro
Storyblok es un headless CMS basado en componentes que te permite gestionar tu contenido utilizando componentes reutilizables llamados Bloks.
Integración con Astro
En esta sección, utilizarás la integración de Storyblok para conectar Storyblok con Astro.
Prerrequisitos
Para comenzar, necesitarás lo siguiente:
-
Un proyecto de Astro - Si aún no tienes un proyecto de Astro, nuestra guía de instalación te ayudará a poner en marcha en poco tiempo.
-
Una cuenta y espacio de Storyblok - Si aún no tienes una cuenta, regístrate gratis y crea un nuevo espacio.
-
Token de vista previa de Storyblok - Este token se utilizará para obtener borradores y versiones publicadas de tu contenido. Puedes encontrar y generar tu token de API en la pestaña “Access Tokens” de la configuración de tu espacio de Storyblok.
Configuración de credenciales
Para agregar las credenciales de tu sitio a Astro, crea un archivo .env
en la raíz de tu proyecto con la siguiente variable:
Ahora, deberías poder usar esta variable de entorno en tu proyecto.
Tu directorio raíz debería incluir este nuevo archivo ahora:
Directoriosrc/
- …
- .env
- astro.config.mjs
- package.json
Instalación de dependencias
Para conectar Astro con tu espacio de Storyblok, instala la integración oficial de Storyblok utilizando el siguiente comando según tu gestor de paquetes preferido:
Configurando Storyblok
Modifica tu archivo de configuración de Astro para incluir la integración de Storyblok de la siguiente manera:
La integración de Storyblok requiere un objeto con las siguientes propiedades:
-
accessToken
- Esto hace referencia al token de la API de Storyblok que agregaste en el paso anterior.Dado que el archivo de configuración de Astro normalmente no admite variables de entorno, utiliza la función
loadEnv
de Vite para cargarlas. -
components
- Un objeto que mapea los nombres de los componentes de Storyblok a las rutas de tus componentes locales. Esto es necesario para renderizar tus Bloks de Storyblok en Astro.Las rutas de los componentes son relativas al directorio
src
. Por ejemplo, si tu componente se encuentra ensrc/storyblok/MyComponent.astro
,la ruta seríastoryblok/MyComponent
(sin la extensión.astro
). -
apiOptions
- Un objeto conteniendo las opciones de la API de Storyblok.Por defecto, la región es
eu
. Si tu espacio de Storyblok fue creado en la región de US, necesitarás establecer la región comous
.
Conectando Bloks a los componentes de Astro
Para conectar tus Bloks a Astro, crea una nueva carpeta llamada storyblok
dentro del directorio src
. Esta carpeta contendrá todos los componentes de Astro que coincidirán con tus Bloks en tu biblioteca de Bloks de Storyblok.
En este ejemplo, tienes un tipo de contenido de Blok llamado blogPost
en tu biblioteca de Storyblok con los siguientes campos:
title
- Un campo de textodescription
- Un campo de textocontent
- Un campo de texto enriquecido
Nuestro objetivo es crear el equivalente del componente de Astro que utilizará estos campos para renderizar su contenido. Para hacer esto, crea un nuevo archivo llamado BlogPost.astro
dentro de src/storyblok
con el siguiente contenido:
La propiedad blok
contiene los datos que recibirás de Storyblok. También contiene los campos que se definieron en el Blok de tipo de contenido blogPost
en Storyblok.
Para renderizar nuestro contenido, la integración proporciona funciones de utilidad como:
storyblokEditable
- Agrega los atributos necesarios a los elementos para que puedas editarlos en Storyblok.renderRichText
- transforma el campo de texto enriquecido en HTML.
Tu directorio raíz debería incluir este nuevo archivo:
Directoriosrc/
Directoriostoryblok/
- BlogPost.astro
- .env
- astro.config.mjs
- package.json
Finalmente, para conectar el Blok blogPost
al componente BlogPost
, agrega una nueva propiedad a tu objeto components
en el archivo de configuración de Astro.
- La clave es el nombre del Blok en Storyblok. En este caso, es
blogPost
. - El valor es la ruta al componente. En este caso, es
storyblok/BlogPost
.
La key
debe coincidir exactamente con el nombre del Blok en Storyblok para que se referencie correctamente. Si no coinciden, o estás intentando referenciar un componente que no existe en Storyblok, obtendrás un error.
Obteniendo Datos
Para probar la configuración, en Storyblok crea una nueva historia con el tipo de contenido blogPost
llamada test-post
.
En Astro, crea una nueva página en el directorio src/pages/
llamada test-post.astro
con el siguiente contenido:
Para consultar tus datos, utiliza el gancho useStoryblokApi
. Esto inicializará una nueva instancia del cliente utilizando la configuración de integración que has establecido.
Para renderizar tu contenido, pasa la propiedad content
del Story al componente StoryblokComponent
como una prop blok
. Este componente renderizará los Bloks que están definidos dentro de la propiedad content
property. En este caso, renderizará el componente BlogPost
.
Creando un blog con Astro y Storyblok
Con la configuración de integración establecida, ahora puedes crear un blog con Astro y Storyblok.
Prerrequisitos
-
Un espacio de Storyblok - Para este tutorial, recomendamos utilizar un espacio nuevo. Si ya tienes un espacio con bloques (Bloks), siéntete libre de utilizarlos, pero deberás modificar el código para que coincida con los nombres de los bloques y los tipos de contenido.
-
Un proyecto de Astro integrado con Storyblok - Consulta la sección de integración con Astro para obtener instrucciones sobre cómo configurar la integración.
Creando una biblioteca blok
Para crear bloques, ve a la aplicación de Storyblok y haz clic en la pestaña de Block Library. Haz clic en el botón + New blok y crea los siguientes bloques:
-
blogPost
- Un tipo de contenido Blok con los siguientes campos:title
- Un campo de textodescription
- Un campo de textocontent
- Un campo de texto enriquecido
-
blogPostList
- Un Blok anidado vacío -
page
- Un tipo de contenido Blok con los siguientes campos:body
- Un Blok anidado
Creando contenido
Para agregar nuevo contenido, ve a la sección de contenido haciendo clic en la pestaña de Content. Utilizando la biblioteca de Bloks que creaste en el paso anterior, crea las siguientes historias:
-
home
- Un story de tipo de contenido con el Blokpage
. Dentro del campobody
, agrega un BlokblogPostList
. -
blog/no-javascript
- Un story con el tipo de contenidoblogPost
dentro de la carpeta del blog. -
blog/astro-is-amazing
- Un story con el tipo de contenidoblogPost
dentro de la carpeta del blog.
Ahora que tienes tu contenido listo, regresa a tu proyecto de Astro y comienza a construir tu blog.
Conectando Bloks a componentes
Para conectar los Bloks recién creados a los componentes de Astro, crea una nueva carpeta llamada storyblok
en tu directorio src
y agrega los siguientes archivos:
Page.astro
es un componente de tipo de contenido de Blok anidado que renderizará de forma recursiva todos los Bloks dentro de la propiedad body
del Blok page
. También agrega los atributos storyblokEditable
al elemento padre, lo que nos permitirá editar la página en Storyblok.
BlogPost.astro
renderizará las propiedades title
, description
y content
del Blok blogPost
.
Para transformar la propiedad content
de un campo de texto enriquecido a HTML, puedes utilizar la función auxiliar renderRichText
.
BlogPostList.astro
es un componente de tipo de contenido de Blok anidado que renderizará una lista de vistas previas de publicaciones de blog.
Utiliza el hook useStoryblokApi
para obtener todas los stories con el tipo de contenido blogPost
. Utiliza el parámetro de consulta version
para obtener las versiones en borrador de las historias cuando se encuentra en modo de desarrollo y las versiones publicadas al compilar para producción.
Astro.props
se utiliza para configurar el editor en Storyblok. Aquí también se pueden pasar propiedades adicionales a tu componente, si es necesario.
Finalmente, agrega tus componentes a la propiedad components
del objeto de configuración storyblok
en astro.config.mjs
. La clave es el nombre del Blok en Storyblok y el valor es la ruta al componente relativa a src
.
Generando páginas
Para crear una ruta para una página
especifica, puedes obtener su contenido directamente desde la API de Storyblok y pasarlo al componente StoryblokComponent
. Asegúrate de haber agregado el componente Page
a tu archivo astro.config.mjs.
Crea un archivo index.astro
dentro de src/pages/
para renderizar la página home
:
Para generar páginas para todas tus publicaciones de blog, crea una página .astro
que creará rutas dinámicas. Este enfoque varía dependiendo de si estás utilizando la generación de sitios estáticos (la opción predeterminada) o el renderizado en el lado del servidor.
Generación de sitio estático
If you are using Astro’s default static site generation, you will use dynamic routes and the getStaticPaths
function to generate your project pages.
Crea un nuevo directorio src/pages/blog/
y agrega un nuevo archivo llamado [...slug].astro
con el siguiente código:
Este archivo generará una página para cada historia, con el slug y contenido obtenidos de la API de Storyblok.
Cuando agregues carpetas dentro de Storyblok, inclúyelas en el slug al interactuar con la API de Storyblok. Por ejemplo, en la solicitud GET anterior, podemos usar cdn/stories/blog, con una carpeta blog adentro en lugar de usarlas en la raíz.
Renderizado en el lado del servidor
Si has optado por el modo de SSR, utilizarás rutas dinámicas para obtener los datos de la página desde Storyblok.
Crea un nuevo directorio src/pages/blog/
y agrega un nuevo archivo llamado [...slug].astro
con el siguiente código:
Este archivo obtendrá y renderizará los datos de la página desde Storyblok que coincidan con el parámetro dinámico slug
.
Dado que estás utilizando una redirección a /404
, crea una página de error 404 en src/pages
:
Si no se encuentra la story, la solicitud se redirigirá a la página 404.
Publicando tu sitio
Para implementar tu sitio web, visita nuestras guías de despliegue y sigue las instrucciones para tu proveedor de alojamiento preferido.
Volver a compilar según los cambios en Storyblok
Si tu proyecto utiliza el modo estático predeterminado de Astro, deberás configurar un webhook para desencadenar una nueva compilación cuando cambie tu contenido. Si estás utilizando Netlify o Vercel como proveedor de alojamiento, puedes utilizar su función de webhook para desencadenar una nueva compilación a partir de los eventos de Storyblok.
Netlify
Para configurar un webhook en Netlify:
-
Ve al panel de administración de tu sitio en Netlify y haz clic enBuild & deploy.
-
Bajo la pestaña Continuous Deployment, encuentra la sección de 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
Para configurar un webhook en Vercel:
-
Ve al panel de control de tu proyecto y haz clic en Settings.
-
Bajo la pestaña Git, encuentra 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ñadiendo un webhook a Storyblok
En la sección Settings de tu espacio de Storyblok, haz clic en la pestaña Webhooks. Pega la URL del webhook que copiaste en el campo Story published & unpublished y haz clic en Save para crear el webhook.
Ahora, cada vez que publiques una nueva historia, se desencadenará una nueva compilación y tu blog se actualizará.
Recursos Oficiales
- Storyblok ofrece una integración de Astro para agregar Storyblok a tu proyecto.
Oficiales de la comunidad
- Conseguir que el Editor Visual funcione para Storyblok + Astro por Sandra Rodgers
- Astro + Storyblok: previsualización SSR para una edición visual instantánea por Jonas Gierer
- Astro-Storyblok previsualiza un sitio con la función Branch Deploys de Netlify por Sandra Rodgers