Zum Inhalt springen

Migrieren von Create React App (CRA)

Astros React-Integration (EN) ermöglicht dir, React-Komponenten in Astro-Komponenten zu verwenden, auch komplette React-Projekte wie Create React App (CRA)!

src/pages/index.astro
---
// Importiere die App-Komponente deines Stammverzeichnisses
import App from '../cra-project/App.jsx';
---
<!-- Verwende eine Client-Direktive, um deine App zu laden -->
<App client:load />
Lies in Build a Single Page Application (SPA) with Astro (englischer Blogpost) External, wie man React Router in Astro verwendet.

Viele Apps werden als komplette React-Apps “einfach funktionieren”, wenn du sie direkt in dein Astro-Projekt mit der React-Integration installierst. Das ist eine gute Möglichkeit, dein Projekt sofort zum Laufen zu bringen und deine App funktionsfähig zu halten, während du zu Astro migrierst.

Mit der Zeit kannst du deine Struktur stückweise in eine Kombination aus .astro- und .jsx- Komponenten umbauen. Dabei wirst du merken, dass du weniger React-Komponenten brauchst als du vielleicht denkst!

Hier sind ein paar grundlegende Konzepte und Migrations­strategien, die dir den Einstieg erleichtern. Nutze den Rest unserer Dokumente und unsere Discord-Community, um weiterzumachen!

Wesentliche Gemeinsamkeiten zwischen CRA und Astro

Abschnitt betitelt Wesentliche Gemeinsamkeiten zwischen CRA und Astro

Wesentliche Unterschiede zwischen CRA und Astro

Abschnitt betitelt Wesentliche Unterschiede zwischen CRA und Astro

Wenn du deine CRA-Webseite in Astro nachbilden willst, werden dir einige wichtige Unterschiede auffallen:

  • CRA ist eine Single Page Application (App mit einer einzigen Seite), welche eine index.js-Datei als das Stammverzeichnis deines Projekts verwendet. Astro ist eine Multiple Page Application (App mit mehreren Seiten), und index.astro ist deine Startseite.

  • .astro-Komponenten sind nicht als exportierte Funktionen geschrieben, die Seitenvorlagen zurückgeben. Stattdessen wirst du deinen Code in einen “Code-Zaun” mit deinem JavaScript-Code und einem Body, der ausschließlich deinen generierten HTML-Code enthält, aufteilen.

  • Inhaltsorientiert: Astro wurde als Auslage für deine Inhalte entwickelt und erlaubt dir, interaktive Elemente nur einzubauen, wenn du sie brauchst. Eine existierende CRA-App könnte für ausgiebige client-seitige Interaktivität ausgelegt sein und benötigt vielleicht fortgeschrittene Astro-Techniken, um komplexere Elemente wie Dashboards durch .astro-Komponenten zu ersetzen.

Füge deine CRA zu Astro hinzu

Abschnitt betitelt Füge deine CRA zu Astro hinzu

Deine vorhandene App kann direkt in einem neuen Astro-Projekt gerendert werde, oftmals auch ohne Änderungen an deinem Code.

Erstelle ein neues Astro-Projekt

Abschnitt betitelt Erstelle ein neues Astro-Projekt

Verwende den create astro-Befehl, um Astros CLI Wizard zu starten, und wähle ein neues “leeres” Astro-Projekt.

Terminal-Fenster
npm create astro@latest

Füge Integrationen und Abhängigkeiten hinzu

Abschnitt betitelt Füge Integrationen und Abhängigkeiten hinzu

Füge die React-Integration mit dem astro add-Befehl hinzu. Wenn deine App Tailwind oder MDX verwendet, kannst du mehrere Astro-Integrationen mit einem Befehl hinzufügen:

Terminal-Fenster
npx astro add react
npx astro add react tailwind mdx

Wenn deine CRA-App andere Abhängigkeiten (z.B. NPM-Pakete) benötigt, kannst du diese entweder individuell über die Kommandozeile installieren oder durch das Hinzufügen in die package.json-Datei deines Astro-Projekts, wenn du danach den Installationsbefehl laufen lässt. Beachte, dass viele, aber nicht alle, React-Abhängigkeiten auch in Astro funktionieren werden.

Füge deine vorhanden App-Dateien hinzu

Abschnitt betitelt Füge deine vorhanden App-Dateien hinzu

Kopiere deine vorhanden CRA-Projektdateien und Ordner (z.B. components, hooks, styles etc.) in einen neuen Ordner in src/, während du die Struktur aufrecht erhältst, damit deine App weiterhin funktioniert. Beachte, dass alle .js-Dateiendungen in .jsx oder .tsx umbenannt werden müssen.

Füge keine Konfigurations­dateien hinzu. Du wirst Astros eigene astro.config.mjs, package.json und tsconfig.json bearbeiten können.

