Crear una aplicación para la barra de herramientas de desarrollo

Astro incluye una barra de herramientas de desarrollo que puedes usar para inspeccionar tu sitio, comprobar problemas de accesibilidad y rendimiento, y más. Esta barra de herramientas puede extenderse con apps personalizadas.

Construir una dev toolbar app motivacional

En esta receta, aprenderás cómo crear una dev toolbar app que te ayuda a mantener la motivación mientras trabajas en tu sitio. Esta app mostrará un mensaje motivacional cada vez que la actives.

Consejo

¿Solo quieres empezar rápidamente? Inicia tu app creando un nuevo proyecto de Astro con la plantilla toolbar-app.

npm

npm create astro@latest -- --template toolbar-app

pnpm

pnpm create astro -- --template toolbar-app

Yarn

yarn create astro -- --template toolbar-app

O, sigue leyendo para aprender cómo construir una app desde cero.

Crear la integración de Astro

Las dev toolbar apps solo pueden ser añadidas por Astro Integrations usando el hook astro:config:setup. Necesitarás crear tanto una toolbar app como la integración que la añadirá a la barra de herramientas de tu proyecto de Astro existente.

1. En la raíz de tu proyecto de Astro existente, crea una nueva carpeta llamada my-toolbar-app/ para los archivos de tu app e integración. Crea dos nuevos archivos en esta carpeta: app.ts y my-integration.ts.

   • Directoriomy-toolbar-app/

     • app.ts
     • my-integration.ts
   • Directoriosrc/

     • Directoriopages/

       • …
     • …
   • astro.config.mjs
   • package.json
   • tsconfig.json

2. En my-integration.ts, añade el siguiente código para proporcionar tanto el nombre de tu integración como la función addDevToolbarApp() necesaria para añadir tu dev toolbar app con el hook astro:config:setup:

   my-toolbar-app/my-integration.ts

   import { fileURLToPath } from 'node:url';
   import type { AstroIntegration } from 'astro';
   
   export default {
     name: 'my-astro-integration',
     hooks: {
       'astro:config:setup': ({ addDevToolbarApp }) => {
         addDevToolbarApp({
           id: "my-toolbar-app",
           name: "My Toolbar App",
           icon: "🚀",
           entrypoint: fileURLToPath(new URL('./app.ts', import.meta.url))
         });
       },
     },
   } satisfies AstroIntegration;

   Usar rutas relativas para el entrypoint

   El entrypoint es la ruta a tu archivo de dev toolbar app relativa a la raíz de tu proyecto de Astro existente, no a la carpeta de integración (my-toolbar-app) misma.

   Para usar rutas relativas para los entrypoints, obtén la ruta al archivo actual usando import.meta.url y resuelve la ruta al entrypoint desde ahí.

3. Para usar esta integración en tu proyecto, añádela al array de integrations en tu archivo astro.config.mjs.

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import myIntegration from './my-toolbar-app/my-integration.ts';
   
   export default defineConfig({
     integrations: [myIntegration],
   })

4. Si no está ya corriendo, inicia el dev server. Si tu integración se ha añadido con éxito a tu proyecto, deberías ver una nueva app “undefined” en la dev toolbar.

   Pero, también verás un mensaje de error de que tu dev toolbar app ha fallado al cargar. Esto es porque aún no has construido la app en sí. Lo harás en la siguiente sección.

Consulta la documentación de Astro Integration API para más sobre cómo construir integraciones de Astro.

Crear la app

Las dev toolbar apps se definen usando la función defineToolbarApp() del módulo astro/toolbar. Esta función toma un objeto con una función init() que será llamada cuando la dev toolbar app se cargue.

Esta función init() contiene la lógica de tu app para renderizar elementos en la pantalla, enviar y recibir eventos del lado del cliente desde la dev toolbar, y comunicarse con el servidor.

app.ts

import { defineToolbarApp } from "astro/toolbar";

export default defineToolbarApp({
    init(canvas, app, server) {
      // ...
    },
});

Para mostrar mensajes motivacionales en la pantalla, usarás la propiedad canvas para acceder a un ShadowRoot estándar. Los elementos pueden crearse y añadirse al ShadowRoot usando las APIs estándar del DOM.

1. Copia el siguiente código en my-toolbar-app/app.ts. Esto proporciona una lista de mensajes motivacionales, y la lógica para crear un nuevo elemento <h1> con un mensaje aleatorio:

   my-toolbar-app/app.ts

   import { defineToolbarApp } from "astro/toolbar";
   
   const motivationalMessages = [
     "You're doing great!",
     "Keep up the good work!",
     "You're awesome!",
     "You're a star!",
   ];
   
   export default defineToolbarApp({
       init(canvas) {
         const h1 = document.createElement('h1');
         h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
   
         canvas.append(h1);
       },
   });

2. Inicia el dev server si no está ya corriendo y activa la app en la dev toolbar. Si tu app funciona correctamente, verás un mensaje motivacional mostrado en la esquina superior izquierda de la pantalla. (¡Y es verdad!)

   Sin embargo, este mensaje no cambiará cuando la app se active y desactive, ya que la función init() solo se llama una vez cuando la app se carga.

