TypeScript

Astro wird mit integrierter Unterstützung für TypeScript ausgeliefert. Du kannst .ts- und .tsx-Dateien in dein Astro-Projekt importieren, TypeScript-Code direkt in deiner Astro-Komponente schreiben und sogar eine astro.config.ts-Datei verwenden, wenn du möchtest.

Mit TypeScript kannst du Fehler zur Laufzeit verhindern, indem du die Struktur von Objekten und Komponenten in deinem Code definierst. Wenn du zum Beispiel TypeScript verwendest, um die Eigenschaften deiner Komponente einzugeben, bekommst du in deinem Editor eine Fehlermeldung, wenn du eine Eigenschaft setzt, die deine Komponente nicht akzeptiert.

Du musst keinen TypeScript-Code in deinen Astro-Projekten verwenden, um davon zu profitieren. Astro behandelt deinen Komponentencode immer als TypeScript, und die Astro VSCode Extension leitet so viel wie möglich ab, um Autovervollständigung, Hinweise und Fehler in deinem Editor bereitzustellen.

Der Astro-Dev-Server führt keine Typüberprüfung durch, aber du kannst ein separates Skript verwenden, um auf der Kommandozeile auf Typfehler zu prüfen.

Einrichtung

Abschnitt betitelt Einrichtung

Astro-Starterprojekte enthalten eine tsconfig.json-Datei in deinem Projekt. Auch wenn du keinen TypeScript-Code schreibst, ist diese Datei wichtig, damit Tools wie Astro und VS Code dein Projekt verstehen können. Einige Funktionen (wie npm-Paketimporte) werden ohne die Datei tsconfig.json im Editor nicht vollständig unterstützt. Wenn du Astro manuell installierst, solltest du diese Datei selbst erstellen.

Astro enthält drei erweiterbare tsconfig.json-Vorlagen: base, strict und strictest. Die base-Vorlage ermöglicht die Unterstützung moderner JavaScript-Funktionen und wird auch als Grundlage für die anderen Vorlagen verwendet. Wir empfehlen, strict oder strictest zu verwenden, wenn du vorhast, in deinem Projekt TypeScript zu schreiben. Du kannst die drei Vorlagenkonfigurationen unter astro/tsconfigs/ ansehen und vergleichen.

Um von einer der Vorlagen zu erben, verwende [die Einstellung extends] (https://www.typescriptlang.org/tsconfig#extends):

tsconfig.json

{
  "extends": "astro/tsconfigs/base"
}

Außerdem enthalten unsere Vorlagen eine Datei env.d.ts im Ordner src, um die Client-Typen von Vite für dein Projekt bereitzustellen:

env.d.ts

/// <reference types="astro/client" />

Wenn du nicht VSCode verwendest, kannst du das Astro TypeScript Plugin installieren, um den Import von .astro-Dateien aus .ts-Dateien zu unterstützen (was für den Re-Export nützlich sein kann).

npm

npm install @astrojs/ts-plugin

pnpm

pnpm add @astrojs/ts-plugin

Yarn

yarn add @astrojs/ts-plugin

Füge dann Folgendes zu deiner tsconfig.json hinzu:

tsconfig.json

  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }

Um zu überprüfen, ob das Plugin funktioniert, erstelle eine .ts-Datei und importiere eine Astro-Komponente darin. Du solltest in deinem Editor keine Warnmeldungen erhalten.

UI-Frameworks

Abschnitt betitelt UI-Frameworks

Wenn dein Projekt ein UI-Framework verwendet, können je nach Framework zusätzliche Einstellungen erforderlich sein. Weitere Informationen findest du in der TypeScript-Dokumentation deines Frameworks. (Vue, React, Preact, Solid)

Typ-Importe

Abschnitt betitelt Typ-Importe

Verwende, wann immer möglich, explizite Typ-Importe und -Exporte.

import { SomeType } from './script';
import type { SomeType } from './script';