Verschiebe den Inhalt des Ordners public/ deiner App (z. B. statische Assets) in den Ordner public/ von Astro.

  • Directorypublic/
    • logo.png
    • favicon.ico
    • …
  • Directorysrc/
    • Directorycra-project/
      • App.jsx
      • …
    • Directorypages/
      • index.astro
  • astro.config.mjs
  • package.json
  • tsconfig.json

Rendere deine App

Abschnitt betitelt Rendere deine App

Importiere deine Stammverzeichnis-Komponenten in das Frontmatter von index.astro und rendere die <App />-Komponente in deiner Seitenvorlage:

src/pages/index.astro
---
import App from '../cra-project/App.jsx';
---
<App client:load />

Verwandle deine CRA in Astro

Abschnitt betitelt Verwandle deine CRA in Astro

Nachdem du deine vorhandene App in Astro hinzugefügt hast, willst du wahrscheinlich die App auch in Astro umwandeln!

Du replizierst ein ähnliches komponenten­basiertes Design unter Verwendung von Astro HTML-Vorlagenkomponenten für deine Grundstruktur, während du einzelne React-Komponenten (die selbst ganze Apps sein können!) für Inseln der Interaktivität importierst und einbindest.

Jede Migration sieht anders aus und kann schrittweise durchgeführt werden, ohne dass die Funktionalität deiner App unterbrochen wird. Konvertiere deine Komponenten in deinem eigenen Tempo, sodass deine App mit der Zeit immer mehr von Astro-Komponenten angetrieben wird.

Während du deine React-App konvertierst, entscheidest du, welche React-Komponenten du als Astro-Komponenten umschreibst und welche nicht. Deine einzige Einschränkung besteht darin, dass Astro-Komponenten zwar React-Komponenten importieren können, React-Komponenten jedoch nur andere React-Komponenten importieren dürfen:

src/pages/static-components.astro
---
import MyReactComponent from '../components/MyReactComponent.jsx';
---
<html>
  <body>
    <h1>Verwende React-Komponenten direkt in Astro!</h1>
    <MyReactComponent />
  </body>
</html>

Anstatt Astro-Komponenten in React-Komponenten zu importieren, kannst du mehrere React-Komponenten in einer einzelnen Astro-Komponente verschachteln:

src/pages/nested-components.astro
---
import MyReactSidebar from '../components/MyReactSidebar.jsx';
import MyReactButton from '../components/MyReactButton.jsx';
---
<MyReactSidebar>
  <p>Hier ist eine Seitenleiste mit etwas Text und einem Button.</p>
  <div slot="actions">
    <MyReactButton client:idle />
  </div>
</MyReactSidebar>

Vielleicht hilft es dir, zuerst über Astro-Inseln und Astro-Komponenten zu lernen, bevor du dein CRA in ein Astro-Projekt umwandelst.

Vergleiche: JSX vs Astro

Abschnitt betitelt Vergleiche: JSX vs Astro

Vergleiche folgende React-Komponente und die entsprechende Astro-Komponente:

StarCount.jsx
import React, { useState, useEffect } from 'react';
import Header from './Header';
import Footer from './Footer';


const Component = () => {
const [stars, setStars] = useState(0);
const [message, setMessage] = useState('');


useEffect(() => {
    const fetchData = async () => {
        const res = await fetch('https://api.github.com/repos/withastro/astro');
        const json = await res.json();


        setStars(json.stargazers_count || 0);
        setMessage(json.message);
    };


    fetchData();
}, []);


return (
    <>
        <Header />
        <p style={{
            backgroundColor: `#f4f4f4`,
            padding: `1em 1.5em`,
            textAlign: `center`,
            marginBottom: `1em`
        }}>Astro hat {stars} 🧑‍🚀</p>
        <Footer />
    </>
)
};


export default Component;

JSX-Dateien in .astro-Dateien umwandeln

Abschnitt betitelt JSX-Dateien in .astro-Dateien umwandeln

Hier sind ein paar Tipps für das Umwandeln von CRA-.js-Komponenten in .astro-Komponenten:

  1. Verwende das zurückgegebene JSX deiner vorhandenen CRA-Komponentenfunktion als Basis für deine HTML-Vorlage.

  2. Tausche jeden CRA oder JSX Syntax gegen Astro oder gegen HTML-Web-Standards. Damit ist zum Beispiel {children} oder className gemeint.

  3. Verschiebe sämtliches JavaScript, inklusive import-Statements, in einen “Code-Zaun” (---). Beachte: JavaScript, welches für das bedingte Rendern von Inhalten benötigt wird, wird oftmals in der HTML-Vorlage direkt in Astro geschrieben.

  4. Verwende Astro.props, um auf die Komponenten­attribute, die zuvor deiner CRA-Komponenten­funktionen weitergegeben worden sind, zuzugreifen.

  5. Entscheide, ob deine importierten Komponenten auch in Astro umgewandelt werden müssen. Du kannst sie als React-Komponenten behalten, egal ob kurzfristig oder für immer. Aber vielleicht willst du sie ja doch in .astro-Komponenten umwandeln, vor allem, wenn sie nicht interaktiv sind.

  6. Ersetze useEffect() mit import-Statements oder Astro.glob() für das Laden von lokalen Dateien. Verwende fetch() für das laden von externen Daten.

