Saltar al contenido

ApostropheCMS & Astro

ApostropheCMS es un sistema de gestión de contenidos (CMS) que admite la edición en página en Astro.

Integración con Astro

Sección titulada "Integración con Astro"

En esta sección, utilizarás la integración de Apostrophe para conectar ApostropheCMS a Astro.

Requisitos previos

Sección titulada “Requisitos previos”

Para empezar, necesitarás lo siguiente:

  1. Un proyecto de Astro renderizado bajo demanda con el adaptador de Node.js instalado y output: 'server' configurado - Si aún no tienes un proyecto de Astro, nuestra guía de instalación te ayudará a empezar en poco tiempo.

  2. Un proyecto de ApostropheCMS con una variable de entorno configurada llamada APOS_EXTERNAL_FRONT_KEY - Esta variable de entorno se puede establecer con cualquier cadena de texto aleatoria. Si aún no tienes un proyecto de ApostropheCMS, la guía de instalación te permitirá configurar uno rápidamente. Recomendamos encarecidamente utilizar la herramienta de la CLI de Apostrophe para facilitar esto.

Configurar la comunicación del proyecto

Sección titulada “Configurar la comunicación del proyecto”

Tu proyecto de Astro necesita tener una variable de entorno APOS_EXTERNAL_FRONT_KEY establecida con el mismo valor que la de tu proyecto de ApostropheCMS para permitir la comunicación entre ambos. Esta clave compartida actúa como un medio para verificar las solicitudes entre el frontend (Astro) y el backend (ApostropheCMS).

Crea un archivo .env en la raíz de tu proyecto de Astro con la siguiente variable:

.env
APOS_EXTERNAL_FRONT_KEY='RandomStrongString'

Tu directorio raíz ahora debería incluir este nuevo archivo:

  • Directoriosrc/
    • …
  • .env
  • astro.config.mjs
  • package.json

Instalación de dependencias

Sección titulada "Instalación de dependencias"

Para conectar Astro con tu proyecto de ApostropheCMS, instala la integración oficial de Apostrophe en tu proyecto de Astro utilizando el siguiente comando para tu gestor de paquetes preferido.

Ventana de la terminal
npm install @apostrophecms/apostrophe-astro vite @astrojs/node

Configurar Astro

Sección titulada “Configurar Astro”

Configura tanto la integración de apostrophe-astro como Vite en tu archivo astro.config.mjs.

El siguiente ejemplo proporciona la URL base de tu instancia de Apostrophe y las rutas a las carpetas en tu proyecto para mapear entre los widgets y tipos de plantilla de página de ApostropheCMS y tu proyecto de Astro. También configura el renderizado en el lado del servidor de Vite.

astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import apostrophe from '@apostrophecms/apostrophe-astro';
import { loadEnv } from 'vite';


const env = loadEnv("", process.cwd(), 'APOS');


export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone'
  }),
  integrations: [
    apostrophe({
      aposHost: 'http://localhost:3000',
      widgetsMapping: './src/widgets',
      templatesMapping: './src/templates'
    })
  ],
  vite: {
    ssr: {
      // Do not externalize the @apostrophecms/apostrophe-astro plugin, we need
      // to be able to use virtual: URLs there
      noExternal: [ '@apostrophecms/apostrophe-astro' ],
    },
    define: {
      'process.env.APOS_EXTERNAL_FRONT_KEY': JSON.stringify(env.APOS_EXTERNAL_FRONT_KEY),
      'process.env.APOS_HOST': JSON.stringify(env.APOS_HOST)
    }
  }
});

Para ver las opciones de configuración completas y sus explicaciones, consulta la documentación de apostrophe-astro.

Conectar widgets de ApostropheCMS a componentes de Astro

Sección titulada “Conectar widgets de ApostropheCMS a componentes de Astro”

Los widgets de ApostropheCMS son bloques de contenido estructurado que se pueden añadir a la página, como columnas de diseño, imágenes y bloques de texto. Deberás crear un componente de Astro para cada widget en tu proyecto de Apostrophe, además de un archivo para mapear esos componentes al widget de Apostrophe correspondiente.

Crea una nueva carpeta en src/widgets/ para tus componentes de Astro y el archivo de mapeo, index.js.

Los componentes mapeados ubicados en esta carpeta reciben una propiedad widget que contiene los campos del esquema de tu widget, y cualquier prop personalizada, a través de Astro.props. Estos valores estarán disponibles para la edición en la página.

El siguiente ejemplo muestra un componente RichTextWidget.astro accediendo al contenido de su widget de ApostropheCMS correspondiente para permitir la edición en contexto:

src/widgets/RichTextWidget.astro
---
const { widget } = Astro.props;
const { content } = widget;
---
<Fragment set:html={ content }></Fragment>

