Pierwszy projekt w Astro 7 od instalacji do wdrożenia

Ten artykuł jest punktem startowym serii o Astro. Zaczynamy od pustego katalogu i dochodzimy do publicznego adresu testowego. Astro 7 ukazało się 22 czerwca 2026 roku, dlatego przykłady odnoszą się do bieżącej głównej wersji frameworka.

Czym jest Astro i jaki problem rozwiązuje w pierwszym projekcie

Astro to framework webowy zbudowany wokół jednej obserwacji: strony często wysyłają zbyt dużo JavaScriptu. Blog czy strona firmowa składa się głównie z tekstu, obrazów i linków. Taka treść może być dostarczona jako HTML bez uruchamiania całego frameworka interfejsu w przeglądarce.

Komponenty .astro renderują się do HTML podczas budowania albo na serwerze i same nie wymagają hydratacji w przeglądarce. JavaScript dodajesz świadomie do wybranych elementów, na przykład przez zwykły <script> albo komponent React, Vue czy Svelte z dyrektywą client:*. To podejście nazywa się architekturą wysp i opisuję je szczegółowo w osobnym artykule.

Astro pasuje do stron treściowych: blogów, dokumentacji, stron firmowych, landing page i portfolio. Może również obsługiwać aplikacje dynamiczne, ale przy panelach z dużą ilością stanu trzeba porównać architekturę, kompetencje zespołu i ekosystem integracji. Astro i Next.js zestawiam w osobnym artykule.

Wymagania przed pierwszym projektem Astro: Node 22.12+

Bieżąca dokumentacja Astro 7 wymaga Node.js 22.12.0 lub nowszego. Nieparzyste wersje, takie jak 23, nie są wspierane. Sprawdź wersję Node przed instalacją:

node --version

Jeśli masz starszą wersję, zaktualizuj Node przed utworzeniem projektu. Menedżer wersji, taki jak nvm, ułatwia przełączanie środowiska między projektami. Zapisz też wersję w pliku .nvmrc, aby zespół i środowisko CI korzystały z tej samej gałęzi:

22.12.0

Krok 1: utworzenie pierwszego projektu Astro

Jedna komenda stawia cały projekt z interaktywnym kreatorem:

npm create astro@latest

Kreator poprosi między innymi o katalog projektu i szablon startowy. Opcje mogą zmieniać się między wersjami CLI, dlatego czytaj podsumowanie wyświetlane w terminalu. Do przejścia tego poradnika wystarczy pusty szablon. Jeśli pominiesz instalację zależności, uruchom ją ręcznie:

cd moj-projekt
npm install

Jeśli kreator zainstalował już zależności, przejdź bezpośrednio do katalogu i uruchom serwer deweloperski:

cd moj-projekt
npm run dev

Serwer zwykle startuje pod adresem http://localhost:4321 i odświeża stronę po zmianie pliku. Otwórz dokładny adres wypisany w terminalu, ponieważ przy zajętym porcie może być inny.

Krok 2: struktura projektu Astro po instalacji

Po dodaniu komponentu i layoutu z kolejnych kroków struktura projektu będzie wyglądała w przybliżeniu tak:

moj-projekt/
├── src/
│   ├── pages/          ← każdy plik = strona (routing)
│   │   └── index.astro ← strona główna (/)
│   ├── components/     ← komponenty wielokrotnego użytku
│   └── layouts/        ← szablony wspólne dla stron
├── public/             ← zasoby kopiowane bez przetwarzania
├── astro.config.mjs    ← konfiguracja Astro
├── tsconfig.json       ← konfiguracja TypeScript
└── package.json

Dwa katalogi zapamiętaj od razu:

• Katalog src/pages definiuje adresy strony. Pliki .astro, .md, .mdx oraz obsługiwane endpointy tworzą trasy aplikacji.
• Katalog public omija przetwarzanie builda. Umieszczaj w nim między innymi robots.txt, favicon i zasoby, które muszą zachować dokładną nazwę. Obrazy wymagające optymalizacji importuj z src/ i wyświetlaj przez komponent <Image />.

