145 lines
6.2 KiB
Markdown
145 lines
6.2 KiB
Markdown
# IPAL — Dokumentacja modułów
|
|
|
|
> **Zaczynasz wdrożenie?** Przeczytaj najpierw [WDROZENIE-PLAYBOOK.md](./WDROZENIE-PLAYBOOK.md) — sztywna procedura, kolejność, realne przykłady błędów.
|
|
|
|
**Instalacja pakietu** (token Gitea, rejestr vs repozytorium) → główny
|
|
[README](../README.md).
|
|
**Nowy projekt krok po kroku** → [getting-started.md](./getting-started.md).
|
|
|
|
Ta dokumentacja opisuje **konfigurację i moduły** pluginu — zakłada, że
|
|
`@intecion/ipal-kit` jest już zainstalowany.
|
|
|
|
IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który
|
|
dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
|
|
wizualne i podłączenia do Next.js.
|
|
|
|
## Zasada
|
|
|
|
- **Plugin** = logika, helpery, konfiguracja, globale.
|
|
- **Klient (projekt)** = komponenty (wygląd), pliki-podłączenia Next.js
|
|
(jednolinijkowe re-eksporty), konfiguracja front.
|
|
|
|
## Konfiguracja i wpięcie
|
|
|
|
### Wymagane zależności
|
|
|
|
Projekt klienta musi mieć (poza payloadem):
|
|
|
|
```json
|
|
"dependencies": {
|
|
"@payloadcms/plugin-seo": "3.84.1",
|
|
"@payloadcms/plugin-form-builder": "3.84.1",
|
|
"nodemailer": "^8.0.1",
|
|
"lucide-react": "^0.400.0",
|
|
"slugify": "^1.6.6",
|
|
"server-only": "^0.0.1"
|
|
}
|
|
```
|
|
|
|
Wersje `@payloadcms/*` **muszą** być identyczne z wersją `payload`. Wymuś
|
|
spójność przez `pnpm.overrides` (patrz niżej), inaczej Payload odrzuci wpięcie
|
|
pluginów (pusty tab SEO, brak kolekcji Forms) albo crashuje.
|
|
|
|
```json
|
|
"pnpm": {
|
|
"overrides": {
|
|
"payload": "3.84.1",
|
|
"@payloadcms/ui": "3.84.1",
|
|
"@payloadcms/next": "3.84.1",
|
|
"@payloadcms/db-sqlite": "3.84.1",
|
|
"@payloadcms/richtext-lexical": "3.84.1",
|
|
"@payloadcms/plugin-seo": "3.84.1",
|
|
"@payloadcms/plugin-form-builder": "3.84.1"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Po wpięciu — wygeneruj importMap
|
|
|
|
Plugin dostarcza komponenty admina (pola SEO). Po dodaniu uruchom:
|
|
|
|
```bash
|
|
pnpm payload generate:importmap
|
|
```
|
|
|
|
Bez tego pola SEO nie wyrenderują się (błąd `PayloadComponent not found in
|
|
importMap`).
|
|
|
|
```ts
|
|
// payload.config.ts
|
|
import { ipalKit } from '@intecion/ipal-kit'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
plugins: [
|
|
ipalKit({
|
|
i18n: {
|
|
defaultLocale: 'pl',
|
|
locales: [
|
|
{ code: 'pl', label: 'Polski' },
|
|
{ code: 'en', label: 'English' },
|
|
],
|
|
},
|
|
access: { authCollection: 'users' },
|
|
pages: { slug: 'pages' },
|
|
seo: { collections: ['pages', 'posts'] },
|
|
forms: { redirectRelationships: ['pages'] },
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
## Entry pointy pakietu
|
|
|
|
| Import | Zawiera | Kontekst |
|
|
|---|---|---|
|
|
| `@intecion/ipal-kit` | logika server-safe, plugin, helpery | server / config |
|
|
| `@intecion/ipal-kit/server` | runtime server-only (sendEmail, verifyTurnstile, submitForm) | Server Actions / route handlers |
|
|
| `@intecion/ipal-kit/client` | komponenty client (consent, Turnstile, Analytics) | `'use client'` |
|
|
| `@intecion/ipal-kit/rsc` | RenderBlocks (RSC) | server component |
|
|
| `@intecion/ipal-kit/next/middleware` | locale middleware (import bez zmian) | `proxy.ts` (Next 16; dawniej `middleware.ts`) |
|
|
|
|
## Moduły
|
|
|
|
| Moduł | Opis | Dok |
|
|
|---|---|---|
|
|
| i18n | Lokalizacja, negocjacja locale, ścieżki URL, strona jednojęzyczna | [i18n.md](./i18n.md) |
|
|
| hooks | Hooki: revalidate ISR, slug history 301, ochrona stron systemowych | [hooks.md](./hooks.md) |
|
|
| kolekcje-katalog | Jakie kolekcje budować, kiedy, jak wpiąć (minimum nie maksimum) | [kolekcje-katalog.md](./kolekcje-katalog.md) |
|
|
| fundamenty-projektu | Struktura katalogów, nazewnictwo, konwencje | [fundamenty-projektu.md](./fundamenty-projektu.md) |
|
|
| deployment | Zmienne .env, ISR/SSG, force-dynamic, Coolify/Docker | [deployment.md](./deployment.md) |
|
|
| pages | System pages (homepage/privacy/cookies) → ścieżki | [pages.md](./pages.md) |
|
|
| access | Role admin > editor > user, kontrola dostępu | [access.md](./access.md) |
|
|
| payload-helpers | getSiteSettings / getSiteIntegrations | [payload-helpers.md](./payload-helpers.md) |
|
|
| seo | Metadata, hreflang, auto-fill, plugin-seo | [seo.md](./seo.md) |
|
|
| wymagania-prawne | **Polityki, regulaminy, baner cookies, RODO (compliance)** | [wymagania-prawne.md](./wymagania-prawne.md) |
|
|
| standardy-kodu | **Dobre praktyki senior: typy, architektura, antywzorce** | [standardy-kodu.md](./standardy-kodu.md) |
|
|
| architektura-tresci | **Jak budować, żeby klient wszystko edytował** (filozofia CMS) | [architektura-tresci.md](./architektura-tresci.md) |
|
|
| blocks | RenderBlocks — silnik renderowania bloków | [blocks.md](./blocks.md) |
|
|
| consent | Banner cookies GDPR, Google Consent Mode | [consent.md](./consent.md) |
|
|
| turnstile | Cloudflare Turnstile (widget + verify) | [turnstile.md](./turnstile.md) |
|
|
| email | Wysyłka: SMTP z panelu lub Microsoft Graph (M365) | [email.md](./email.md) |
|
|
| forms | Form-builder + submitForm (Turnstile + zapis) | [forms.md](./forms.md) |
|
|
| analytics | GA4 / GTM spięte z Consent Mode | [analytics.md](./analytics.md) |
|
|
| slug | Auto-slug z tytułu, per locale | [slug.md](./slug.md) |
|
|
| notifications | Teksty wyników akcji (formularz) per język | [notifications.md](./notifications.md) |
|
|
| storage | Media na Cloudflare R2 (offload z .env) | [storage.md](./storage.md) |
|
|
| security | Nagłówki bezpieczeństwa HTTP (HSTS, X-Frame...) | [security.md](./security.md) |
|
|
| content | Blog/archiwa: kolekcje pod stroną-archiwum, listing, paginacja | [content.md](./content.md) |
|
|
|
|
Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
|
|
Referencja wdrożenia frontu: [getting-started.md](./getting-started.md)
|
|
Wydawanie nowych wersji wtyczki: [publishing.md](./publishing.md)
|
|
Jak komendy łączą się z Gitea (dla instalujących): [gitea-commands.md](./gitea-commands.md)
|
|
Working with a project repo on Gitea (clone/pull/push): [gitea-workflow.md](./gitea-workflow.md) · [🇵🇱 PL](./gitea-workflow.pl.md)
|
|
|
|
## Zasady dla wszystkich modułów
|
|
|
|
1. **Helpery przyjmują `payload` jako argument** — plugin nigdy nie woła
|
|
`getPayload` sam.
|
|
2. **Sekrety w panelu** — SMTP, Turnstile secret, R2 w SiteIntegrations
|
|
(admin-only). Odczyt server-side przez Local API.
|
|
3. **Client/server split** — kod z sekretami ma `server-only`; komponenty
|
|
client w `@intecion/ipal-kit/client`.
|
|
4. **Generyki na typy klienta** — helpery przyjmują `<T>` (np. wygenerowany
|
|
`SiteSetting`), bo plugin nie zna typów projektu. |