Algunos widgets estándar de Apostrophe, como las imágenes y los vídeos, requieren marcadores de posición porque por defecto no contienen contenido editable. El siguiente ejemplo crea un componente ImageWidget.astro estándar que establece el valor de src de forma condicional al valor de la imagen aposPlaceholder pasada por el widget, a una imagen alternativa del proyecto de Astro, o a la imagen seleccionada por el gestor de contenido utilizando el ayudante de adjuntos (attachment) de Apostrophe:

src/widgets/ImageWidget.astro
---
const { widget } = Astro.props;
const placeholder = widget?.aposPlaceholder;
const src = placeholder ?
  '/images/image-widget-placeholder.jpg' :
  widget?._image[0]?.attachment?._urls['full'];
---
<style>
  .img-widget {
    width: 100%;
  }
</style>
<img class="img-widget" {src} />

Para ver más ejemplos, consulta los ejemplos de widgets del proyecto inicial astro-frontend.

Cada componente .astro debe ser mapeado al widget principal de Apostrophe correspondiente en src/widgets/index.js.

El siguiente ejemplo añade los dos componentes anteriores a este archivo:

src/widgets/index.js
import RichTextWidget from './RichTextWidget.astro';
import ImageWidget from './ImageWidget.astro';


const widgetComponents = {
  '@apostrophecms/rich-text': RichTextWidget,
  '@apostrophecms/image': ImageWidget
};


export default widgetComponents;

Consulta la documentación de ApostropheCMS para conocer las convenciones de nomenclatura de widgets estándar, pro y personalizados del proyecto

El directorio del proyecto ahora debería verse así:

  • Directoriosrc/
    • Directoriowidgets/
      • index.js
      • ImageWidget.astro
      • RichTextWidget.astro
  • .env
  • astro.config.mjs
  • package.json

Añadir tipos de página

Sección titulada “Añadir tipos de página”

Al igual que los widgets, cualquier plantilla de tipo de página en tu proyecto de ApostropheCMS necesita tener un componente de plantilla correspondiente en tu proyecto de Astro. También necesitarás un archivo que mapee los tipos de página de Apostrophe a componentes individuales.

Crea una nueva carpeta en src/templates/ para tus componentes de Astro y el archivo de mapeo, index.js. Los componentes mapeados ubicados en esta carpeta reciben una propiedad page que contiene los campos de esquema de tu página, y cualquier prop personalizada, a través de Astro.props. Estos componentes también pueden acceder a un componente AposArea para renderizar las áreas de Apostrophe.

El siguiente ejemplo muestra un componente HomePage.astro renderizando una plantilla de página a partir de su tipo de página home-page de ApostropheCMS correspondiente, incluyendo un campo de esquema de área llamado main:

src/templates/HomePage.astro
---
import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro';
const { page, user, query } = Astro.props.aposData;
const { main } = page;
---


<section class="bp-content">
  <h1>{ page.title }</h1>
  <AposArea area={main} />
</section>

Cada componente .astro debe ser mapeado al tipo de página principal de Apostrophe correspondiente en src/templates/index.js.

El siguiente ejemplo añade el componente anterior HomePage.astro a este archivo:

src/templates/index.js
import HomePage from './HomePage.astro';


const templateComponents = {
  '@apostrophecms/home-page': HomePage
};


export default templateComponents;

Consulta la documentación de ApostropheCMS para conocer las convenciones de nomenclatura de plantillas, incluyendo páginas especiales y tipos de página de pieza.

El directorio del proyecto ahora debería verse así:

  • Directoriosrc/
    • Directoriowidgets/
      • index.js
      • ImageWidget.astro
      • RichTextWidget.astro
    • Directoriotemplates/
      • HomePage.astro
      • index.js
  • .env
  • astro.config.mjs
  • package.json

Crear el componente […slug.astro] y obtener datos de Apostrophe

Sección titulada “Crear el componente […slug.astro] y obtener datos de Apostrophe”

Dado que Apostrophe es responsable de conectar las URLs con el contenido, incluyendo la creación de nuevo contenido y páginas sobre la marcha, solo necesitarás un componente de página de Astro de nivel superior: la ruta [...slug].astro.

El siguiente ejemplo muestra un componente [...slug].astro mínimo:

src/pages/[...slug].astro
---
import aposPageFetch from '@apostrophecms/apostrophe-astro/lib/aposPageFetch.js';
import AposLayout from '@apostrophecms/apostrophe-astro/components/layouts/AposLayout.astro';
import AposTemplate from '@apostrophecms/apostrophe-astro/components/AposTemplate.astro';


const aposData = await aposPageFetch(Astro.request);
const bodyClass = `myclass`;