Pusty szablon może nie zawierać od razu katalogów components/ i layouts/. Utwórz je podczas dodawania pierwszych plików. Astro nie wymaga tych dwóch nazw, ale są powszechną konwencją porządkującą projekt.

Krok 3: routing oparty na plikach w Astro

Astro nie wymaga osobnego rejestru tras. Struktura plików wyznacza adresy strony w mechanizmie routingu opartego na plikach:

src/pages/index.astro        → /
src/pages/o-mnie.astro       → /o-mnie
src/pages/blog/index.astro   → /blog
src/pages/blog/pierwszy.astro → /blog/pierwszy

Dla tras dynamicznych, na przykład wpisów bloga, używasz nawiasów kwadratowych w nazwie pliku:

src/pages/blog/[slug].astro  → /blog/cokolwiek

W domyślnym trybie statycznym taka strona wymaga funkcji getStaticPaths(), która określa adresy generowane podczas budowania:

---
// src/pages/blog/[slug].astro
export function getStaticPaths() {
  return [
    { params: { slug: 'pierwszy-wpis' } },
    { params: { slug: 'drugi-wpis' } },
  ]
}
 
const { slug } = Astro.params
---
 
<h1>Wpis: {slug}</h1>

Przy renderowaniu dynamicznej trasy na żądanie z adapterem getStaticPaths() nie jest używane. Plik z parametrem pasuje wtedy do adresów przychodzących, a strona powstaje podczas żądania. Tryb renderowania zmienia zachowanie tras, dlatego nie kopiuj przykładu SSG bez sprawdzenia konfiguracji projektu.

Krok 4: pierwszy komponent .astro w projekcie

Komponent Astro składa się ze skryptu komponentu pomiędzy separatorami --- oraz szablonu HTML. Skrypt działa podczas budowania albo renderowania na serwerze i nie trafia automatycznie do przeglądarki:

---
// src/components/Karta.astro, skrypt komponentu
interface Props {
  tytul: string
  opis: string
}
 
const { tytul, opis } = Astro.props
---
 
<!-- Szablon: HTML z interpolacją -->
<article class="karta">
  <h2>{tytul}</h2>
  <p>{opis}</p>
</article>
 
<style>
  .karta {
    padding: 1.5rem;
    border-radius: 0.5rem;
    border: 1px solid #e5e7eb;
  }
</style>

W tym przykładzie:

1. Astro.props udostępnia dane przekazane do komponentu.
2. Interfejs Props kontroluje wymagane nazwy i typy właściwości.
3. Wyrażenie {tytul} wstawia wartość JavaScript do szablonu.
4. Style są ograniczone do komponentu przez domyślny mechanizm scoping.

Używasz go w stronie, importując i osadzając:

---
// src/pages/index.astro
import Karta from '../components/Karta.astro'
---
 
<Karta tytul="Witaj" opis="To mój pierwszy komponent w Astro." />

Ten komponent renderuje sam HTML. Jeśli dodasz zwykły <script> albo interaktywną wyspę z dyrektywą client:*, odpowiedni kod kliencki pojawi się w wyniku. Hasło „zero JS domyślnie” opisuje zachowanie komponentu Astro, a nie zakaz używania JavaScriptu w całej witrynie.

Krok 5: minimalny layout strony Astro

Pierwszy widok powinien mieć język dokumentu, kodowanie, viewport, tytuł i opis. Zamiast powtarzać te elementy na każdej stronie, utwórz layout:

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string
  description: string
}
 
const { title, description } = Astro.props
---
 
<!doctype html>
<html lang="pl">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <meta name="description" content={description} />
    <title>{title}</title>
  </head>
  <body>
    <main>
      <slot />
    </main>
  </body>
</html>

Następnie użyj layoutu i przygotowanej karty na stronie głównej:

---
// src/pages/index.astro
import Karta from '../components/Karta.astro'
import BaseLayout from '../layouts/BaseLayout.astro'
---
 
