Créer une application pour la barre d'outils de développement

Astro inclut une barre d’outils de développement que vous pouvez utiliser pour inspecter votre site, pour vérifier l’accessibilité et les problèmes de performance, et plus encore. Cette barre d’outils peut être étendue avec des applications personnalisées.

Créer une application de motivation pour la barre d’outils de développement

Dans cette recette, vous apprendrez à créer une application pour la barre d’outils de développement qui vous aidera à rester motivé pendant que vous travaillez sur votre site. Cette application affichera un message motivant chaque fois que vous l’activerez.

Vous voulez démarrer rapidement ? Créez un nouveau projet Astro avec le template toolbar-app.

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

pnpm create astro -- --template toolbar-app

yarn create astro -- --template toolbar-app

Ou, continuez à apprendre comment créer une application depuis le début.

Créer une intégration Astro

Les applications de la barre d’outils de développement peuvent être ajoutées par les intégrations Astro en utilisant le hook astro:config:setup. Vous devrez créer à la fois une application pour la barre d’outils et l’intégration qui l’ajoutera à la barre d’outils de votre projet Astro existant.

À la racine de votre projet Astro, créez un nouveau dossier nommé my-toolbar-app/ pour votre application et les fichiers de l’intégration. Créez deux nouveaux fichiers dans ce dossier : app.ts et my-integration.ts.
- Répertoiremy-toolbar-app/
  - app.ts
  - my-integration.ts
- Répertoiresrc/
  - Répertoirepages/
    …
  - …
