Instalacja i konfiguracja Astro

Polecenie CLI create astro to najszybszy sposób na rozpoczęcie nowego projektu Astro od zera. Przeprowadzi Cię ono przez każdy etap konfiguracji nowego projektu Astro i pozwoli wybrać pomiędzy różnymi szablonami startowymi.

Możesz również rozpocząć swój projekt używając istniejącego motywu lub szablonu startowego.

Aby zainstalować Astro ręcznie, zapoznaj się z naszym szczegółowym przewodnikiem instalacji ręcznej.

Wymagania wstępne

Node.js - v18.17.1 lub v20.3.0 albo nowsza. ( v19 nie jest wspierana.)
Edytor kodu - Polecamy VS Code z naszą oficjalną wtyczką Astro.
Terminal - Astro jest dostępne poprzez interfejs wiersza poleceń (CLI).

Wspierane przeglądarki

Astro jest budowane przy użyciu bundlera Vite, który domyślnie generuje kod dla przeglądarek obsługujących współczesny JavaScript. Aby uzyskać pełne informacje, możesz sprawdzić listę przeglądarek aktualnie wspieranych przez Vite.

Rozpocznij nowy projekt

Zainstaluj przy użyciu konfiguratora CLI

Uruchom poniższe polecenie w swoim terminalu, żeby zainicjalizować projekt:
- npm
- pnpm
- yarn
Okno terminala
# stwórz nowy projekt przy użyciu npm npm create astro@latest
Okno terminala
# stwórz nowy projekt przy użyciu pnpm pnpm create astro@latest
Okno terminala
# stwórz nowy projekt przy użyciu yarn yarn create astro
Możesz uruchomić polecenie create astro w dowolnym miejscu na swoim komputerze, więc nie musisz tworzyć nowego, pustego katalogu dla Twojego projektu przed rozpoczęciem. Jeżeli nie masz jeszcze pustego folderu na Twój nowy projekt, asystent inicjalizacji stworzy go automatycznie.

Jeśli wszystko poszło zgodnie z planem, to zobaczysz wiadomość o sukcesie, po której pojawią się kolejne sugerowane kroki. Teraz, kiedy Twój projekt został stworzony, możesz przy pomocy polecenia cd przejść do folderu z projektem, aby zacząć korzystać z Astro.
Jeżeli podczas inicjalizacji pominąłeś krok wykonujący npm install, to upewnij się, żeby zainstalować zależności projektu przed przejściem dalej.
Teraz możesz uruchomić serwer deweloperski Astro i sprawdzać podgląd Twojego projektu na żywo podczas tworzenia aplikacji!

Użyj motywu lub szablonu startowego

Możesz również rozpocząć nowy projekt Astro i oprzeć go o oficjalny przykład albo o gałąź main dowolnego repozytorium na GitHubie, przekazując argument z flagą --template do polecenia create astro.

Przejrzyj nasze motywy i przykładowe szablony, gdzie znajdziesz motywy dla blogów, portfolio, stron z dokumentacją, stron docelowych i wiele więcej! Możesz także poszukać na GitHubie, aby znaleźć jeszcze więcej projektów startowych.

Uruchom następujące polecenie w swoim terminalu, podając nazwę oficjalnego szablonu startowego Astro lub nazwę użytkownika i repozytorium GitHub motywu, którego chcesz użyć:

# stwórz nowy projekt przy użyciu oficjalnego przykładu
npm create astro@latest -- --template <example-name>

# stwórz nowy projekt oparty na gałęzi "main" repozytorium z GitHub
npm create astro@latest -- --template <github-username>/<github-repo>

# stwórz nowy projekt przy użyciu oficjalnego przykładu
pnpm create astro@latest --template <example-name>

# stwórz nowy projekt oparty na gałęzi "main" repozytorium z GitHub
pnpm create astro@latest --template <github-username>/<github-repo>

# stwórz nowy projekt przy użyciu oficjalnego przykład
yarn create astro --template <example-name>

# stwórz nowy projekt oparty na gałęzi "main" repozytorium z GitHub
yarn create astro --template <github-username>/<github-repo>

W trybie domyślnym, polecenie użyje gałęzi “main” danego repozytorium. Żeby użyć innej nazwy gałęzi, jako część flagi --template przekaż argument: <github-username>/<github-repo>#<branch>.

Odpowiedz na pytania i podążaj za instrukcjami konfiguratora CLI.
Możesz teraz uruchomić serwer deweloperski Astro i zobaczyć podgląd swojego projektu na żywo, podczas gdy dostosowujesz go do swoich potrzeb!