Auf diese Weise vermeidest du Fälle, in denen der Astro-Bundler versucht, deine importierten Typen fälschlicherweise so zu bündeln, als ob sie JavaScript wären.

Du kannst TypeScript so konfigurieren, dass Typ-Importe in deiner .tsconfig-Datei erzwungen werden.

TypeScript ≤4.9

Setze importsNotUsedAsValues auf "error". TypeScript prüft dann deine Importe und sagt dir, wann import type verwendet werden sollte. Diese Einstellung ist standardmäßig in unseren Vorlagen strict und strictest enthalten.

tsconfig.json

{
  "compilerOptions": {
    "importsNotUsedAsValues": "error"
  }
}

TypeScript ≥5.0

Setze verbatimModuleSyntax auf true. TypeScript prüft deine Importe und sagt dir, wann import type verwendet werden sollte.

tsconfig.json

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

Import-Aliase

Abschnitt betitelt Import-Aliase

Astro unterstützt Import-Aliase, die du in deiner tsconfig.json & jsconfig.json paths Konfiguration definierst.

src/pages/about/nate.astro

---
import HelloWorld from '@components/HelloWorld.astro';
import Layout from '@layouts/Layout.astro';
---

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

Erweiterung von window und globalThis

Abschnitt betitelt Erweiterung von window und globalThis

Du möchtest dem globalen Objekt vielleicht eine Eigenschaft hinzufügen. Das kannst du tun, indem du eine globale Deklaration in deine Datei “env.d.ts” einfügst:

env.d.ts

declare global {
  var myString: string;
  function myFunction(): boolean;
}

export {};

Dies ermöglicht die Eingabe von globalThis.myString und globalThis.myFunction, sowie window.myString und window.myFunction.

Beachte, dass window nur im clientseitigen Code verfügbar ist. globalThis ist sowohl serverseitig als auch clientseitig verfügbar, aber sein serverseitiger Wert wird nicht an den Client weitergegeben.

Wenn du nur eine Eigenschaft des window-Objekts angeben willst, stelle stattdessen eine Window-Schnittstelle bereit:

env.d.ts

interface Window {
  myFunction(): boolean;
}

Komponenten-Eigenschaften

Abschnitt betitelt Komponenten-Eigenschaften

Astro unterstützt die Eingabe von Komponenteneigenschaften über TypeScript. Um dies zu aktivieren, füge eine TypeScript Props-Schnittstelle zu deinem Komponenten-Frontmatter hinzu. Eine Export-Anweisung kann verwendet werden, ist aber nicht notwendig. Die Astro VSCode Extension sucht automatisch nach der Props-Schnittstelle und bietet dir die richtige TypeScript-Unterstützung, wenn du die Komponente in einer anderen Vorlage verwendest.

src/components/HelloProps.astro

---
interface Props {
  name: string;
  greeting?: string;
}
const { greeting = 'Hallo', name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Gemeinsame Prop-Type-Pattern

Abschnitt betitelt Gemeinsame Prop-Type-Pattern

• Wenn deine Komponente keine Eigenschaften oder Slot-Inhalte annimmt, kannst du type Props = Record<string, never> verwenden.

• Wenn deine Komponente Kind-Elemente an ihren Standard-Slot übergeben werden muss, kannst du dies mit type Props = { children: any; }; erzwingen.

Typ-Helfer

Abschnitt betitelt Typ-Helfer

Hinzugefügt in: astro@1.6.0

Astro verfügt über einige eingebaute Hilfstypen für gängige Prop-Type-Pattern. Diese sind unter dem Einstiegspunkt astro/types verfügbar.

Eingebaute HTML-Attribute

Abschnitt betitelt Eingebaute HTML-Attribute

Astro bietet den Typ HTMLAttributes, um zu prüfen, ob dein Markup gültige HTML-Attribute verwendet. Du kannst diese Typen verwenden, um Komponenteneigenschaften zu erstellen.

Wenn du zum Beispiel eine Link-Komponente baust, kannst du die Standard-HTML-Attribute für a-Tags in den Prop-Typen deiner Komponente wie folgt wiedergeben.

src/components/Link.astro

---
import type { HTMLAttributes } from 'astro/types'
// einen `type` verwenden
type Props = HTMLAttributes<'a'>;
// or extend with an `interface`
interface Props extends HTMLAttributes<'a'> {
  myProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

Es ist auch möglich, die Standard-JSX-Definitionen um nicht-standardmäßige Attribute zu erweitern, indem du den astroHTML.JSX-Namensraum in einer .d.ts-Datei neu deklarierst.

src/custom-attributes.d.ts

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    'data-count'?: number;
    'data-label'?: string;
  }
}

