Aller au contenu

Intégration Astro

Le package @unschema-graph/astro assure un support de premier ordre pour Astro 5, 6 et 7, avec une application Dev Toolbar interactive et des helpers pour les collections de contenu.


Automatique (CLI)

Fenêtre de terminal
npx astro add @unschema-graph/astro

pnpm

Fenêtre de terminal
pnpm add @unschema-graph/astro zod

npm

Fenêtre de terminal
npm install @unschema-graph/astro zod

yarn

Fenêtre de terminal
yarn add @unschema-graph/astro zod

bun

Fenêtre de terminal
bun add @unschema-graph/astro zod

Déclarez l’intégration dans astro.config.mjs :

astro.config.mjs
import { defineConfig } from 'astro/config';
import { schemaGraph } from '@unschema-graph/astro';
export default defineConfig({
site: 'https://mon-site.fr',
integrations: [
schemaGraph({
// Lève une exception au build pour éviter un mauvais SEO, avertit en dev :
onError: process.env.NODE_ENV === 'production' ? 'throw' : 'warn',
}),
],
});
Option Type Défaut Description
baseUrl string config.site URL canonique de base pour résoudre les fragments #id et URLs relatives.
inLanguage string locale de la route Locale BCP-47 par défaut lorsqu’aucune locale de route Astro n’est disponible.
onError 'throw' | 'warn' | 'silent' build: 'throw', dev: 'warn' Mode de sévérité de la validation.

La résolution est déterministe : la prop <Schema baseUrl> prime sur la baseUrl de l’intégration, qui prime sur site d’Astro. Pour la locale : <Schema inLanguage>, puis Astro.currentLocale, puis la valeur par défaut de l’intégration.


Insérez <Schema /> dans le <head> de votre layout principal ou sur une page dédiée. Le composant sérialise vos entités en <script type="application/ld+json"> avec zéro JavaScript côté client.

src/layouts/BaseLayout.astro
---
import { Organization, Schema, WebSite } from '@unschema-graph/astro';
interface Props {
title: string;
items?: any[];
}
const { title, items = [] } = Astro.props;
// Identité globale du site présente sur toutes les pages
const site = WebSite({
'@id': '#website',
name: 'Acme Corp',
url: 'https://mon-site.fr',
publisher: '#organization',
});
const org = Organization({
'@id': '#organization',
name: 'Acme Corp',
url: 'https://mon-site.fr',
logo: 'https://mon-site.fr/logo.png',
});
---
<!doctype html>
<html lang={Astro.currentLocale ?? 'fr'}>
<head>
<meta charset="utf-8" />
<title>{title}</title>
<!-- Rendu des entités globales + entités de la page dans un seul @graph -->
<Schema items={[site, org, ...items]} />
</head>
<body>
<slot />
</body>
</html>

Transmettre les entités d’une page à un layout

Section intitulée « Transmettre les entités d’une page à un layout »

unschema-graph découvre automatiquement les entités au sein du graphe d’objets qu’il reçoit. Il parcourt les relations imbriquées, remonte les entités référencées dotées d’un @id, les déduplique et émet un @graph unifié.

const organization = Organization({
'@id': '#organization',
name: 'Acme',
});
const article = Article({
'@id': '#article',
headline: 'Hello',
publisher: organization,
});

Transmettre uniquement article à <Schema /> suffit pour qu’organization soit découverte automatiquement :

Article
↓ publisher
Organization
↓
automatic discovery
↓
Organization promoted into @graph
↓
Article.publisher replaced by { "@id": ... }

En revanche, Astro n’expose pas implicitement les variables arbitraires créées dans une page à son layout parent. Il s’agit d’une contrainte de flux de données propre aux composants Astro, et non d’une limitation de résolution de graphe : les variables de page doivent être transmises explicitement au layout via des props.

Le modèle recommandé consiste à transmettre les entités racines de la page au layout via une prop telle que schemaItems.

src/pages/blog/building-structured-data.astro
---
import BaseLayout from '../../layouts/BaseLayout.astro';
import {
Article,
Organization,
} from '@unschema-graph/astro';
const organization = Organization({
'@id': '#organization',
name: 'Acme Media',
url: 'https://example.com',
});
const article = Article({
'@id': '#article',
headline: 'Building structured data with Astro',
author: 'Ada Lovelace',
publisher: organization,
});
---
<BaseLayout
title="Building structured data with Astro"
schemaItems={[article]}
>
<article>
<h1>Building structured data with Astro</h1>
</article>
</BaseLayout>