Edytuj swój projekt

Aby wprowadzić zmiany w swoim projekcie, otwórz folder z projektem w edytorze kodu. Praca w trybie deweloperskim z uruchomioną funkcją serwera deweloperskiego umożliwia bieżący podgląd zmian w przeglądarce.

Możesz również skonfigurować różne aspekty środowiska deweloperskiego, takie jak TypeScript lub dodanie oficjalnej wtyczki do edytora kodu.

Uruchom serwer deweloperski Astro

Astro ma wbudowany serwer deweloperski, który zawiera wszystko, czego potrzebujesz do rozwoju projektu. Polecenie CLI astro dev uruchomi lokalny serwer deweloperski, dzięki czemu po raz pierwszy zobaczysz swoją nową stronę internetową w działaniu.

Każdy szablon startowy zawiera wstępnie skonfigurowany skrypt, który uruchomi astro dev za Ciebie. Po przejściu do katalogu projektu, użyj swojego ulubionego menedżera pakietów, aby uruchomić to polecenie i rozpocząć serwer deweloperski Astro.

npm run dev

pnpm run dev

yarn run dev

Jeżeli wszystko pójdzie zgodnie z planem, Astro uruchomi Twój projekt pod adresem http://localhost:4321/. Odwiedź ten link w przeglądarce i zobacz swoją nową stronę!

Praca w trybie deweloperskim

Astro będzie nasłuchiwać zmian w Twoim folderze src/ oraz aktualizować podgląd strony wraz z wprowadzanymi zmianami, więc nie musisz ponownie uruchamiać serwera, aby zobaczyć wprowadzone zmiany. Jeżeli serwer deweloperski jest uruchomiony, zawsze będziesz w stanie zobaczyć bieżącą wersję swojej strony w przeglądarce.

Przeglądając stronę, będziesz miał dostęp do deweloperskiego paska narzędzi Astro (EN). Podczas budowania pomoże Ci on rewidować Twoje Wyspy, zauważać problemy z dostępnością oraz więcej.

Jeżeli po uruchomieniu serwera deweloperskiego nie jesteś w stanie otworzyć swojego projektu w przeglądarce, wróć do terminala, w którym uruchomiłeś komendę dev, i sprawdź wyświetloną wiadomość. Powinna poinformować Cię, dlaczego wystąpił błąd lub czy Twój projekt jest uruchomiony pod innym adresem URL niż http://localhost:4321/.

Skonfiguruj swoje środowisko dewelperskie

Zapoznaj się z poniższymi przewodnikami, aby dostosować swoje środowisko deweloperskie.

Konfiguracja edytora Dostosuj swój edytor kodu, aby poprawić doświadczenie deweloperskie w Astro i odblokować nowe funkcje.

Pasek narzędzi deweloperskich Poznaj przydatne funkcje paska narzędzi deweloperskich.

TypeScript w Astro

Astro ma wbudowane wsparcie dla TypeScript, które może pomóc w zapobieganiu błędom w czasie wykonywania funkcji w środowisku uruchomieniowym poprzez definiowanie kształtów obiektów i komponentów w Twoim kodzie.

Nie musisz pisać kodu w TypeScript, żeby Twój projekt czerpał z niego korzyści. Astro zawsze potraktuje kod w Twoim komponencie jako TypeScript, a rozszerzenie Astro w VSCode wywnioskuje jak najwięcej, aby dostarczyć autouzupełnianie, wskazówki albo informacje o błędach w Twoim edytorze.

Przeczytaj więcej na temat wykorzystania i konfiguracji TypeScript w Astro (EN)

Buduj i przeglądaj swoją stronę

Aby sprawdzić wersję swojej strony, która zostanie stworzona podczas budowania finalnej wersji, wyjdź z serwera deweloperskiego (Ctrl + C) i uruchom odpowiednie polecenie menedżera paczek w swoim terminalu:

npm run build

pnpm build

yarn run build

Astro zbuduje gotowy do wdrożenia na produkcję plik z zawartością Twojej strony w osobnym folderze (domyślnie dist/), a Ty możesz oglądać ten proces w terminalu. Poinformuje Cię o potencjalnych błędach, które pojawiły się podczas kompilacji. Jeżeli TypeScript jest skonfigurowany na ‘strict’ albo ‘strictest’, polecenie ‘build’ sprawdzi projekt pod względem błędów typowania.

