Pierwszy projekt w Astro — od npm create astro do wdrożenia w 15 minut

Ten artykuł to punkt startowy serii o Astro — jeśli reszta serii zakłada, że masz już projekt, to tutaj go zakładamy od pustego folderu. Bez wcześniejszej wiedzy o Astro, za to z wyjaśnieniem, dlaczego robimy rzeczy tak, a nie inaczej. Zapraszam do lektury.

Czym jest Astro i jaki problem rozwiązuje

Astro to framework webowy zbudowany wokół jednej obserwacji: większość stron internetowych wysyła do przeglądarki znacznie więcej JavaScriptu, niż potrzebuje. Blog czy strona firmowa to w 90% treść — tekst, obrazy, linki. A mimo to klasyczne aplikacje React czy Vue ładują cały framework, żeby wyświetlić akapit, który mógłby być zwykłym HTML-em.

Astro nazywa ten nadmiar bloatem JavaScriptu i rozwiązuje go u źródła: domyślnie generuje czysty HTML i nie wysyła do przeglądarki ani jednej linijki frameworkowego JS. Interaktywność — formularz, slider, kalkulator — dodajesz świadomie, tylko tam, gdzie jest potrzebna. To podejście nazywa się architekturą wyspArchitektura wysp (Islands Architecture) to wzorzec, w którym większość strony jest statycznym HTML-em, a interaktywne fragmenty hydratują się jako niezależne wyspy. i rozkładam je szczegółowo w osobnym artykule.

Dla kogo Astro: blogi, dokumentacja, strony firmowe, landing page, portfolio, lekki e-commerce. Wszędzie tam, gdzie treść jest najważniejsza, a interaktywność punktowa. Dla aplikacji z dużą ilością stanu (dashboardy, panele) lepszy bywa Next.js — porównuję oba w osobnym artykule.

Zanim zaczniesz: Node 22.12+

Astro 6 wymaga Node.js w wersji 22.12.0 lub wyższej. Wersje nieparzyste (jak v23) nie są wspierane, sprawdzisz swoją za pomocą:

node --version

Jeśli masz starszą wersję, po prostu zaktualizuj Node (np. przez nvm) zanim ruszysz dalej — to najczęstsza przyczyna błędów na samym starcie.

Krok 1: Utworzenie projektu

Jedna komenda stawia cały projekt z interaktywnym kreatorem:

npm create astro@latest

Kreator zapyta o nazwę projektu, szablon startowy (wybierz pusty albo blog), TypeScript i instalację zależności - po chwili masz działający projekt.

Wchodzisz do katalogu i uruchamiasz serwer deweloperski:

cd moj-projekt
npm run dev

Serwer startuje pod localhost:4321 i odświeża stronę na bieżąco przy każdej zmianie pliku. Pierwsza strona już działa.

Krok 2: Struktura projektu

Astro ma przewidywalną i minimalną strukturę katalogów, której najważniejsze elementy wyglądają 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/             ← statyczne zasoby (obrazy, robots.txt)
├── astro.config.mjs    ← konfiguracja Astro
├── tsconfig.json       ← konfiguracja TypeScript
└── package.json

Dwa katalogi zapamiętaj od razu:

• src/pages/ — serce routingu, gdzie każdy plik staje się stroną (o tym za chwilę).
• public/ — pliki kopiowane do builda dosłownie i bez przetwarzania. Tu trafia robots.txt, favicon i statyczne obrazy.

Krok 3: Routing oparty na plikach

Astro nie ma osobnej konfiguracji tras. Struktura plików w src/pages/ jest mapą URL-i — to routing oparty na plikachRouting oparty na plikach to model, w którym ścieżka pliku w projekcie automatycznie wyznacza adres URL strony, bez ręcznej konfiguracji tras.:

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 (np. wpis bloga, którego nazwa nie jest znana z góry) używasz nawiasów kwadratowych w nazwie pliku:

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

Wewnątrz takiej strony Astro wymaga funkcji getStaticPaths, która mówi, jakie konkretne adresy wygenerować podczas builda:

---
// 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>

To wszystko dostajesz bez konfiguracji routera i bez rejestrowania tras.

Krok 4: Pierwszy komponent .astro

Komponent Astro to plik .astro z dwiema częściami: frontmatter (sekcja skryptu między ---, wykonywana na serwerze/podczas builda) i szablon (HTML poniżej):

---
// src/components/Karta.astro — frontmatter: kod serwerowy
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>

Trzy rzeczy warte uwagi:

• Astro.props — komponent przyjmuje dane jak funkcja przyjmuje argumenty.
• {tytul} — interpolacja wyrażeń JavaScript w HTML, składnia bliska JSX.
• <style> — style są domyślnie ograniczone do komponentu (scoped), więc nie wyciekają na resztę strony.

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 nie wysyła do przeglądarki ani bajta JavaScriptu — renderuje się do czystego HTML podczas builda i tak właśnie wygląda „zero JS domyślnie" w praktyce.

Krok 5: Build i wdrożenie

Statyczną stronę budujesz jedną komendą:

npm run build

Astro generuje folder dist/ z gotowymi plikami HTML, CSS i zoptymalizowanymi zasobami. Dla statycznej strony nie potrzebujesz adaptera — to zwykłe pliki, które wdrożysz na dowolnym hostingu:

• Vercel / Netlify / Cloudflare Pages — podłączasz repozytorium z GitHuba, a one budują i wdrażają automatycznie przy każdym pushu, darmowy plan w zupełności wystarczy dla małej strony.
• Dowolny CDN albo serwer plików — wrzucasz zawartość dist/.

Adapter (Vercel, Netlify, Cloudflare, Node) dokładasz dopiero, gdy potrzebujesz renderowania na serwerze albo funkcji dynamicznych — to temat późniejszych artykułów serii, m.in. o Cloudflare Workers.

Co dalej

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.