Tests migrieren

Abschnitt betitelt Tests migrieren

Da Astro reines HTML ausgibt, kannst du deine End-zu-End Tests für die Ausgabe des Erzeugungsvorgangs schreiben. Bereits bestehende Tests funktionieren vielleicht auch sofort, wenn du die Markupstruktur deiner CRA-Webseite übernehmen konntest. Testbibliotheken wie Jest oder React Testing Library können importiert und für das Testen deiner React-Komponenten in Astro verwendet werden.

Lies Astros Testanleitung für mehr.

Referenz: Wandle CRA Syntax in Astro um

Abschnitt betitelt Referenz: Wandle CRA Syntax in Astro um

CRA Imports in Astro

Abschnitt betitelt CRA Imports in Astro

Aktualisiere alle Dateiimporte, um die relativen Dateipfade exakt zu referenzieren. Das kannst du mit einem Importalias erreichen oder indem du den relativen Pfad komplett ausschreibst.

Beachte, dass .astro und andere Dateitypen nur mit deren Dateiendung importiert werden können.

src/pages/authors/Fred.astro
---
import Card from '../../components/Card.astro';
---
<Card />

CRA Children in Astro

Abschnitt betitelt CRA Children in Astro

Schreibe jede {children}-Instanz in einen Astro <slot />. Astro benötigt keine {children} als Komponentenattribut und kann automatisch verschaltelte Inhalte in einem <slot /> rendern.

src/components/MyComponent.astro
---
---
export default function MyComponent(props) {
    return (
      <div>
        {props.children}
      </div>
    );
}


<div>
  <slot />
</div>

React-Komponenten, die mehrere {children} rendern, können durch benannte Slots in Astro-Komponenten umgewandelt werden.

Lies mehr über spezifische <slot />-Verwendungen in Astro.

CRA Datenabruf in Astro

Abschnitt betitelt CRA Datenabruf in Astro

Daten abzurufen ist in Astro-Komponenten im Vergleich zu React-Komponenten recht ähnlich, wenn auch mit kleinen Unterschieden.

Um Daten von anderen Dateien in deinem Projekt zu importieren, kannst du alle Instanzen von useEffect entweder gegen Astro.glob() oder getCollection()/getEntryBySlug() austauschen.

Um externe Daten abzurufen, verwende fetch().

Diese Datenabrufe werden im Frontmatter der Astro-Komponente gemacht und verwenden ein top-level await.

src/pages/index.astro
---
import { getCollection } from 'astro:content';


// Hole alle `src/content/blog/` Einträge
const allBlogPosts = await getCollection('blog');


// Hole alle `src/content/posts/` Einträge
const allPosts = await Astro.glob('../pages/posts/*.md');


// Rufe externe Daten ab
const response = await fetch('https://randomuser.me/api/');
const data = await response.json();
const randomUser = data.results[0];
---

Lies mehr über das Importieren von lokalen Dateien mit Astro.glob(), die Collections API (EN) oder das Abrufen von externen Daten.

CRA Styling in Astro

Abschnitt betitelt CRA Styling in Astro

Eventuell musst du CSS-in-JS-Bibliotheken (z.B. gestylte Komponenten) gegen andere, in Astro verfügbaren CSS-Optionen austauschen.

Falls nötig, ändere etwaige Inline-Stilobjekte (style={{ fontWeight: "bold" }}) zu inline HTML-Stilattributen(style="font-weight:bold;"). Oder verwenden Astros <style>-Tag für gescopte CSS-Stile.

src/components/Card.astro
<div style={{backgroundColor: `#f4f4f4`, padding: `1em`}}>{nachricht}</div>
<div style="background-color: #f4f4f4; padding: 1em;">{nachricht}</div>

Tailwind wird unterstützt, wenn du die Tailwind-Integration installiert hast. Keine weiteren Änderungen in deinem bestehenden Tailwind-Code notwendig!

Lerne mehr über Styling in Astro.

Fehlerbehebung

Abschnitt betitelt Fehlerbehebung

Deine CRA-App kann in Astro “einfach funktionieren”! Allerdings ist es auch möglich, dass du kleine Anpassungen vornehmen musst, um die Funktionalität und/oder Styles deiner App zu duplizieren.

Wenn du in der Dokumentation nicht die Fragen auf deine Antworten findest, bitte besuche den Astro Discord und stelle deine Frage im Support-Forum!

Weitere Migrations-Anleitungen

Wirke mit

Worum geht es?

Issue auf GitHub erstellen

Schnellster Weg, um unser Team auf ein Problem aufmerksam zu machen.

Community