Kiedy kompilacja się zakończy, uruchom odpowiednie polecenie preview (np. npm run preview) w terminalu, aby zobaczyć efekt końcowy kompilacji strony lokalnie w przeglądarce internetowej.

Zwróć uwagę, że ten podgląd pokazuje kod w takiej formie, w jakiej istniał w momencie ostatniej kompilacji na produkcję. Ma to na celu umożliwienie podglądu tego, jak Twoja strona będzie wyglądać po wdrożeniu na Internet. Wszelkie późniejsze zmiany w kodzie, dokonane po zbudowaniu, nie będą widoczne podczas podglądu strony, dopóki ponownie nie uruchomisz polecenia budującego.

Użyj kombinacji klawiszy (Ctrl + C), żeby wyjść z podglądu i uruchomić inne polecenie, takie jak restart serwera deweloperskiego, żeby wrócić do pracy w trybie deweloperskim, który na bieżąco aktualizuje podgląd strony w przeglądarce wraz ze zmianami w edytorze kodu.

Czytaj więcej na temat CLI Astro (EN) i poleceń, których będziesz używać podczas pracy z Astro.

Wdrożenie strony na produkcję

Możesz rozważyć wdrożenie swojej aplikacji na produkcję od razu, zanim dodasz albo zmienisz zbyt dużo kodu. Jest to pomocne w opublikowaniu minimalnej, działającej wersji Twojej strony i może zaoszczędzić Ci trochę czasu oraz zapobiec problemom związanym z wdrożeniem produkcyjnym w późniejszym terminie.

Kolejne kroki

Gratulacje! Teraz jesteś gotów, żeby rozpocząć budowanie z Astro! 🥳

Poniżej znajdziesz kilka tematów, z którymi polecamy się zapoznać. Możesz je czytać w dowolnej kolejności. Możesz też zostawić dokumentację na później i poeksperymentować trochę ze swoim nowym projektem Astro oraz wrócić do niej, kiedy pojawią się jakieś trudności bądź będziesz mieć pytania.

Odkryj Możliwości Astro

Zrozum kod w projekcie Zapoznaj się ze strukturą plików Astro w naszym przewodniku Struktura Projektu.

Tworzenie Kolekcji Treści Dodaj do swojej nowej strony treść przy użyciu walidacji frontmatter i automatycznego zabezpieczenia typowania.

Dodaj wsparcie View Transitions Twórz płynne przejścia między stronami i animacje.

Naucz się o Wyspach Poczytaj na temat architektury wysp Astro.

Weź udział w poradniku wprowadzającym

Zbuduj w pełni funkcjonalny blog w Astro, rozpoczynając od pojedynczej pustej strony, korzystając z poradnika wprowadzającego (EN).

Jest to świetny sposób żeby sprawdzić jak działa Astro i zrozumieć podstawowe zasady funkcjonowania stron, układów, komponentów, routingu, Wysp i wielu innych. Poradnik zawiera również opcjonalną, przyjazną dla początkujących sekcję, która wyjaśnia podstawowe pojęcia związane z tworzeniem stron internetowych. Przeprowadza ona przez proces instalacji niezbędnych aplikacji na Twoim komputerze, tworzenia konta na GitHub oraz wdrożenia produkcyjnego Twojej strony na produkcję.

Instalacja Ręczna

Ten poradnik przeprowadzi Cię krok po kroku przez ręczną instalację i konfigurację nowego projektu Astro.

Jeśli nie chcesz korzystać z automatycznej inicjalizacji poleceniem CLI create astro, możesz skonfigurować projekt samodzielnie, podążając za przedstawionym poniżej poradnikiem.

Stwórz folder na projekt

Stwórz pusty folder z nazwą Twojego projektu, a później do niego przejdź.
Okno terminala
```
mkdir my-astro-project
cd my-astro-project
```
Gdy znajdziesz się w nowym katalogu, stwórz plik package.json. W ten sposób będziesz zarządzać zależnościami swojego projektu, w tym również Astro. Jeżeli nie jesteś zaznajomiony z tym formatem pliku, uruchom następujące polecenie, aby go utworzyć.
- npm
- pnpm
- yarn
Okno terminala
npm init --yes
Okno terminala
pnpm init
Okno terminala
yarn init --yes
Zainstaluj Astro

Najpierw zainstaluj zależności Astro w Twoim projekcie.

