Cómo integrar GrapesJS en una app de Astro (guía completa 2026)

Por qué GrapesJS encaja con Astro

Astro no incluye JavaScript por defecto y te permite optar por el código del lado del cliente por componente. GrapesJS es un editor solo para navegador, así que lo cargas en un cliente script y guardar a través de un endpoint de la API de Astro. Esta guía monta el editor, persiste contenido y exporta HTML/CSS.

1. Montar el editor en un script cliente

Crear src/pages/editor.astro. Las <script> carreras en el navegador, así que importar GrapesJS allí es seguro.

---
// src/pages/editor.astro
---
<link href="https://unpkg.com/grapesjs/dist/css/grapes.min.css" rel="stylesheet" />
<div id="gjs"><h1>Edit me in GrapesJS</h1></div>

<script>
  import grapesjs from 'grapesjs';

  const editor = grapesjs.init({
    container: '#gjs',
    height: '100vh',
    fromElement: true,
    storageManager: {
      type: 'remote',
      stepsBeforeSave: 3,
      options: { remote: { urlStore: '/api/page', urlLoad: '/api/page' } },
    },
  });
</script>

2. Añadir un endpoint de la API de Astro

Crear src/pages/api/page.ts. Extremos SSR exportan el método HTTP funciones.

import type { APIRoute } from 'astro';
import { loadPage, savePage } from '../../lib/store';

export const GET: APIRoute = async () => {
  return new Response(JSON.stringify(await loadPage('home')), {
    headers: { 'Content-Type': 'application/json' },
  });
};

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();
  await savePage('home', data);   // your DB / KV write
  return new Response(JSON.stringify({ status: 'ok' }));
};

Activar un adaptador SSR (output: 'server' o 'hybrid' en astro.config.mjs) por lo que el POST se gestiona en el momento de la solicitud.

3. Exportar el margen final

const html = editor.getHtml();
const css = editor.getCss();
// Persist or render: `<style>${css}</style>${html}`

Trampas comunes en Astro

El cero JS por defecto de Astro es lo que hay que recordar. El editor debe ejecutarse en el lado del cliente — una etiqueta simple <script> o una isla de framework con client:only; importar GrapesJS en frontmatter (contexto de servidor) fallará. El guardado necesita tiempo de ejecución: una compilación totalmente estática no puede aceptar un POST, así que configúrase output: 'server' o 'hybrid' con un adaptador SSR antes de cablear el Gestor de Almacenamiento a /api/page. Y mantén la ruta del editor fuera de cualquier lista de prerenderizado — quieres que se renderice bajo demanda, no que se congele en la compilación.

Requisitos previos

Necesitarás Node.js 18+ y un proyecto de Astro 4. Si aceptas una partida guardada en tiempo de ejecución, tendrás también quiero un adaptador SSR (output: 'server' o 'hybrid'). No existe ningún paquete GrapesJS específico para Astro — el editor se ejecuta en el navegador mediante un script cliente o una isla de framework, y los endpoints de Astro gestionan la persistencia.

Añadir bloques personalizados al editor

Registra bloques arrastrables con el Gestor de Bloques después grapesjs.init de dentro de tu script cliente:

editor.BlockManager.add('hero', {
  label: 'Hero section',
  category: 'Sections',
  content: '<section class="hero"><h1>Headline</h1><p>Copy</p></section>',
});

Saca librerías de bloques y presets listos de GJS. Haz marketing para un conjunto más rico.

Análisis profundo del almacenamiento: un adaptador personalizado

Un adaptador de almacenamiento personalizado publica el proyecto en el endpoint de tu API de Astro:

editor.Storage.add('astro-store', {
  async load() {
    const res = await fetch('/api/page');
    return res.ok ? res.json() : {};
  },
  async store(data) {
    await fetch('/api/page', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
  },
});
// then: storageManager: { type: 'astro-store' }

Mantén la ruta del editor fuera de cualquier lista de prerenderizado para que se renderice bajo demanda, no congelada en la compilación.

Consejos de rendimiento

Astro ships no tiene JS por defecto, así que el peso del editor es opt-in — cárgalo solo en la ruta del editor mediante un script o client:only isla cliente. División de códigos Plugins pesados. Como el resto del sitio permanece estático, tus páginas públicas permanecen Rápido incluso con un editor pesado detrás de una ruta administrativa.

Consideraciones de seguridad

Autentica y autoriza el endpoint POST antes de escribir — un sitio con sensación estática Todavía necesita una ruta de guardado protegida. Limpia el margen almacenado en la salida si los no administradores pueden Edición. Valida el tamaño de la carga útil para que un proyecto grande no pueda agotar la memoria.

Resolución de errores comunes

Un error de importación en el frontmatter significa que importaste GrapesJS en el Contexto del servidor — mantenlo en un cliente <script> o en un client:only isla. El POST 404 suele fallar significa que no hay adaptador SSR; cambiar a output: 'server' o 'hybrid'. Un lienzo sin estilo o en blanco significa el La hoja de estilo no se cargaba o el contenedor no estaba presente.

Cuándo usar GrapesJS con Astro

GrapesJS se adapta cuando un sitio de Astro estático necesita un editor visual integrado detrás de una ruta administrativa — un creador de páginas o compositor de boletín — con tu propia almacenamiento y salida HTML. Para contenido puramente estático editado en markdown, Astro's Las colecciones de contenido son más sencillas; para la composición visual a página completa, GrapesJS es el una opción más fuerte, licenciada por el MIT.

Próximos pasos

Ver el GrapesJS + Svelte relacionado y GrapesJS + React , consulta las Mercado GrapesJS, o empieza desde el GJS. Página principal del mercado.

Preguntas frecuentes

¿Funciona GrapesJS en una isla Astro?

Sí — usa un lado <script> del cliente o una isla de marco con client:only así que GrapesJS se ejecuta en el navegador.

¿Cómo guardo contenido de GrapesJS en Astro?

Añadir un endpoint API en src/pages/api la POST exportación y Haz que el Gestor de Almacenamiento publique el JSON del proyecto en él.

¿Necesito un adaptador para el endpoint de guardado?

Sí, para manejar POST en tiempo de ejecución se necesita un adaptador SSR (output: 'server' o 'hybrid'); una construcción totalmente estática No puedo aceptar escrituras.