if (aposData.redirect) {
  return Astro.redirect(aposData.url, aposData.status);
}
if (aposData.notFound) {
  Astro.response.status = 404;
}
---
<AposLayout title={aposData.page?.title} {aposData} {bodyClass}>
    <Fragment slot="standardHead">
      <meta name="description" content={aposData.page?.seoDescription} />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta charset="UTF-8" />
    </Fragment>
    <AposTemplate {aposData} slot="main"/>
</AposLayout>

Consulta la documentación de ApostropheCMS para ver opciones de plantillas adicionales, incluyendo los slots disponibles en el componente AposTemplate.

Crear un blog con Astro y ApostropheCMS

Sección titulada “Crear un blog con Astro y ApostropheCMS”

Con la integración configurada, ahora puedes crear un blog con Astro y ApostropheCMS. Tu blog utilizará una pieza de Apostrophe, un tipo de contenido independiente que se puede incluir en cualquier página, y un tipo de página de pieza, un tipo de página especializado que se utiliza para mostrar esas piezas de forma de forma individual o colectiva.

Requisitos previos

Sección titulada “Requisitos previos”
  1. Un proyecto de ApostropheCMS con la herramienta CLI de Apostrophe instalada - Puedes crear un nuevo proyecto o utilizar uno existente. Sin embargo, este tutorial solo mostrará cómo crear una pieza de blog y un tipo de página de pieza. Tendrás que integrar cualquier otro código de proyecto existente de forma independiente. Si no tienes la herramienta CLI instalada, consulta las instrucciones de instalación de la CLI de Apostrophe.
  2. Un proyecto de Astro integrado con ApostropheCMS - Para crear un proyecto desde cero, consulta integrar con Astro para obtener instrucciones sobre cómo configurar la integración, o utiliza el proyecto inicial astro-frontend.

Crear una pieza de blog y un tipo de página de pieza

Sección titulada “Crear una pieza de blog y un tipo de página de pieza”

Para crear tu pieza de blog y el tipo de página de pieza para mostrarlos, navega a la raíz de tu proyecto de ApostropheCMS en tu terminal. Utiliza la herramienta de la CLI de ApostropheCMS para crear la nueva pieza y el tipo de página de pieza con el siguiente comando:

Ventana de la terminal
apos add piece blog --page

Esto creará dos nuevos módulos en tu proyecto, uno para el tipo de pieza de blog y otro para el tipo de página de pieza correspondiente. A continuación, abre el archivo app.js en la raíz de tu proyecto de ApostropheCMS en tu editor de código y añade tus nuevos módulos.

app.js
require('apostrophe')({
  // other configuration options
  modules: {
    // other project modules
    blog: {},
    'blog-page': {}
  }
});

El módulo blog-page también debe añadirse al array de opciones de types del módulo @apostrophecms/page para que pueda seleccionarse en el modal de creación de páginas. En tu proyecto de ApostropheCMS, abre el archivo modules/@apostrophecms/page/index.js y añade el blog-page.

modules/@apostrophecms/page/index.js
module.exports = {
  options: {
    types: [
      {
        name: '@apostrophecms/home-page',
        label: 'Home'
      },
      // Any other project pages
      {
        name: 'blog-page',
        label: 'Blog'
      }
    ]
  }
};

Crear el esquema del blog

Sección titulada “Crear el esquema del blog”

En un proyecto de ApostropheCMS, a los editores se les ofrece un conjunto de campos de entrada para añadir contenido. Aquí tienes un ejemplo de una publicación de blog simple que añade tres campos de entrada, un authorName, publicationDate y un área de content donde los gestores de contenido pueden añadir múltiples instancias de widgets. In crisis, estamos especificando que pueden añadir los widgets de imagen y de texto enriquecido que creamos durante la configuración de la integración.

modules/blog/index.js
module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Blog',
    // Additionally add a `pluralLabel` option if needed.
  },
  fields: {
    add: {
      authorName: {
        type: 'string',
        label: 'Author'
      },
      publicationDate: {
        type: 'date',
        label: 'Publication date'
      },
      content: {
        type: 'area',
        label: 'Content',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basic',
        fields: [ 'authorName', 'publicationDate', 'content' ]
      }
    }
  }
};

En este punto, todos los componentes procedentes del proyecto de ApostropheCMS están configurados. Inicia el sitio local desde la línea de comandos utilizando npm run dev, asegurándote de pasar la variable de entorno APOS_EXTERNAL_FRONT_KEY establecida con la cadena que hayas elegido:

Ventana de la terminal
APOS_EXTERNAL_FRONT_KEY='MyRandomString' npm run dev

Mostrar las publicaciones de blog

Sección titulada “Mostrar las publicaciones de blog”

Para mostrar una página con todas las publicaciones de blog, crea un archivo de componente BlogIndex.astro en el directorio src/templates de tu proyecto de Astro y añade el siguiente código:

Después de obtener tanto los datos de la página como los de las piezas de la prop aposData, este componente crea el marcado utilizando ambos campos del esquema de pieza de blog que creamos, pero también de piece.title y piece._url que Apostrophe añade a cada pieza.