3. Para añadir interactividad del lado del cliente a tu app, añade el argumento app y usa onAppToggled() para seleccionar un nuevo mensaje aleatorio cada vez que tu toolbar app se active:

   app.ts

   import { defineToolbarApp } from "astro/toolbar";
   
   const motivationalMessages = [
     "You're doing great!",
     "Keep up the good work!",
     "You're awesome!",
     "You're a star!",
   ];
   
   export default defineToolbarApp({
       init(canvas, app) {
         const h1 = document.createElement('h1');
         h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
   
         canvas.append(h1);
   
         // Display a random message when the app is toggled
         app.onToggled(({ state }) => {
           const newMessage = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
           h1.textContent = newMessage;
         });
       },
   });

4. En tu preview del navegador, activa y desactiva tu app varias veces. Con este cambio, un nuevo mensaje aleatorio será seleccionado cada vez que actives la app, ¡proporcionándote una fuente infinita de motivación!

Consulta la documentación de Astro Dev Toolbar API para más sobre cómo construir dev toolbar apps.

Construir apps con un UI framework

UI frameworks como React, Vue, o Svelte también pueden usarse para crear dev toolbar apps. Estos frameworks proporcionan una forma más declarativa de crear UIs y pueden hacer tu código más mantenible y fácil de leer.

La misma dev toolbar app motivacional construida en tu proyecto de Astro existente anteriormente en esta página con JavaScript puede construirse usando un UI framework (ej. Preact) en su lugar. Dependiendo del framework que elijas, puede que necesites o no un paso de build.

Nota

Sin importar cómo elijas construir tu dev toolbar app, usando JavaScript o un UI framework, aún necesitarás crear la integración que añade tu app a la dev toolbar.

Sin paso de build

Si tu framework lo soporta, puedes crear una dev toolbar app sin un paso de build. Por ejemplo, puedes usar la función h de Preact para crear elementos y renderizarlos directamente al ShadowRoot:

app.ts

import { defineToolbarApp } from "astro/toolbar";
import { render, h } from "preact";

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
      render(h('h1', null, message), canvas);
    },
});

Alternativamente, el paquete htm es una buena opción para crear dev toolbar apps sin un paso de build, ofreciendo integración nativa para React y Preact y soporte para otros frameworks:

app.ts

import { defineToolbarApp } from "astro/toolbar";
import { render } from "preact";
import { html } from 'htm/preact';

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

export default defineToolbarApp({
    init(canvas) {
      const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
      render(html`<h1>${message}</h1>`, canvas);
    },
});

En ambos casos, ahora puedes iniciar tu proyecto y ver el mensaje motivacional mostrado en la esquina superior izquierda de la pantalla cuando actives la app.

Con paso de build

Astro no preprocesa código JSX en las dev toolbar apps, por lo que se requiere un paso de build para usar componentes JSX en tu dev toolbar app.

Los siguientes pasos usarán TypeScript para hacer esto, pero cualquier otra herramienta que compile código JSX también funcionará (ej. Babel, Rollup, ESBuild).

1. Instala TypeScript dentro de tu proyecto:

   npm

   npm install --save-dev typescript

   pnpm

   pnpm install --save-dev typescript

   Yarn

   yarn add --dev typescript

2. Crea un archivo tsconfig.json en la raíz de la carpeta de tu toolbar app con los ajustes apropiados para compilar y para el framework que estás usando (React, Preact, Solid). Por ejemplo, para Preact:

   my-toolbar-app/tsconfig.json

   {
     "compilerOptions": {
       "skipLibCheck": true,
       "module": "NodeNext",
       "jsx": "react-jsx",
       "jsxImportSource": "preact",
     }
   }

3. Ajusta el entrypoint en tu integración para apuntar al archivo compilado, recordando que este archivo es relativo a la raíz de tu proyecto de Astro:

   my-integration.ts

   addDevToolbarApp({
     id: "my-toolbar-app",
     name: "My Toolbar App",
     icon: "🚀",
     entrypoint: join(__dirname, "./app.js"),
   });

4. Ejecuta tsc para compilar tu toolbar app, o tsc --watch para recompilar automáticamente tu app cuando hagas cambios.

   Con estos cambios, ahora puedes renombrar tu archivo app.ts a app.tsx (o .jsx) y usar sintaxis JSX para crear tu dev toolbar app:

   app.tsx

   import { defineToolbarApp } from "astro/toolbar";
   import { render } from "preact";
   
   const motivationalMessages = [
     "You're doing great!",
     "Keep up the good work!",
     "You're awesome!",
     "You're a star!",
   ];
   
   export default defineToolbarApp({
       init(canvas) {
         const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
         render(<h1>{message}</h1>, canvas);
       },
   });

¡Ahora deberías tener todas las herramientas que necesitas para crear una dev toolbar app usando el UI framework que elijas!