<BaseLayout
  title="Pierwsza strona w Astro"
  description="Prosty projekt przygotowany w Astro 7."
>
  <h1>Pierwsza strona w Astro</h1>
  <Karta tytul="Witaj" opis="To mój pierwszy komponent w Astro." />
</BaseLayout>

To minimalna baza, a nie pełna konfiguracja SEO. Przed publikacją dodaj adres kanoniczny, metadane udostępniania, favicon, robots.txt i mapę witryny zgodnie z wymaganiami projektu.

Krok 6: build i podgląd produkcyjny

Statyczną stronę budujesz jedną komendą:

npm run build

Astro generuje katalog dist/ z wynikiem produkcyjnym. Po udanym buildzie uruchom lokalny podgląd:

npm run preview

Sprawdź stronę pod adresem podanym w terminalu, przejdź po wszystkich trasach i zajrzyj do konsoli przeglądarki. Udany build nie gwarantuje poprawnej strony: możliwe są nadal uszkodzone linki, błędy zasobów, nieprawidłowe metadane lub problemy widoczne dopiero przy bezpośrednim otwarciu podstrony.

Krok 7: wdrożenie statycznej strony Astro

Dla domyślnego statycznego wyniku adapter nie jest wymagany. Hosting musi uruchamiać komendę npm run build i publikować katalog dist/. Najprostsza ścieżka przez panel dostawcy wygląda następująco:

1. Utwórz repozytorium Git i zapisz pierwszy commit.
2. Wyślij repozytorium do obsługiwanej usługi Git, na przykład GitHub lub GitLab.
3. Zaimportuj repozytorium w panelu wybranego hostingu.
4. Potwierdź komendę budowania npm run build i katalog publikacji dist.
5. Uruchom wdrożenie i otwórz przydzielony adres testowy.

Podstawowe komendy Git przed wysłaniem repozytorium:

git init
git add .
git commit -m "Utwórz pierwszy projekt Astro"

Sposób dodania zdalnego repozytorium zależy od usługi i wybranej metody uwierzytelniania. Nie wklejaj tokenu dostępowego do kodu ani historii poleceń.

Adapter dla Vercel, Netlify, Cloudflare lub Node dodaj wtedy, gdy korzystasz z renderowania na żądanie albo funkcji zależnych od danej platformy. W takim projekcie wykonaj instrukcję konkretnego adaptera, ponieważ sam katalog dist/ może zawierać również kod serwerowy, a nie wyłącznie pliki statyczne.

Szczegóły integracji Cloudflare, w tym różnicę między statycznymi zasobami a renderowaniem na żądanie, opisuję w artykule o Astro i Cloudflare Workers.

Co sprawdzić po pierwszym wdrożeniu

Publiczny adres nie oznacza jeszcze, że projekt jest gotowy do promocji. Przed podpięciem domeny wykonaj krótki test odbiorczy:

• Otwórz stronę główną i każdą podstronę bezpośrednio w nowej karcie, aby wykryć problemy routingu i błędne reguły przekierowań.

• Sprawdź widok mobilny, obsługę klawiaturą, kontrast i teksty alternatywne obrazów.

• Zweryfikuj tytuł, opis, adres kanoniczny, favicon, robots.txt i mapę witryny.

• Przejrzyj konsolę przeglądarki, log wdrożenia, odpowiedź strony 404 oraz żądania zakończone błędami.

• Potwierdź, że sekrety i pliki lokalne nie trafiły do repozytorium, a zmienne publiczne nie zawierają danych wrażliwych.

Co dalej po pierwszym projekcie Astro

Masz działający projekt, a teraz reszta serii układa się w naturalną ścieżkę:

• Zrozum fundament. Architektura wysp wyjaśnia, dlaczego Astro jest szybkie.

• Dodaj treść z walidacją. Content Collections zamieniają pliki Markdown w typowany system.

• Dodaj interaktywność świadomie. Dyrektywy client decydują, co i kiedy dostaje JavaScript.

• Zadbaj o widoczność. SEO w Astro pokazuje, jak wykorzystać przewagę wydajnościową w Google.