src/templates/BlogIndex.astro
---
import dayjs from 'dayjs';


const { page, pieces } = Astro.props.aposData;
---


<section class="bp-content">
  <h1>{ page.title }</h1>


  <h2>Blog Posts</h2>


  {pieces.map(piece => (
    <h4>
      Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
    </h4>
    <h3>
      <a href={ piece._url }>{ piece.title }</a>
    </h3>
    <h4>{ piece.authorName }</h4>
  ))}
</section>

Para mostrar publicaciones de blog individuales, crea un archivo BlogShow.astro en la carpeta src/templates del proyecto de Astro con el siguiente código:

Este componente utiliza el componente <AposArea> para mostrar los widgets añadidos al área de content y el contenido de authorName y publicationDate introducido en los campos con los mismos nombres.

src/templates/BlogShow.astro
---
import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro';
import dayjs from 'dayjs';


const { page, piece } = Astro.props.aposData;
const { main } = piece;
---


<section class="bp-content">
  <h1>{ piece.title }</h1>
  <h3>Created by: { piece.authorName }
  <h4>
    Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
  </h4>
  <AposArea area={content} />
</section>

Finalmente, estos componentes de Astro deben ser mapeados a los tipos de página de ApostropheCMS correspondientes. Abre el archivo src/templates/index.js del proyecto de Astro y modifícalo para que contenga el siguiente código:

src/templates/index.js
import HomePage from './HomePage.astro';
import BlogIndexPage from './BlogIndexPage.astro';
import BlogShowPage from './BlogShowPage.astro';


const templateComponents = {
  '@apostrophecms/home-page': HomePage,
  '@apostrophecms/blog-page:index': BlogIndexPage,
  '@apostrophecms/blog-page:show': BlogShowPage
};


export default templateComponents;

Crear publicaciones de blog

Sección titulada “Crear publicaciones de blog”

Añadir publicaciones de blog a tu sitio se logra utilizando las herramientas de contenido y gestión de ApostropheCMS para crear esas publicaciones y publicando al menos una página de índice para mostrarlas.

Con el servidor de desarrollo de Astro en ejecución, navega a la página de inicio de sesión ubicada en http://localhost:4321/login en la vista previa de tu navegador. Utiliza las credenciales que se añadieron durante la creación del proyecto de ApostropheCMS para iniciar sesión como administrador. Tu proyecto de ApostropheCMS debería seguir ejecutándose.

Una vez que hayas iniciado sesión, tu navegador será redirigido a la página de inicio de tu proyecto y mostrará una barra de administración en la parte superior para editar contenido y gestionar tu proyecto.

Para añadir tu primera publicación de blog, haz clic en el botón Blogs de la barra de administración para abrir el modal de creación de piezas de blog. Al hacer clic en el botón New Blog en la parte superior derecha, se abrirá un modal de edición donde puedes añadir contenido. El campo del área content te permitirá añadir tantos widgets de imagen y de texto enriquecido como desees.

Puedes repetir este paso y añadir tantas publicaciones como quieras. También seguirás estos pasos cada vez que quieras añadir una nueva publicación.

Para publicar una página que muestre todas tus publicaciones, haz clic en el botón Pages en la barra de administración. En el modal del árbol de páginas, haz clic en el botón New Page. En el menú desplegable Type de la columna derecha, selecciona Blog. Añade un título para la página y haz clic en Publish and View. Solo tendrás que hacer esto una vez.

Cualquier nueva publicación de blog que se cree se mostrará automáticamente en esta página. Las publicaciones de blog individuales se pueden mostrar haciendo clic en el enlace creado en la página de índice.

El área de content de las publicaciones individuales se puede editar directamente en la página navegando a la publicación y haciendo clic en edit en la barra de administración. Otros campos se pueden editar utilizando el modal de edición que se abre al hacer clic en el elemento de menú Blogs en la barra de administración.

Desplegar tu sitio

Sección titulada “Desplegar tu sitio”

Para desplegar tu sitio web, necesitas alojar tus proyectos de Astro y ApostropheCMS.

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

Para el proyecto de ApostropheCMS, sigue las instrucciones para tu tipo de alojamiento en nuestra guía de alojamiento. Finalmente, tendrás que proporcionar una variable de entorno APOS_HOST al proyecto de Astro para reflejar la URL correcta donde se ha desplegado tu sitio de ApostropheCMS.

Recursos oficiales

Sección titulada "Recursos oficiales"

Recursos de la comunidad

Sección titulada "Recursos de la comunidad"

Más guías de CMS

Socios de CMS destacados

  • CloudCannon

    CMS basado en Git creado para mayor velocidad, seguridad y cero dolores de cabeza.

Todas las guías de CMS

Contribuir Comunidad Patrocinar