Astro musi zostać zainstalowane lokalnie, nie globalnie. Upewnij się, że nie uruchamiasz polecenia npm install -g astro, pnpm add -g astro lub yarn add global astro.
- npm
- pnpm
- yarn
Okno terminala
npm install astro
Okno terminala
pnpm add astro
Okno terminala
yarn add astro
Teraz podmień zawartość swojego package.json na poniższą sekcję scripts:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
Użyjesz tych skryptów później w poradniku uruchamiania Astro i korzystania z różnych poleceń.

Stwórz swoją pierwszą stronę

W edytorze tekstowym stwórz nowy plik src/pages/index.astro. Będzie to Twoja pierwsza strona w projekcie Astro.

W tym kroku skopiuj i wklej następujące fragmenty kodu (uwzględniając kreski ---) w nowo powstałym pliku:

---
// Witaj w Astro! Wszystko pomiędzy tymi potrójnymi kreskami
// to Twój "frontmatter komponentu". Nigdy nie uruchamia się w przeglądarce.
console.log('To uruchamia się w Twoim terminalu, a nie w przeglądarce!');
---
<!-- Poniżej znajduje się Twój "szablon komponentu". To po prostu HTML, ale
    z dodatkiem magii, aby pomóc Ci tworzyć świetne szablony. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

Stwórz swój pierwszy zasób statyczny

Stwórz również folder public/ w celu przechowywania plików statycznych. Astro zawsze będzie je uwzględniać przy kompilacji na produkcję, więc możesz swobodnie tworzyć odnośniki do nich wewnątrz szablonów komponentów.

W edytorze tekstu stwórz nowy plik public/robots.txt. robots.txt to prosty plik, który większość stron uwzględnia, aby powiedzieć botom takim jak Google, jak obchodzić się z Twoją stroną.

W tym kroku skopiuj i wklej następujące fragmenty kodu w nowo powstałym pliku:
public/robots.txt
```
# Przykład: Pozwól wszystkim botom na skanowanie i indeksowanie Twojej strony.
# Pełna składnia: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
Stwórz astro.config.mjs

Astro jest konfigurowane przy użyciu astro.config.mjs. Choć ten plik jest opcjonalny, jeśli nie potrzebujesz specjalnej konfiguracji Astro, warto go stworzyć od razu na przyszłość.

Stwórz astro.config.mjs w ‘root’ projektu i skopiuj do niego kod poniżej:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
Jeżeli chcesz uwzględnić framework z komponentami UI (EN), taki jak React, Svelte itp., albo używać w swoim projekcie narzędzi jak Tailwind lub Partytown, to w tym miejscu możesz je ręcznie zaimportować i skonfigurować.

Zapoznaj się z dokumentacją konfiguracji API (EN) Astro w celu uzyskania większej ilości informacji.
Dodaj wsparcie TypeScript

TypeScript jest konfigurowany przy użyciu tsconfig.json. Nawet jeżeli nie piszesz kodu w Typescript, ten plik jest ważny dla narzędzi takich jak Astro i VS Code, żeby wiedziały, jak rozumieć Twój projekt. Niektóre funkcjonalności (np. importy paczek npm) nie są w pełni wspierane w edytorze bez pliku tsconfig.json.

Jeżeli planujesz pisać kod w TypeScript, to użycie szablonu Astro strict lub strictest jest rekomendowane. Możesz przejrzeć i porównać trzy szablony konfiguracyjne w astro/tsconfigs/.

Stwórz tsconfig.json w folderze ‘root’ swojego projektu i skopiuj do niego poniższy kod. (Możesz użyć base, strict, lub strictest dla swojego szablonu TypeScript):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Na koniec, stwórz src/env.d.ts, aby poinformować TypeScript o dostępnych typach globalnych w projekcie Astro:
src/env.d.ts
```
/// <reference types="astro/client" />
```
Przeczytaj poradnik instalacji TypeScript (EN) w Astro w celu uzyskania większej ilości informacji.
Kolejne kroki

Jeżeli przeszedłeś powyższe kroki, to struktura w Twoim projekcie powinna wyglądać w ten sposób.
- Foldernode_modules/
  - …
- Folderpublic/
  - robots.txt
- Foldersrc/
  - Folderpages/
    index.astro
  - env.d.ts
- astro.config.mjs
- package-lock.json bądź yarn.lock, pnpm-lock.yaml, itd.
- package.json
- tsconfig.json
Możesz teraz uruchomić serwer deweloperski Astro i sprawdzić podgląd Twojego projektu na żywo podczas tworzenia aplikacji!

Pomóż nam

Społeczność