Intégration Astro

Astro est un framework Web insulaire conçu pour les sites riches en contenu. @astrojs/bext est l'adaptateur Astro qui cible bext : vous conservez l'expérience de création de Astro, et bext fournit la couche HTTP, le cache, le WAF, HTTP/2/3 et l'écosystème de plugins que chaque adaptateur réinvente autrement.

Version préliminaire. L'adaptateur et le framework côté Rust runtime dans le navire crates/bext-framework-astro dans le cadre de Jalon E6 de bext. Voir le feuille de route de l'écosystème pour ce qui a atterri et ce qui est encore sur la liste de suivi.

Installer#

bun add -d @astrojs/bext

Dépendances homologues : astro ^4 ou astro ^5.

Configurer#

Dans astro.config.mjs :

import { defineConfig } from "astro/config";
import bext from "@astrojs/bext";

export default defineConfig({
  output: "server",
  adapter: bext({
    runtime: "bun",
  }),
});

L'adaptateur s'enregistre dans le hook astro:config:setup et appelle setAdapter() dans astro:config:done. Astro est ensuite construit avec la sortie du serveur, produisant dist/server/entry.mjs plus un répertoire dist/client d'actifs hachés.

Possibilités#

Construire#

bun run build

La build émet :

dist/
  client/            hashed JS, CSS, fonts
  server/
    entry.mjs        SSR entry exporting { handler }
  bext-adapter.json  metadata for the bext runtime

bext-adapter.json est le contrat entre @astrojs/bext et crates/bext-framework-astro. Cela ressemble à :

{
  "adapter": "@astrojs/bext",
  "version": "0.1.0-preview",
  "runtime": "bun",
  "serverEntry": "server/entry.mjs",
  "clientDir": "client",
  "generatedAt": "2026-04-11T12:00:00.000Z"
}

Servir#

Via bext.config.toml#

[framework]
type = "astro"
build_dir = "dist"

[build]
script = "dist/server/entry.mjs"
watch_dirs = ["src"]
live_reload = true

Alors:

bext serve

Le vhost de bext détecte le projet comme Astro (sur astro.config.* + astro dans package.json ), lit la sortie de build et distribue les requêtes au gestionnaire Astro via l'adaptateur d'exécution du framework.

Via bext new#

bext new my-astro-app --template @bext/starter-astro
cd my-astro-app
bun install
bun run build
bext serve

Le démarreur est livré avec astro.config.mjs, une mise en page Base.astro, deux pages ( / et /about ) et la plomberie bext.config.toml pré-câblée.

Comment ça s'articule#

Trois pièces mobiles collaborent sur chaque demande Astro via bext :

1. @astrojs/bext (ce package) — Intégration Astro et adaptateur. S'exécute au moment de la construction. Produit dist/ et bext-adapter.json.
2. crates/bext-framework-astro — Rouille FrameworkAdapter mise en œuvre. S'exécute au moment de la configuration du serveur. Détecte le projet, appelle bunx astro build (ou npx astro build ), normalise la sortie et vend un adaptateur d'exécution.
3. bext-server vhost — par demande. Itinéraires entrants requêtes à l'adaptateur d'exécution Astro, qui à son tour les envoie au sous-processus Node / Bun exécutant dist/server/entry.mjs.

Comment cela se compare-t-il à @astrojs/node#

@astrojs/node produit un serveur Node autonome que vous exécutez vous-même. @astrojs/bext ignore la couche HTTP — bext le fournit — et émet simplement l'entrée SSR compilée ainsi que les actifs statiques. bext ajoute ensuite TLS, HTTP/2/3, le cache, WAF, la compression et l'écosystème complet de plugins sans que Astro n'ait besoin d'en connaître aucun.

Si vous exécutez actuellement @astrojs/node derrière nginx, @astrojs/bext remplace les deux calques en un seul mouvement.

Ce qui fonctionne aujourd'hui#

• Routage du système de fichiers ( src/pages/* )
• Itinéraires dynamiques avec [param].astro
• Itinéraires API ( src/pages/api/* )
• Collections de contenu
• MDX (avec @astrojs/mdx)
• Îles via client:load, client:visible, etc.
• Sortie hybride ( output: "hybrid" )
• Pages pré-rendues ( export const prerender = true )
• Actifs statiques servis à partir de dist/client/

Limites actuelles#

• L'envoi du sous-processus est toujours TODO. Pour l'aperçu E6, le l'adaptateur d'exécution est uniquement un descripteur - bext-framework-astro handle_request renvoie une erreur non encore câblée. Le suivi consiste à apprendre au vhost du serveur bext à envoyer au sous-processus Node / Bun qui importe dist/server/entry.mjs, en réutilisant la même plomberie de sous-processus que bext a déjà pour PHP / FastCGI.
• Aucune réponse en streaming pour l’instant. Le app.render() de Astro peut renvoie un flux Response. L'aperçu les met en mémoire tampon. Les transmettre via le rédacteur de réponses de bext atterrit avec le streaming Crochet FrameworkAdapter::render.
• Aucune prise en charge du runtime Edge. Cet adaptateur cible Node / Bun. La sortie compatible avec les Workers de style Edge est hors de portée pour E6.
• Le service d’imagerie n’est pas encore ponté. Image intégrée de Astro Le service fonctionne, mais il ne passe pas par le pipeline multimédia de bext pour la mise en cache ou la transformation. L'intégration avec le pipeline d'images de bext est un suivi.
• Aucune version native de Rust. @astrojs/bext débourse pour astro build — La version de Astro est un ensemble de plugins Vite et sa réécriture dans Rust est hors de portée pour l'E6. Un pipeline direct turbopack / chignon figure sur la feuille de route de l'écosystème.

Dépannage#

• astro build produced no dist/ directory — la build a été exécutée mais n'a pas émis la mise en page attendue. Vérifiez à nouveau que astro.config.mjs a output: "server" et que l'adaptateur est installé en tant que dépendance de développement.
• AstroRuntime::handle_request is not wired yet — vous êtes voir la limitation du descripteur E6 uniquement. La construction fonctionne, la détection fonctionne, mais l'envoi par demande est prévu pour le suivi. En attendant, utilisez @astrojs/node derrière bext comme proxy inverse si vous avez besoin de trafic de production maintenant.
• Incompatibilité de dépendance entre Astro v4 et v5 — peerDependencies est défini sur "astro": "^4 || ^5". Si votre fichier de verrouillage épingle une version majeure antérieure, les hooks d'intégration ne seront pas résolus : mettez à niveau Astro ou utilisez un adaptateur plus ancien.

Documents associés#

• @bext/starter-astro — échafaudage de démarrage
• Présentation du cadre bext — comment les adaptateurs composer avec le pipeline de requêtes de bext
• PRISM — Le moteur natif TSX vers HTML de bext, un autre Implémentation FrameworkAdapter

Links#

• Astro — documentation officielle Astro et API de l'adaptateur