Script Tags in Astro JS funktionieren anders als in klassischen HTML-Projekten. Wer nicht versteht, wie das Astro Framework Scripts verarbeitet, landet schnell in Production-Bugs: Scripts die lokal funktionieren, im Build aber schweigen. Die gute Nachricht: Das Prinzip ist einfach – wenn man die drei Patterns kennt.
Die offizielle Empfehlung der AstroJS-Docs ist eindeutig: Inline-Script mit Import ist der primäre Weg. Kein src=-Attribut, kein Framework-Overhead, kein Boilerplate. Das Astro Javascript Framework übernimmt TypeScript-Kompilierung, Bundling und Deduplication automatisch.
Die Astro-Docs zeigen in jedem Beispiel konsequent das Inline-Script mit Import als Standard. Das Script steht direkt in der .astro-Datei, Imports funktionieren wie gewohnt:
<script>
// npm-Pakete direkt importieren
import confetti from 'canvas-confetti';
// querySelector für Event-Handling
const buttons = document.querySelectorAll('[data-confetti-button]');
buttons.forEach((button) => {
button.addEventListener('click', () => confetti());
});
</script>
Was Astro im Hintergrund automatisch erledigt:
Astro verarbeitet ein <script> Tag nicht, sobald ein zusätzliches Attribut vorhanden ist – außer src. Das ist der häufigste Grund warum Scripts lokal funktionieren, im Production-Build aber nicht.
<!-- FALSCH: defer deaktiviert Astro-Processing -->
<script src="../scripts/menu.ts" defer></script>
<!-- FALSCH: type="module" manuell setzen ist nicht nötig und deaktiviert Processing -->
<script src="../scripts/menu.ts" type="module"></script>
<!-- RICHTIG: kein zusätzliches Attribut -->
<script src="../scripts/menu.ts"></script>
<!-- RICHTIG: inline ohne Attribute -->
<script>
import { init } from '../utils/init.ts';
init();
</script>
Der Reflex defer oder async hinzuzufügen kommt aus klassischem HTML – in Astro ist das kontraproduktiv. Astro setzt type="module" automatisch, und Module sind per Spezifikation immer deferred.
Wer Scripts in separate .js/.ts Dateien auslagert – etwa für größere Logik oder Wiederverwendung – kann src= nutzen. Das funktioniert aber nur für Dateien aus dem src/-Ordner:
<!-- Relative Pfade zu Dateien in src/ -->
<script src="../scripts/local.js"></script>
<script src="./script-with-types.ts"></script>
Diese Scripts werden genauso verarbeitet wie Inline-Scripts: TypeScript, Bundling, Deduplication. Der src=-Ansatz ist kein primäres Pattern in den Docs, sondern eine Alternative wenn die Script-Logik bereits als separate Datei vorliegt.
Wichtig: Kein zusätzliches Attribut – auch hier gilt: defer, async oder type="module" manuell draufzusetzen deaktiviert das Processing.
Für alles außerhalb von src/ – also CDN-Bibliotheken oder Dateien im public/-Ordner – ist is:inline Pflicht. Astro kann diese Dateien nicht bundeln oder transformieren:
<!-- Script aus public/ -->
<script is:inline src="/my-script.js"></script>
<!-- Externes CDN-Script -->
<script is:inline src="https://analytics.example.com/script.js"></script>
<!-- Globale Config-Variable setzen (kein Import nötig) -->
<script is:inline>
window.__SITE_CONFIG__ = { version: '2.0', env: 'production' };
</script>
is:inline deaktiviert bewusst TypeScript-Kompilierung, Bundling und Deduplication. Das bedeutet auch: Wird eine Komponente mit is:inline-Script mehrfach auf einer Seite eingebunden, wird das Script mehrfach gerendert.
Die Astro-Docs empfehlen für wiederverwendbare Komponenten explizit das Web Components / Custom Element Pattern. Der Grund: document.querySelector durchsucht die gesamte Seite – bei mehreren Instanzen einer Komponente greift jede Instanz auf alle anderen zu.
Custom Elements lösen das elegant: this.querySelector sucht nur innerhalb der eigenen Instanz. Der Browser ruft connectedCallback() für jede Instanz separat auf, obwohl das Script nur einmal gebundelt wird.
<astro-counter>
<button>Klick mich</button>
<span>0</span>
</astro-counter>
<script>
class AstroCounter extends HTMLElement {
connectedCallback() {
let count = 0;
// Sucht nur in DIESER Instanz, nicht auf der ganzen Seite
const button = this.querySelector('button');
const display = this.querySelector('span');
button.addEventListener('click', () => {
count++;
display.textContent = count.toString();
});
}
}
customElements.define('astro-counter', AstroCounter);
</script>
Dieser Ansatz funktioniert auch dann korrekt wenn die Komponente 10x auf einer Seite eingebunden ist – jede Instanz zählt unabhängig. Das ist der sauberste Weg für interaktive Astro-Komponenten ohne React, Vue oder Svelte.
Server-seitige Variablen aus dem Astro-Frontmatter sind im Client-Script nicht verfügbar – der Frontmatter-Code läuft nur beim Build. Der empfohlene Weg: Werte als data-*-Attribute auf HTML-Elemente schreiben, im Script auslesen.
---
const { message = 'Willkommen!' } = Astro.props;
---
<!-- Prop als data-Attribut speichern -->
<astro-greet data-message={message}>
<button>Hallo sagen</button>
</astro-greet>
<script>
class AstroGreet extends HTMLElement {
connectedCallback() {
// data-Attribut im Browser auslesen
const message = this.dataset.message;
this.querySelector('button').addEventListener('click', () => {
alert(message);
});
}
}
customElements.define('astro-greet', AstroGreet);
</script>
Dieses Muster nutzt Astro intern selbst für client:*-Direktiven: Props werden als props-Attribut auf <astro-island>-Elementen gespeichert und dann client-seitig hydratisiert.
src/. npm-Pakete, lokale Utils, TypeScript. Kein zusätzliches Attribut.src= mit Pfad zu src/ → Wenn Script-Logik bereits als separate Datei existiert. Gleiche Verarbeitung wie Inline.is:inline src= → CDN-Bibliotheken, Scripts aus public/, externe Analytics.is:inline ohne src → Kleine Config-Variablen (window.__FOO__), die kein Bundling brauchen.Was niemals funktioniert: import innerhalb von is:inline-Scripts. Der Import-Resolver ist bei is:inline deaktiviert.
Agentic engineering: the new default is that you are not writing the code directly 99% of the time, you are orchestrating agents who do and acting as oversight – engineering to emphasize that there is an art and science and expertise to it.
Entdeckt die Vorteile von Astro JS Islands für eure Webprojekte. Unsere Experten bieten fundierte Beratung und Schulungen zur effizienten Implementierung dieser leistungsstarken Architektur.
Mehr erfahren
Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.
Die offizielle Empfehlung laut Astro-Docs ist das Inline-Script mit Import-Statement direkt in der .astro-Datei. Astro übernimmt dabei automatisch TypeScript-Kompilierung, Bundling und Deduplication. Kein src=-Attribut, kein type="module" manuell setzen.
Der häufigste Grund: Ein zusätzliches Attribut wie defer, async oder type="module" deaktiviert Astros Script-Processing vollständig. Astro verarbeitet nur Script-Tags ohne zusätzliche Attribute – außer src. Defer ist in Astro unnötig, da type="module" automatisch gesetzt wird und Module immer deferred sind.
is:inline ist für drei Fälle gedacht: externe CDN-Scripts, Dateien aus dem public/-Ordner, und kleine inline Configs wie window.__FOO__. Bei is:inline entfallen TypeScript, Bundling und Deduplication. Wichtig: import-Statements funktionieren innerhalb von is:inline nicht.
Props aus dem Frontmatter sind im Browser nicht verfügbar, da der Frontmatter nur zur Build-Zeit läuft. Der empfohlene Weg: Werte als data-*-Attribute auf HTML-Elemente schreiben und im Script über this.dataset auslesen – am besten kombiniert mit dem Custom Element Pattern.
Beide werden von Astro gleich verarbeitet, solange keine zusätzlichen Attribute vorhanden sind. src= verweist auf eine externe .js/.ts-Datei in src/, das Inline-Script enthält den Code direkt in der .astro-Datei. Die Astro-Docs bevorzugen in Beispielen das Inline-Pattern mit Import.
document.querySelector durchsucht die gesamte Seite – bei mehreren Instanzen einer Komponente greift jede Instanz auf alle anderen zu. Custom Elements lösen das mit this.querySelector, das nur innerhalb der eigenen Instanz sucht. Außerdem läuft connectedCallback() für jede Instanz separat, obwohl das Script nur einmal gebundelt wird.
Ja – in Inline-Scripts und src=-Scripts aus src/ funktionieren npm-Imports direkt. Astro bundelt diese automatisch. Nicht möglich ist der Import in is:inline-Scripts: Dort ist der Bundler deaktiviert. Für CDN-Bibliotheken deshalb immer is:inline src= nutzen.
Astro selbst generiert statisches HTML ohne externe Datenverbindungen. DSGVO-Relevanz entsteht durch eingebundene Drittanbieter-Scripts wie Analytics oder Fonts. Diese sollten per is:inline src= eingebunden und durch ein Consent-Management-System gesteuert werden. NCA berät bei DSGVO-konformer Astro-Implementierung.