Hinweis

astroHTML wird global innerhalb von astro-Komponenten injiziert. Um es in TypeScript-Dateien zu verwenden, benutze eine triple-slash directive:

/// <reference types="astro/astro-jsx" />

type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;

Ableiten von getStaticPaths()-Typen

Abschnitt betitelt Ableiten von getStaticPaths()-Typen

Hinzugefügt in: astro@2.1.0

Astro enthält Hilfsprogramme für die Arbeit mit Typen, die von deiner Funktion getStaticPaths() für dynamische Routen zurückgegeben werden.

Du kannst den Typ von Astro.params mit InferGetStaticParamsType und den Typ von Astro.props mit InferGetStaticPropsType ermitteln:

src/pages/posts/[...slug].astro

---
import { InferGetStaticParamsType, InferGetStaticPropsType, GetStaticPaths } from 'astro';

export const getStaticPaths = (async () => {
  const posts = await getCollection('blog');
  return posts.map((post) => {
    return {
      params: { slug: post.slug },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { slug } = Astro.params as Params;
//                      ^? { slug: string; }
const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---

Typenprüfung

Abschnitt betitelt Typenprüfung

Um Typfehler in deinem Editor zu sehen, stelle bitte sicher, dass du die Astro-VS-Code-Erweiterung installiert hast. Bitte beachte, dass die Befehle astro start und astro build den Code mit esbuild übersetzen, aber keine Typprüfung durchführen. Um zu verhindern, dass dein Code gebaut wird, wenn er TypeScript-Fehler enthält, ändere dein “build”-Skript in der Datei package.json wie folgt:

package.json

  "scripts": {
    "build": "astro build",
    "build": "astro check && tsc --noEmit && astro build",
  },

Hinweis

astro check prüft nur Typen innerhalb von astro-Dateien und tsc --noEmit prüft nur Typen innerhalb von ts-Dateien und tsx-Dateien. Um Typen innerhalb von Svelte- und Vue-Dateien zu prüfen, kannst du die Pakete svelte-check bzw. vue-tsc verwenden.

📚 Lies mehr über .ts-Dateiimporte in Astro. 📚 Lies mehr über TypeScript-Konfiguration.

Fehlersuche

Abschnitt betitelt Fehlersuche

Fehler bei der gleichzeitigen Typisierung mehrerer JSX-Frameworks

Abschnitt betitelt Fehler bei der gleichzeitigen Typisierung mehrerer JSX-Frameworks

Wenn du mehrere JSX-Frameworks im selben Projekt verwendest, kann es zu Problemen kommen, da jedes Framework unterschiedliche, manchmal widersprüchliche Einstellungen in der Datei tsconfig.json benötigt.

Lösung: Setze die Einstellung jsxImportSource auf react (Standard), preact oder solid-js, je nachdem, welches Framework du am häufigsten verwendest. Verwende dann einen pragma-Kommentar in jeder kollidierenden Datei eines anderen Frameworks.

Für die Standardeinstellung von jsxImportSource: react würdest du folgendes verwenden:

// For Preact
/** @jsxImportSource preact */

// For Solid
/** @jsxImportSource solid-js */