diff --git a/src/content/docs/pl/basics/project-structure.mdx b/src/content/docs/pl/basics/project-structure.mdx new file mode 100644 index 0000000000000..19d70bfc027ce --- /dev/null +++ b/src/content/docs/pl/basics/project-structure.mdx @@ -0,0 +1,131 @@ +--- +title: Struktura projektu +description: Naucz się, jak zorganizować projekt z Astro. +i18nReady: true +--- +import { FileTree } from '@astrojs/starlight/components'; + +Twój nowy projekt Astro wygenerowany dzięki kreatorowi CLI `create astro` już zawiera kilka plików i folderów. Inne stworzysz już sam i dodasz je do istniejącej struktury plików Astro. + +Poniżej przedstawimy Ci w jaki sposób projekt Astro jest zorganizowany oraz jakie pliki znajdziesz w swoim nowym projekcie. + +## Foldery i Pliki + +Astro wykorzystuje z góry narzuconą strukturę folderów dla Twojego projektu. Każdy główny folder projektu Astro powinien zawierać następujące foldery i pliki: + +- `src/*` - Kod źródłowy Twojego projektu. (komponenty, strony, style, itp.) +- `public/*` - Twoje nieprzetworzone, pozaprogramowe zasoby. (fonty, ikony, itp.) +- `package.json` - Manifest projektu. +- `astro.config.mjs` - Plik konfiguracyjny Astro. (zalecany) +- `tsconfig.json` - Plik konfiguracyjny TypeScript. (zalecany) + +### Przykładowe Drzewko Projektu + +Standardowy folder projektu Astro może wyglądać tak: + + +- public/ + - robots.txt + - favicon.svg + - social-image.png +- src/ + - components/ + - Header.astro + - Button.jsx + - layouts/ + - PostLayout.astro + - pages/ + - posts/ + - post1.md + - post2.md + - post3.md + - index.astro + - styles/ + - global.css +- astro.config.mjs +- package.json +- tsconfig.json + + +### `src/` + +Folder `src/` to miejsce, gdzie żyje większość kodu źródłowego Twojego projektu. Zawiera on: + +- [Strony](/pl/basics/astro-pages/) +- [Layouty](/pl/basics/layouts/) +- [Komponenty Astro](/pl/basics/astro-components/) +- [Komponenty frameworków UI (React, itp.)](/pl/guides/framework-components/) +- [Style (CSS, Sass)](/pl/guides/styling/) +- [Pliki Markdown](/pl/guides/markdown-content/) + +Astro przetwarza, optymalizuje i pakuje Twoje pliki z folderu `src/` aby stworzyć finalną stronę internetową, która wysyłana jest do przeglądarki. W przeciwieństwie do statycznego folderu `public/` zawartość `src/` jest budowana i obsługiwana przez Astro. + +Niektóre pliki (takie jak komponenty Astro) nie są nawet wysyłane w swojej postaci, tylko renderowane jako statyczny HTML. Inne pliki (jak CSS) są przesyłane do przeglądarki ale mogą być zoptymalizowane bądź spakowane z innymi plikami CSS dla lepszej wydajności. + +:::tip +Podczas gdy ten przewodnik opisuje niektóre popularne zasady użyte przez społeczność Astro, to jedynymi folderami zarezerwowanymi przez samo Astro są `src/pages/` i `src/content/`. Masz wolną rękę aby zmieniać nazwy i zmieniać układ innych folderów w taki sposób, który jest dla Ciebie najlepszy. +::: + +### `src/components` + +**Komponenty** są jednostkami wielekrotnego użytku dla Twoich stron HTML. Mogą być one [komponentami Astro](/pl/basics/astro-components/), lub [komponentami frameworków UI](/pl/guides/framework-components/) jak React bądź Vue. Powszechne jest aby grupować i organizować wszystkie komponenty Twojego folderu w tym folderze. + +To jest powszechnie przyjęta praktyka w projektach Astro, lecz nie jest ona wymagana. Możesz dowolnie organizować swoje komponenty według własnych życzeń! + +### `src/content` + +Folder `src/content/` ma na celu przechowywanie [kolekcji zawartości](/pl/guides/content-collections/) i ich opcjonalne pliki konfiguracji. Żadne inne pliki nie mają prawa tu być. + +### `src/layouts` + +[Layouty](/pl/basics/layouts/) to komponenty Astro, które definiują strukturę UI współdzieloną przez jedną lub więcej [stron](/pl/basics/astro-pages/). + +Tak jak `src/components`, ten folder to znana, ale niewymagana konwencja. + +### `src/pages` + +[Strony](/pl/basics/astro-pages/) są specjalnym rodzajem komponentu, dzięki którym stworzysz nowe podstrony swojej witryny. Strona może być komponentem Astro bądź plikiem Markdown, który reprezentuje jakąś część zawartości Twojego portalu. + +:::caution +`src/pages` to **wymagany** podfolder Twojego projektu Astro. Bez tego Twoja strona nie będzie miała żadnych stron czy ścieżek! +::: + +### `src/styles` + +Powszechnym zamysłem jest przechowywanie Twoich plików CSS bądź Sass w `src/styles`, ale nie jest on konieczny. Tak długo, jak Twoje style znajdują się gdziekolwiek w katalogu src/ i są poprawnie importowane, Astro zajmie się ich obsługą i optymalizacją. + +### `public/` + +Folder `public/` jest dla plików i zasobów Twojego projektu, które nie muszą być przetworzone podczas procesu budowania Astro. Pliki z tego folderu będą skopiowane do folderu budowania w stanie nienaruszonym, a po tym Twoja strona zostanie stworzona. + +Takie zachowanie sprawia, że `public/` jest idealnym miejscem na podstawowe zasoby jak zdjęcia czy fonty, lub dla specjalnych plików takich jak `robots.txt` i `manifest.webmanifest`. + +Możesz umieścić w `public/` pliki CSS i JavaScript, ale pamiętaj, że te pliki nie będą zoptymalizowane ani spakowane w Twoim finalnym projekcie. + +:::tip +Ogólnie przyjmując, każdy plik CSS lub JavaScript napisany przez Ciebie powinien się znajdować w folderze `src/`. +::: + +### `package.json` + +Ten plik jest używany przez paczkę mendedżerów pakietów to zarządzania Twoimi zależnościami. Definiuje również powszechnie użyte skrypty do uruchamiania Astro (np. `npm start`, `npm run build`). + +Znajdują się tu [dwa typy zależności](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file), które możesz określić jako `package.json`: `dependencies` i `devDependencies`. W większości przypadków oba pracują tak samo: Astro potrzebuje wszelkie zależności podczas budowy, a Twój menedżer paczki je zainstaluje. Zalecamy przechowywanie wszystkich Twoich zależności w `dependencies` na początek, oraz używać jedynie `devDependencies` gdy najdzie taka specyficzna potrzeba. + +Aby wesprzeć tworzenie nowego pliku `package.json` dla Twojego projektu, sprawdź instrukcję [ręcznej instalacji](/pl/install-and-setup/#instalacja-ręczna). + +### `astro.config.mjs` + +Ten plik jest wygenerowany w każdym startowym szablonie i zawiera opcje konfiguracji dla Twojego projektu Astro. Tutaj możesz określić opcje budowania, opcje serwera, jakich integracji użyć i wiele więcej. + +Astro wspiera kilka formatów dla pliku konfiguracyjnego JavaScriptu: `astro.config.js`, `astro.config.mjs`, `astro.config.cjs` i `astro.config.ts`. Polecamy korzystanie z `.mjs` w większości przypadków, oraz z `.ts` w razie pisania w TypeScript. + +Ładowanie pliku konfiguracyjnego TypeScript jest obsługiwane przez [`tsm`](https://github.com/lukeed/tsm) i będzie zwracał szczególną uwagę na Twoje opcje `tsconfig`. + +Zerknij na [Przewodnik Konfiguracji Astro](/pl/guides/configuring-astro/) aby poznać szczegóły opcji konfiguracyjnych. + +### `tsconfig.json` + +Ten plik jest generowany w każdym szablonie startowym i zawiera on opcje konfiguracji TypeScript dla Twojego projektu Astro. Niektóre funkcje (takie jak importy pakietów npm) nie są w pełni obsługiwane w edytorze bez pliku `tsconfig.json`. + +Szczegóły dotyczące ustawień konfiguracji znajdziesz w [Przewodniku TypeScript](/pl/guides/typescript/).