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):

"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.

"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:

pnpm payload generate:importmap

Bez tego pola SEO nie wyrenderują się (błąd PayloadComponent not found in importMap).

// 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
hooks	Hooki: revalidate ISR, slug history 301, ochrona stron systemowych	hooks.md
kolekcje-katalog	Jakie kolekcje budować, kiedy, jak wpiąć (minimum nie maksimum)	kolekcje-katalog.md
fundamenty-projektu	Struktura katalogów, nazewnictwo, konwencje	fundamenty-projektu.md
deployment	Zmienne .env, ISR/SSG, force-dynamic, Coolify/Docker	deployment.md
pages	System pages (homepage/privacy/cookies) → ścieżki	pages.md
access	Role admin > editor > user, kontrola dostępu	access.md
payload-helpers	getSiteSettings / getSiteIntegrations	payload-helpers.md
seo	Metadata, hreflang, auto-fill, plugin-seo	seo.md
wymagania-prawne	Polityki, regulaminy, baner cookies, RODO (compliance)	wymagania-prawne.md
standardy-kodu	Dobre praktyki senior: typy, architektura, antywzorce	standardy-kodu.md
architektura-tresci	Jak budować, żeby klient wszystko edytował (filozofia CMS)	architektura-tresci.md
blocks	RenderBlocks — silnik renderowania bloków	blocks.md
consent	Banner cookies GDPR, Google Consent Mode	consent.md
turnstile	Cloudflare Turnstile (widget + verify)	turnstile.md
email	Wysyłka: SMTP z panelu lub Microsoft Graph (M365)	email.md
forms	Form-builder + submitForm (Turnstile + zapis)	forms.md
analytics	GA4 / GTM spięte z Consent Mode	analytics.md
slug	Auto-slug z tytułu, per locale	slug.md
notifications	Teksty wyników akcji (formularz) per język	notifications.md
storage	Media na Cloudflare R2 (offload z .env)	storage.md
security	Nagłówki bezpieczeństwa HTTP (HSTS, X-Frame...)	security.md
content	Blog/archiwa: kolekcje pod stroną-archiwum, listing, paginacja	content.md

Nowy projekt krok po kroku: getting-started.md Referencja wdrożenia frontu: getting-started.md Wydawanie nowych wersji wtyczki: publishing.md Jak komendy łączą się z Gitea (dla instalujących): gitea-commands.md Working with a project repo on Gitea (clone/pull/push): gitea-workflow.md · 🇵🇱 PL

Zasady dla wszystkich modułów

Helpery przyjmują payload jako argument — plugin nigdy nie woła getPayload sam.
Sekrety w panelu — SMTP, Turnstile secret, R2 w SiteIntegrations (admin-only). Odczyt server-side przez Local API.
Client/server split — kod z sekretami ma server-only; komponenty client w @intecion/ipal-kit/client.
Generyki na typy klienta — helpery przyjmują <T> (np. wygenerowany SiteSetting), bo plugin nie zna typów projektu.