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.
Roland Golla ist nicht nur Gründer von Never Code Alone, sondern ein anerkannter IT-Spezialist mit über 20 Jahren Erfahrung in der Softwareentwicklung. Mit der Expertise aus über 300 erfolgreich abgeschlossenen Web-Projekten entwickelt er heute das NCA AI CMS – eine Lösung, die tiefgreifendes technisches Know-how mit modernster Künstlicher Intelligenz verbindet.
Als offizieller Cypress.IO Ambassador, Speaker auf internationalen Konferenzen und YouTube-Creator für führende Testing-Tools weiß er genau, worauf es bei digitaler Qualität ankommt. Sein Fokus: KI-Systeme (wie Claude 3 und Mistral AI), die nicht nur Texte generieren, sondern echte Geschäftsprozesse für lokale Dienstleister automatisieren und messbare Ergebnisse liefern.
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.
Entdecken Sie die Accessible Astro Components – barrierefreie UI-Komponenten für Astro, die WCAG-konforme, benutzerfreundliche und moderne Webanwendungen ermöglichen. Ideal für inklusives Design und optimierte User Experience.
Entdecken Sie, wie Astro Images Ihre Website-Performance und SEO-Rankings revolutioniert. Unsere Agentur bietet Ihnen das nötige Know-how für Implementierung und Schulungen. Optimieren Sie jetzt!
Entdeckt die Vorteile von Astro JS Islands für eure Webprojekte. Unsere Experten bieten fundierte Beratung und Schulungen zur effizienten Implementierung dieser leistungsstarken Architektur.
Astro dist Ordner Struktur 2026: Static vs. Server Output, _astro Assets, Content Hashing und Deployment-Konfiguration. Der Build Output Guide für Entwickler.
Erfahrt, wie ihr mit der richtigen Anpassung von Zeilenabständen (line-height) und Textabständen eure Webseite barrierefrei macht. Praxisnahe Tipps und WCAG-Konformität für Einsteiger und Profis.
Entdeckt ScrewFast, das vielseitige kostenlose Astro JS Theme für Landingpages. Unsere Agentur bietet Expertise bei der Implementierung und maßgeschneiderte Schulungen.
Vitest 3.0: Schneller JavaScript-Test-Runner mit Vite-Integration. Neue Features, Vorteile und Anwendungen für effizientes Testing in modernen Webprojekten.