- astro.config.mjs
- package.json
- tsconfig.json
Dans my-integration.ts, ajoutez le code suivant pour fournir à la fois le nom de votre intégration et la fonction addDevToolbarApp() requise pour ajouter votre application de barre d’outils avec le 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: "Mon Application de Barre d'outils",
        icon: "🚀",
        entrypoint: fileURLToPath(new URL('./app.ts', import.meta.url))
      });
    },
  },
} satisfies AstroIntegration;
```
La propriété entrypoint correspond au chemin du fichier de votre application de barre d’outils, et non au dossier de l’intégration (my-toolbar-app). Ce chemin doit être relatif à la racine de votre projet Astro.
Pour utiliser des chemins relatifs pour les points d’entrée, obtenez le chemin du fichier courant avec import.meta.url et résolvez le chemin vers le point d’entrée à partir de là.

Pour utiliser cette intégration dans votre projet, ajoutez-la au tableau integrations dans votre fichier astro.config.mjs.

import { defineConfig } from 'astro/config';
import myIntegration from './my-toolbar-app/my-integration.ts';

export default defineConfig({
  integrations: [myIntegration],
})

S’il n’est pas déjà en cours d’exécution, démarrez le serveur web. Si l’intégration a été ajoutée avec succès à votre projet, vous devriez voir une nouvelle application “undefined” dans la barre d’outils Dev.

Cependant, vous verrez également un message d’erreur indiquant que votre application de barre d’outils n’a pas pu être chargée. Cette erreur survient parce que l’application n’a pas encore été créée. Vous allez le faire dans la section suivante.

Consultez la documentation de l’API Integration d’Astro pour en apprendre plus sur la création d’intégration pour Astro.

Créer l’application

Les applications de barre d’outils de développement sont définies en utilisant la fonction defineToolbarApp() du module astro/toolbar. Cette fonction prend comme argument un objet contenant une fonction init() qui sera appelée quand l’application de la barre d’outils sera chargée.

Cette fonction init() contient la logique de votre application pour afficher les éléments sur votre écran, pour envoyer et recevoir les événements côté client depuis la barre d’outils de développement, et pour communiquer avec le serveur.

import { defineToolbarApp } from "astro/toolbar";

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

Pour afficher des messages de motivation à l’écran, vous utiliserez la propriété canvas pour accéder au standard ShadowRoot. Les éléments peuvent être créés et ajoutés au ShadowRoot en utilisant les API standards du DOM.

Copiez le code suivant dans my-toolbar-app/app.ts. Celui-ci fournit une liste de messages de motivation, ainsi que la logique pour créer un nouvel élément <h1> avec un message aléatoire :

import { defineToolbarApp } from "astro/toolbar";

const motivationalMessages = [
  "Tu t'en sors bien !",
  "Continues ton bon travail !",
  "Tu es génial !",
  "Tu es une star !",
];

export default defineToolbarApp({
    init(canvas) {
      const h1 = document.createElement('h1');
      h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];

      canvas.append(h1);
    },
});

Démarrez le serveur de développement s’il n’est pas déjà en cours d’exécution et activer l’application dans la barre d’outils de développement. Si votre application fonctionne correctement, vous verrez un message de motivation affiché dans le coin en haut à gauche de votre écran. (Et, c’est vrai !)

Cependant, ce message ne changera pas quand l’application sera désactivée puis réactivée puisque la fonction init() est appelée une seule fois quand l’application est chargée.

Pour ajouter de l’interactivité côté client à votre application, ajoutez l’argument app et utilisez onAppToggled() pour sélectionner un nouveau message aléatoire à chaque fois que votre application de barre d’outils est activée :

import { defineToolbarApp } from "astro/toolbar";

const motivationalMessages = [
  "Tu t'en sors bien !",
  "Continues ton bon travail !",
  "Tu es génial !",
  "Tu es une star !",
];

export default defineToolbarApp({
    init(canvas, app) {
      const h1 = document.createElement('h1');
      h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];

      canvas.append(h1);

      // Affiche un message aléatoire quand l'application est activée
      app.onToggled(({ state }) => {
        const newMessage = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
        h1.textContent = newMessage;
      });
    },
});

Dans votre navigateur, activez et désactivez votre application plusieurs fois. Avec ce changement, un nouveau message aléatoire sera sélectionné à chaque fois que vous activez l’application, ce qui vous procurera une source infinie de motivation !

Consultez la documentation de l’API Dev Toolbar d’Astro pour en apprendre plus sur la création d’applications pour la barre d’outils de développement.

Construire des applications avec un framework UI

Les frameworks UI comme React, Vue ou Svelte peuvent aussi être utilisés pour créer des applications de barre d’outils de développement. Ces frameworks fournissent une manière plus déclarative de créer des interfaces utilisateurs et peuvent rendre votre code plus maintenable et plus facile à lire.

La même application de motivation construite précédemment avec Javascript peut être créée en utilisant un framework UI (ex. Preact) en remplacement. Selon le framework choisi, vous aurez peut-être besoin d’une étape de construction.

Sans étape de construction

Si votre framework le supporte, vous pouvez créer une application pour la barre d’outils de développement sans étape de construction. Par exemple, vous pouvez utiliser la fonction h de Preact pour créer des éléments et les générer directement dans la ShadowRoot :

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

const motivationalMessages = [
  "Tu t'en sors bien !",
  "Continues ton bon travail !",
  "Tu es génial !",
  "Tu es une star !",
];

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

Sinon, le paquet htm est un bon choix pour créer des applications de barre d’outils de développement sans étape de construction, vous offrant ainsi une intégration native pour React et Preact et le support d’autres frameworks :

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

const motivationalMessages = [
  "Tu t'en sors bien !",
  "Continues ton bon travail !",
  "Tu es génial !",
  "Tu es une star !",
];

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

Dans les deux cas, vous pouvez maintenant démarrer votre projet et voir le message de motivation affiché dans le coin en haut à gauche de votre écran quand vous activez l’application.

Avec une étape de construction

Astro ne prétraite pas le code JSX dans les applications de barre d’outils de développement donc une étape de construction est nécessaire afin d’utiliser des composants JSX dans votre application.

Les étapes suivantes utiliseront TypeScript pour y parvenir, mais n’importe quel autre outil qui compile du code JSX fonctionnera également (par ex. Babel, Rollup, ESBuild).

Installez TypeScript dans votre projet:
- npm
- pnpm
- Yarn
Fenêtre de terminal
npm install --save-dev typescript
Fenêtre de terminal
pnpm install --save-dev typescript
Fenêtre de terminal
yarn add --dev typescript
Créez un fichier tsconfig.json à la racine du dossier de votre application de barre d’outils avec les réglages appropriés pour la construction et pour le framework que vous utilisez (React, Preact, Solid). Par exemple, pour Preact:
my-toolbar-app/tsconfig.json
```
{
  "compilerOptions": {
    "skipLibCheck": true,
    "module": "NodeNext",
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
  }
}
```
Ajustez le point d’entrée entrypoint dans votre intégration pour pointer vers le fichier compilé, en vous rappelant que le chemin du fichier doit être relatif à la racine de votre projet Astro :
my-integration.ts
```
addDevToolbarApp({
  id: "my-toolbar-app",
  name: "Mon Application de Barre d'outils",
  icon: "🚀",
  entrypoint: join(__dirname, "./app.js"),
});
```

Exécutez tsc pour construire votre application de barre d’outils, ou tsc --watch pour regénérer automatiquement votre application à chaque changement.

Avec ces changements, vous pouvez maintenant renommer votre fichier app.ts en app.tsx (ou .jsx) et utiliser la syntaxe JSX pour créer votre application de barre d’outils :

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

const motivationalMessages = [
  "Tu t'en sors bien !",
  "Continues ton bon travail !",
  "Tu es génial !",
  "Tu es une star !",
];

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

Vous devriez maintenant avoir tous les outils nécessaires pour créer une application pour la barre d’outils de développement en utilisant le framework UI de votre choix !

Créer une issue GitHub

Envoyez-nous un commentaire