Seul article est transmis à schemaItems. organization n’a pas besoin d’être passée séparément car elle est accessible via article.publisher et découverte automatiquement par le moteur de graphe.

Dans le layout partagé, déclarez schemaItems dans Props à l’aide du type public SchemaOrgEntity, puis transmettez-le à <Schema items={schemaItems} /> :

src/layouts/BaseLayout.astro
---
import { Schema } from '@unschema-graph/astro';
import type { SchemaOrgEntity } from '@unschema-graph/astro';
interface Props {
title: string;
schemaItems?: SchemaOrgEntity[];
}
const {
title,
schemaItems = [],
} = Astro.props;
---
<html lang="fr">
<head>
<title>{title}</title>
<Schema items={schemaItems} />
</head>
<body>
<slot />
</body>
</html>

Vous devez seulement transmettre les entités racines à rendre. Les entités liées présentes dans ces objets et disposant d’un @id sont découvertes et remontées automatiquement dans le graphe.

Ce modèle est recommandé pour plusieurs raisons :

  • Il maintient la création de schéma au plus près de la page et du contenu concerné.
  • Il confie au layout partagé la responsabilité d’afficher un unique <Schema /> dans <head>.
  • Il préserve un script JSON-LD et un @graph unifiés.
  • Il évite les instances <Schema /> dupliquées lors de l’imbrication de pages et layouts.
  • Il ne requiert aucun middleware ni état global.
  • Il s’intègre naturellement au modèle de props explicites d’Astro.

La frontière entre Astro et unschema-graph s’organise en deux flux distincts :

Astro data flow:
Page
↓ explicit prop
BaseLayout
↓
<Schema items={schemaItems} />
unschema-graph data flow:
root entities
↓
relationship traversal
↓
entity discovery
↓
ID resolution
↓
deduplication
↓
single @graph
  • <Schema /> directement dans chaque page : Valide, mais si le layout rend également des données structurées (comme des métadonnées WebSite ou Organization globales), la page produit plusieurs balises <script type="application/ld+json">. Bien que la présence de plusieurs scripts JSON-LD soit syntaxiquement valide en HTML et Schema.org, le modèle basé sur les props du layout est préférable lorsque l’on souhaite un @graph centralisé.
  • Construire tous les schémas dans le layout : Possible, mais moins modulaire car le layout doit connaître le contenu spécifique à chaque page, son frontmatter ou les paramètres de route.
  • Middleware, contexte ou store global : Envisageable dans des architectures spécifiques, mais inutile pour les applications Astro classiques (statiques ou SSR) où les props gèrent le flux de données de manière explicite.

En mode développement (astro dev), @unschema-graph/astro injecte automatiquement une icône interactive dans la Dev Toolbar d’Astro au bas de votre navigateur.

  • Inspecteur de graphe en temps réel : Visualisez chaque entité détectée dans le @graph de la page courante avec son @type et son @id résolu.
  • Diagnostics du graphe : Affiche les références locales cassées et les conflits de fusion remontés pendant le rendu serveur.
  • Contexte de rendu : Affiche le nombre de nodes, la baseUrl, la locale et le nombre d’avertissements.
  • Copie JSON-LD : Copie la charge générée pour inspection ou test externe.

Le composant reste rendu côté serveur et n’envoie aucun JavaScript client. Les métadonnées de la toolbar utilisent des attributs data-* inertes, lus uniquement par la toolbar de développement Astro.


Lors de l’affichage d’articles Markdown ou MDX, @unschema-graph/astro/content offre des adaptateurs automatiques :

src/pages/blog/[slug].astro
---
import { getEntry, render } from 'astro:content';
import { toBlogPosting } from '@unschema-graph/astro/content';
import BaseLayout from '../../layouts/BaseLayout.astro';
const post = await getEntry('blog', Astro.params.slug!);
if (!post) return Astro.redirect('/404');
const { Content } = await render(post);
// Mappe automatiquement title, description, pubDate et author vers BlogPosting
const blogPosting = toBlogPosting(post, {
url: Astro.url.href,
publisher: '#organization',
});
---
<BaseLayout title={post.data.title} items={[blogPosting]}>
<article>
<h1>{post.data.title}</h1>
<Content />
</article>
</BaseLayout>

Helpers disponibles :

  • toArticle(entry, overrides?)
  • toBlogPosting(entry, overrides?)
  • toNewsArticle(entry, overrides?)

En savoir plus sur le mapping des Collections de contenu →