ship docs/ in npm package for agent access
This commit is contained in:
+204
-221
@@ -1,14 +1,18 @@
|
||||
# Nowy projekt — krok po kroku
|
||||
# Setup projektu — od zera do wdrożenia
|
||||
|
||||
> **Instalacja pluginu** (token Gitea, rejestr vs git) jest opisana w głównym
|
||||
Pełny przewodnik: od pustego katalogu do działającej, wielojęzycznej strony z
|
||||
blokami, consentem, formularzem i SEO. Łączy szkielet projektu (kolejność
|
||||
kroków) z wymaganiami frontendu (Tailwind, trasy, bloki, metadata).
|
||||
|
||||
> **Instalacja pluginu** (token Gitea, rejestr vs git) jest w głównym
|
||||
> [README](../README.md). Ten przewodnik zakłada, że `@intecion/ipal-kit` jest
|
||||
> już zainstalowany, i przeprowadza przez **konfigurację** projektu.
|
||||
> zainstalowany, i przeprowadza przez konfigurację.
|
||||
>
|
||||
> **Zaczynasz wdrożenie produkcyjne?** Najpierw [WDROZENIE-PLAYBOOK.md](./WDROZENIE-PLAYBOOK.md)
|
||||
> — zasady, procedura, pułapki.
|
||||
|
||||
Od pustego katalogu do działającej, wielojęzycznej strony z blokami, consentem i
|
||||
formularzem. Kolejność jest istotna: kilka kroków zależy od poprzednich (schemat
|
||||
bazy, importMap, kolejność wpięcia).
|
||||
|
||||
Zakłada: pnpm, Node 20+, SQLite (dla Postgres zmienia się tylko adapter).
|
||||
Kolejność jest istotna — kilka kroków zależy od poprzednich (schemat bazy,
|
||||
importMap, kolejność wpięcia). Zakłada: pnpm, Node 22, Next 16.
|
||||
|
||||
---
|
||||
|
||||
@@ -16,21 +20,22 @@ Zakłada: pnpm, Node 20+, SQLite (dla Postgres zmienia się tylko adapter).
|
||||
|
||||
```bash
|
||||
npx create-payload-app@latest moj-projekt
|
||||
# → Blank, SQLite
|
||||
# → Blank, SQLite (dev) / Postgres (prod)
|
||||
cd moj-projekt
|
||||
```
|
||||
|
||||
## 2. Plugin i zależności
|
||||
|
||||
Zainstaluj `@intecion/ipal-kit` zgodnie z [README](../README.md) (rejestr Gitea
|
||||
albo bezpośrednio z repozytorium — wymaga tokenu). Następnie dodaj zależności
|
||||
współdzielone z Payloadem, których plugin nie zaciąga sam:
|
||||
Zainstaluj `@intecion/ipal-kit` zgodnie z [README](../README.md). Dodaj
|
||||
zależności współdzielone z Payloadem, których plugin nie zaciąga sam:
|
||||
|
||||
```bash
|
||||
pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \
|
||||
pnpm add @payloadcms/plugin-seo @payloadcms/plugin-form-builder \
|
||||
nodemailer lucide-react slugify server-only
|
||||
```
|
||||
|
||||
### Spójność wersji @payloadcms/* (KRYTYCZNE)
|
||||
|
||||
Wersje `@payloadcms/*` **muszą** zgadzać się z wersją `payload` — inaczej
|
||||
zagnieżdżone pluginy się nie wpinają (pusty tab SEO, brak kolekcji Forms) albo
|
||||
projekt się wywala. Wymuś w `package.json`:
|
||||
@@ -38,13 +43,13 @@ projekt się wywala. Wymuś w `package.json`:
|
||||
```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"
|
||||
"payload": "3.88.0",
|
||||
"@payloadcms/ui": "3.88.0",
|
||||
"@payloadcms/next": "3.88.0",
|
||||
"@payloadcms/db-postgres": "3.88.0",
|
||||
"@payloadcms/richtext-lexical": "3.88.0",
|
||||
"@payloadcms/plugin-seo": "3.88.0",
|
||||
"@payloadcms/plugin-form-builder": "3.88.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -53,11 +58,17 @@ projekt się wywala. Wymuś w `package.json`:
|
||||
rm -rf node_modules pnpm-lock.yaml && pnpm install
|
||||
```
|
||||
|
||||
### Build script z --webpack (Next 16)
|
||||
|
||||
Next 16 domyślnie Turbopack, który konfliktuje z withPayload. W `package.json`:
|
||||
```json
|
||||
"build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" next build --webpack"
|
||||
```
|
||||
|
||||
## 3. Konfiguracja locale — jedno źródło
|
||||
|
||||
Middleware działa przed Payloadem i potrzebuje listy locale synchronicznie, więc
|
||||
nie może jej czytać z gotowego configu. Wydziel osobny plik i importuj w obu
|
||||
miejscach:
|
||||
Proxy działa przed Payloadem i potrzebuje listy locale synchronicznie, więc nie
|
||||
może jej czytać z gotowego configu. Wydziel osobny plik, importuj wszędzie:
|
||||
|
||||
```ts
|
||||
// src/i18n.config.ts
|
||||
@@ -67,25 +78,24 @@ export const i18nConfig = {
|
||||
{ code: 'pl', label: 'Polski' },
|
||||
{ code: 'en', label: 'English' },
|
||||
],
|
||||
} as const
|
||||
} as const // as const — inaczej TS nie uzna locales za niepustą tuple
|
||||
```
|
||||
|
||||
`as const` jest konieczne — bez niego TS nie uzna `locales` za niepustą listę.
|
||||
Importuj w: `payload.config` (ipalKit({ i18n: i18nConfig })) i `proxy.ts`.
|
||||
|
||||
## 4. payload.config.ts
|
||||
|
||||
```ts
|
||||
import { ipalKit, panelSmtpAdapter } from '@intecion/ipal-kit'
|
||||
import { ipalKit, mailAdapter } from '@intecion/ipal-kit'
|
||||
import { i18nConfig } from '@/i18n.config'
|
||||
import { Pages } from '@/collections/Pages'
|
||||
|
||||
export default buildConfig({
|
||||
// …reszta z template'u
|
||||
collections: [Users, Media, Pages],
|
||||
|
||||
// SMTP z panelu zamiast env — czyta Site Integrations przy każdym wysłaniu.
|
||||
// Dyspozytor email: czyta transport (SMTP/Graph) z panelu przy każdej wysyłce.
|
||||
// Bez tego maile form-buildera nie wyjdą (Payload podstawia mocka).
|
||||
email: panelSmtpAdapter(),
|
||||
email: mailAdapter(),
|
||||
|
||||
plugins: [
|
||||
ipalKit({
|
||||
@@ -113,11 +123,11 @@ export const Pages: CollectionConfig = {
|
||||
access: { read: () => true },
|
||||
fields: [
|
||||
{ name: 'title', type: 'text', required: true, localized: true },
|
||||
buildSlugField({ from: 'title' }),
|
||||
buildSlugField({ from: 'title' }), // NIGDY ręczny slug — plugin to ma
|
||||
{
|
||||
name: 'layout',
|
||||
type: 'blocks',
|
||||
blocks: [ContentBlock], // NIGDY pusta lista — Payload się wywala
|
||||
blocks: [ContentBlock], // NIGDY pusta lista — Payload crashuje
|
||||
},
|
||||
],
|
||||
}
|
||||
@@ -158,15 +168,28 @@ import type { BlockComponentMap } from '@intecion/ipal-kit/rsc'
|
||||
import { ContentBlockComponent } from '@/blocks/Content/Component'
|
||||
|
||||
export const blockRegistry: BlockComponentMap = {
|
||||
content: ContentBlockComponent,
|
||||
content: ContentBlockComponent, // klucz = slug bloku
|
||||
}
|
||||
```
|
||||
|
||||
Klucz w rejestrze = `slug` bloku.
|
||||
**Puste `blocks: []` crashuje** (traverseFields) — zawsze co najmniej jeden blok.
|
||||
|
||||
## 7. Tailwind
|
||||
### enhanceProps — wstrzykiwanie danych server-side do bloków
|
||||
|
||||
Blank template go nie ma, a komponenty pluginu (banner cookies) są w Tailwindzie.
|
||||
Bloki NIE importują `lib/*` (cykl importów). Wartości server-side (turnstileSiteKey,
|
||||
odbiorca formularza) wstrzykuje się przez enhanceProps — bez wiedzy pluginu:
|
||||
|
||||
```ts
|
||||
const enhanceProps = ({ block }) => {
|
||||
if (block.blockType === 'formBlock') return { turnstileSiteKey, notificationTo }
|
||||
return {}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Tailwind (WYMÓG)
|
||||
|
||||
Blank template go nie ma, a komponenty pluginu (banner cookies, Turnstile) są w
|
||||
czystym Tailwindzie.
|
||||
|
||||
```bash
|
||||
pnpm add tailwindcss @tailwindcss/postcss
|
||||
@@ -183,16 +206,30 @@ export default { plugins: { '@tailwindcss/postcss': {} } }
|
||||
@source "../../../node_modules/@intecion/ipal-kit/dist/**/*.js";
|
||||
```
|
||||
|
||||
`@source` jest **konieczny** — Tailwind nie skanuje `node_modules`, więc bez
|
||||
niego klasy komponentów pluginu nie powstaną i banner wyrenderuje się goły.
|
||||
Ścieżka jest relatywna do pliku CSS.
|
||||
**`@source` jest KONIECZNY** — Tailwind nie skanuje `node_modules`, więc bez
|
||||
niego klasy komponentów pluginu nie powstaną (banner wyrenderuje się goły).
|
||||
Ścieżka relatywna do pliku CSS.
|
||||
|
||||
## 8. Proxy (dawniej middleware)
|
||||
### Przestylowanie pod klienta
|
||||
|
||||
> **Next 16:** konwencja `middleware.ts` jest przestarzała — nazwa pliku to teraz
|
||||
> `proxy.ts`, a funkcja `proxy` zamiast `middleware`. Logika pluginu bez zmian:
|
||||
> `createLocaleMiddleware` działa tak samo. Migracja jednej komendy:
|
||||
> `npx @next/codemod@canary middleware-to-proxy .`
|
||||
Komponenty pluginu mają domyślny wygląd. Kolory/zaokrąglenia przez CSS custom
|
||||
properties (fallbacki wbudowane):
|
||||
```css
|
||||
:root {
|
||||
--ipal-primary: #16a34a;
|
||||
--ipal-radius: 1rem;
|
||||
}
|
||||
```
|
||||
Pełna lista tokenów + opcja classNames: [consent.md](./consent.md).
|
||||
|
||||
## 8. Proxy (routing locale) — NIGDY middleware.ts
|
||||
|
||||
> **Next 16 używa `proxy.ts`, NIE `middleware.ts`.** Plik `proxy.ts`, funkcja
|
||||
> `proxy`. `middleware.ts` jest przestarzały — jeśli istnieje, USUŃ go. Nigdy
|
||||
> obu naraz. Migracja starego: `npx @next/codemod@canary middleware-to-proxy .`
|
||||
>
|
||||
> Import z pluginu zostaje `@intecion/ipal-kit/next/middleware` — to nazwa
|
||||
> subpath eksportu, NIE nazwa pliku. Nie myl ich.
|
||||
|
||||
```ts
|
||||
// src/proxy.ts
|
||||
@@ -205,104 +242,89 @@ const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
|
||||
|
||||
export function proxy(request: NextRequest) {
|
||||
const result = localeMiddleware(request)
|
||||
if (result.type === 'next') return NextResponse.next()
|
||||
|
||||
const response = NextResponse.redirect(result.location)
|
||||
// cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
|
||||
if (result.cookie) response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
// Cookie zapisywany w OBU wynikach (redirect na '/' i next przy zmianie
|
||||
// języka), TYLKO gdy jest zgoda na functional.
|
||||
const response =
|
||||
result.type === 'next'
|
||||
? NextResponse.next()
|
||||
: NextResponse.redirect(result.location)
|
||||
|
||||
if (result.cookie) {
|
||||
response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
}
|
||||
return response
|
||||
}
|
||||
|
||||
// INLINE, nie import — Next analizuje ten obiekt statycznie i nie wykonuje
|
||||
// importów. Importowana stała zostanie zignorowana, proxy złapie /admin
|
||||
// i /_next, i wszystko zwróci 500.
|
||||
// Matcher INLINE (nie import) — Next analizuje statycznie, nie wykonuje importów.
|
||||
// Import stałej byłby zignorowany → proxy złapałby /admin /_next /api → 500.
|
||||
// Ten wzorzec łapie root '/' (negocjacja locale), pomija api/admin/_next/pliki.
|
||||
export const config = {
|
||||
matcher: ['/((?!api|admin|_next|.*\\..*).*)'],
|
||||
}
|
||||
```
|
||||
|
||||
> Import z pluginu zostaje `@intecion/ipal-kit/next/middleware` — to nazwa
|
||||
> subpath eksportu w pakiecie, niezależna od tego, czy plik projektu nazywa się
|
||||
> `middleware.ts` czy `proxy.ts`.
|
||||
### Zlokalizowane ścieżki — getLocalizedSlugs (NIGDY zaszyta mapa)
|
||||
|
||||
## 9. Warstwa dostępu do danych
|
||||
|
||||
Next uruchamia `generateMetadata` i komponent strony niezależnie — `cache()`
|
||||
sprawia, że nie pytają bazy dwa razy o to samo.
|
||||
Do przełącznika języka / budowania ścieżek NIE twórz zaszytej mapy slugów.
|
||||
Slugi są w bazie (pole `slug` localized):
|
||||
|
||||
```ts
|
||||
// src/lib/payload.ts
|
||||
import { cache } from 'react'
|
||||
import { getPayload } from 'payload'
|
||||
import config from '@/payload.config'
|
||||
import { getLocalizedSlugs, switchLocalePath } from '@intecion/ipal-kit'
|
||||
|
||||
export const getCachedPayload = cache(async () => getPayload({ config: await config }))
|
||||
|
||||
export const getSettings = cache(async (locale: string) =>
|
||||
(await getCachedPayload()).findGlobal({
|
||||
slug: 'site-settings',
|
||||
locale: locale as 'pl' | 'en',
|
||||
depth: 2,
|
||||
}),
|
||||
)
|
||||
const doc = await payload.findByID({ collection: 'pages', id, locale: 'all' })
|
||||
const slugs = getLocalizedSlugs({ slugField: doc.slug, config: i18nConfig })
|
||||
switchLocalePath({ slugs, targetLocale: 'en', config: i18nConfig }) // → '/en/about'
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/lib/locales.ts
|
||||
import { cache } from 'react'
|
||||
import config from '@/payload.config'
|
||||
## 9. Warstwa dostępu do danych — lib/ (jedno źródło)
|
||||
|
||||
export const getConfiguredLocales = cache(async (): Promise<string[]> => {
|
||||
const payloadConfig = await config
|
||||
return payloadConfig.localization ? payloadConfig.localization.locales.map((l) => l.code) : []
|
||||
```ts
|
||||
// src/lib/content.ts — JEDYNE źródło helperów pluginu
|
||||
import { createContentHelpers } from '@intecion/ipal-kit'
|
||||
import payloadConfig from '@/payload.config'
|
||||
import { i18nConfig } from '@/i18n.config'
|
||||
|
||||
export const {
|
||||
getCachedPayload, getSettings, getConfiguredLocales, resolveRoute, getEntries, robots,
|
||||
} = createContentHelpers({
|
||||
config: payloadConfig, // PAYLOAD config (nie i18n!)
|
||||
content: { collections: [] },
|
||||
i18n: i18nConfig, // i18n OSOBNO
|
||||
})
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/lib/pages.ts
|
||||
// src/lib/payload.ts — funkcje projektu, typowane
|
||||
import { cache } from 'react'
|
||||
import type { Page, SiteSetting } from '@/payload-types'
|
||||
import { getCachedPayload, getSettings } from './payload'
|
||||
import { getSiteSettings } from '@intecion/ipal-kit'
|
||||
import { getCachedPayload } from './content' // z content, nie osobny getPayload
|
||||
import type { SiteSetting } from '@/payload-types'
|
||||
|
||||
export const resolvePage = cache(
|
||||
async (locale: string, slugPath: string | null): Promise<Page | null> => {
|
||||
if (!slugPath) {
|
||||
// Strona główna z System Pages — edytor może ją zmienić bez zmiany kodu.
|
||||
const settings = (await getSettings(locale)) as SiteSetting
|
||||
const homepage = settings.homepage
|
||||
return homepage && typeof homepage === 'object' ? homepage : null
|
||||
}
|
||||
|
||||
const payload = await getCachedPayload()
|
||||
const result = await payload.find({
|
||||
collection: 'pages',
|
||||
where: { slug: { equals: slugPath } },
|
||||
locale: locale as 'pl' | 'en',
|
||||
depth: 2,
|
||||
limit: 1,
|
||||
})
|
||||
return result.docs[0] ?? null
|
||||
},
|
||||
export const getSettings = cache(async (locale: string) =>
|
||||
getSiteSettings<SiteSetting>(await getCachedPayload(), { locale: locale as never, depth: 2 }),
|
||||
)
|
||||
```
|
||||
|
||||
> NIE twórz `lib/pages.ts` (resolvePage) ani `lib/locales.ts` — plugin ma
|
||||
> `resolveRoute` i `getConfiguredLocales`. Duplikaty = rozjazd.
|
||||
|
||||
## 10. Trasy
|
||||
|
||||
Usuń starter — `(frontend)/layout.tsx` i `(frontend)/page.tsx`. Rootem zostaje
|
||||
layout locale, bo `<html lang>` musi znać język, a `(frontend)` jest ponad
|
||||
segmentem `[locale]`. Każdy trafia na ścieżkę z locale — middleware przekierowuje.
|
||||
layout locale (bo `<html lang>` musi znać język).
|
||||
|
||||
```
|
||||
src/app/(frontend)/
|
||||
styles.css
|
||||
[locale]/
|
||||
layout.tsx
|
||||
layout.tsx # walidacja locale + ConsentProvider + Analytics
|
||||
[[...slug]]/
|
||||
page.tsx
|
||||
page.tsx # render bloków
|
||||
```
|
||||
|
||||
`[[...slug]]` — **podwójne** nawiasy. Pojedyncze `[slug]` dają string zamiast
|
||||
tablicy (`slug.join is not a function`) i nie łapią samego `/pl`.
|
||||
**`[[...slug]]` — PODWÓJNE nawiasy** (opcjonalny catch-all). Pojedyncze `[slug]`
|
||||
dają string (`slug.join is not a function`) i nie łapią samego `/pl`.
|
||||
|
||||
```tsx
|
||||
// src/app/(frontend)/[locale]/layout.tsx
|
||||
@@ -310,8 +332,8 @@ import { notFound } from 'next/navigation'
|
||||
import { getConsentTexts, getAnalyticsConfig } from '@intecion/ipal-kit'
|
||||
import { ConsentProvider, CookieBanner, CookieButton, Analytics } from '@intecion/ipal-kit/client'
|
||||
import { i18nConfig } from '@/i18n.config'
|
||||
import { getCachedPayload, getSettings } from '@/lib/payload'
|
||||
import { getConfiguredLocales } from '@/lib/locales'
|
||||
import { getCachedPayload, getConfiguredLocales } from '@/lib/content'
|
||||
import { getSettings } from '@/lib/payload'
|
||||
import '../styles.css'
|
||||
|
||||
export default async function LocaleLayout({ children, params }) {
|
||||
@@ -325,13 +347,9 @@ export default async function LocaleLayout({ children, params }) {
|
||||
|
||||
const [texts, analytics] = await Promise.all([
|
||||
getConsentTexts({
|
||||
config: i18nConfig,
|
||||
locale,
|
||||
payload,
|
||||
privacyPolicy:
|
||||
privacyPage && typeof privacyPage === 'object'
|
||||
? { page: privacyPage, label: 'Polityka prywatności' }
|
||||
: undefined,
|
||||
config: i18nConfig, locale, payload,
|
||||
privacyPolicy: privacyPage && typeof privacyPage === 'object'
|
||||
? { page: privacyPage, label: 'Polityka prywatności' } : undefined,
|
||||
}),
|
||||
getAnalyticsConfig(payload),
|
||||
])
|
||||
@@ -343,7 +361,7 @@ export default async function LocaleLayout({ children, params }) {
|
||||
<main>{children}</main>
|
||||
<CookieBanner />
|
||||
<CookieButton />
|
||||
<Analytics {...analytics} />
|
||||
<Analytics {...analytics} /> {/* WEWNĄTRZ ConsentProvider */}
|
||||
</ConsentProvider>
|
||||
</body>
|
||||
</html>
|
||||
@@ -364,8 +382,7 @@ import { RenderBlocks } from '@intecion/ipal-kit/rsc'
|
||||
import { createPageMetadata } from '@intecion/ipal-kit'
|
||||
import { i18nConfig } from '@/i18n.config'
|
||||
import { blockRegistry } from '@/blocks/registry'
|
||||
import { getCachedPayload } from '@/lib/payload'
|
||||
import { resolvePage } from '@/lib/pages'
|
||||
import { getCachedPayload, resolveRoute } from '@/lib/content'
|
||||
|
||||
const pageMetadata = createPageMetadata({
|
||||
config: i18nConfig,
|
||||
@@ -377,104 +394,92 @@ export async function generateMetadata({ params }): Promise<Metadata> {
|
||||
return pageMetadata({ payload: await getCachedPayload(), locale, slug })
|
||||
}
|
||||
|
||||
export default async function Page({ params }) {
|
||||
export default async function Page({ params, searchParams }) {
|
||||
const { locale, slug } = await params
|
||||
const page = await resolvePage(locale, slug?.length ? slug.join('/') : null)
|
||||
if (!page) notFound()
|
||||
|
||||
return <RenderBlocks blocks={page.layout as never} components={blockRegistry} />
|
||||
const { page } = await searchParams
|
||||
const route = await resolveRoute(locale, slug ?? [], page) // 3 args
|
||||
if (!route) notFound()
|
||||
return <RenderBlocks blocks={route.doc.layout as never} components={blockRegistry} />
|
||||
}
|
||||
```
|
||||
|
||||
## 11. Środowisko
|
||||
- brak slug (`/pl`) → home przez System Pages (nie hardkod slug)
|
||||
- slug (`/pl/o-nas`) → resolveRoute po slug w danym locale
|
||||
- `depth: 2` → relacje w blokach (form) się populują
|
||||
|
||||
```bash
|
||||
# .env
|
||||
DATABASE_URL=file:./moj-projekt.db
|
||||
PAYLOAD_SECRET=<losowy-ciąg>
|
||||
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
|
||||
```
|
||||
## 11. Metadata / SEO (szczegóły)
|
||||
|
||||
`createPageMetadata` obsługuje hreflang. Kluczowe: resolveDocument pobiera
|
||||
dokument z **`locale: 'all'`** — wtedy `slug` jest mapą locale→wartość, z której
|
||||
budują się hreflang alternates. Zwykły fetch (jeden locale) → tylko string,
|
||||
hreflang nie powstanie.
|
||||
|
||||
Bez `NEXT_PUBLIC_SERVER_URL` canonical i hreflang wyjdą względne.
|
||||
|
||||
## 12. Generowanie i start
|
||||
## 12. Nagłówki bezpieczeństwa
|
||||
|
||||
```ts
|
||||
// next.config.ts
|
||||
import { buildSecurityHeaders } from '@intecion/ipal-kit'
|
||||
const securityHeaders = buildSecurityHeaders({
|
||||
hsts: process.env.NODE_ENV === 'production', // off w dev (http)
|
||||
additional: [ /* CSP projektu — zna swoje domeny */ ],
|
||||
})
|
||||
// async headers() { return [{ source: '/:path*', headers: securityHeaders }] }
|
||||
```
|
||||
Szczegóły: [security.md](./security.md).
|
||||
|
||||
## 13. Środowisko
|
||||
|
||||
```bash
|
||||
# .env
|
||||
DATABASE_URI=<postgres albo file:./dev.db>
|
||||
PAYLOAD_SECRET=<losowy-ciąg>
|
||||
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
|
||||
# Email przez Graph (opcjonalnie — sekrety agencyjne):
|
||||
# GRAPH_TENANT_ID=... GRAPH_CLIENT_ID=... GRAPH_CLIENT_SECRET=... GRAPH_SENDER=...
|
||||
```
|
||||
|
||||
## 14. Generowanie i start
|
||||
|
||||
```bash
|
||||
pnpm generate:types
|
||||
pnpm payload generate:importmap # pola SEO to komponenty admina
|
||||
pnpm payload generate:importmap # pola SEO + custom komponenty (MaskedField...)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
`generate:importmap` powtarzaj po każdej zmianie, która dokłada komponenty
|
||||
admina.
|
||||
`generate:importmap` powtarzaj po każdej zmianie dokładającej komponenty admina.
|
||||
|
||||
## 13. Konfiguracja w panelu
|
||||
## 15. Konfiguracja w panelu
|
||||
|
||||
`http://localhost:3000/admin`
|
||||
|
||||
1. **Utwórz pierwszego użytkownika** (dostanie rolę admin).
|
||||
2. **Site Settings → General** — nazwa witryny, kolejność i separator tytułu.
|
||||
3. **Pages** — utwórz stronę główną. Wypełnij tytuł **w każdym locale**
|
||||
(przełącznik u góry) — slug generuje się per język, a pusty slug w EN oznacza
|
||||
404 na `/en/…`.
|
||||
4. **Site Settings → System Pages** — wskaż Homepage. Bez tego `/pl` da 404.
|
||||
5. **Cookie Settings** — treść bannera (bez tego lecą angielskie domyślne).
|
||||
1. **Utwórz pierwszego użytkownika** (rola admin).
|
||||
2. **Site Settings → General** — nazwa witryny, tytuł.
|
||||
3. **Pages** — strona główna. Tytuł **w każdym locale** (slug per język; pusty
|
||||
slug EN = 404 na `/en/…`).
|
||||
4. **Site Settings → System Pages** — wskaż Homepage (bez tego `/pl` → 404).
|
||||
5. **Cookie Settings** — treść bannera per język.
|
||||
6. **Notifications** — teksty wyników formularza per język (opcjonalne, ma fallback).
|
||||
7. **Site Integrations → SMTP** — transport (SMTP/Graph), From Name, From Address.
|
||||
|
||||
Wejdź na `/` — powinno przekierować na `/pl` i pokazać stronę.
|
||||
Wejdź na `/` — powinno przekierować na `/pl`.
|
||||
|
||||
---
|
||||
|
||||
## Rzeczy opcjonalne
|
||||
## Opcjonalne
|
||||
|
||||
### Formularz z Turnstile
|
||||
Wymaga bloku formularza (patrz [forms.md](./forms.md)) + Site Integrations →
|
||||
Turnstile (klucze testowe Cloudflare: site `1x00000000000000000000AA`, secret
|
||||
`1x0000000000000000000000000000000AA`). Maile wysyła form-builder przez
|
||||
mailAdapter — nie pisze się ich w kodzie. Zgoda RODO: checkbox o nazwie `consent`.
|
||||
|
||||
Wymaga bloku formularza w projekcie (patrz forms.md) oraz:
|
||||
|
||||
- **Site Integrations → Turnstile** — site key i secret. Klucze testowe
|
||||
Cloudflare (zawsze przechodzą): site `1x00000000000000000000AA`, secret
|
||||
`1x0000000000000000000000000000000AA`.
|
||||
- **Site Integrations → SMTP** — host, port, user, hasło, adres nadawcy.
|
||||
- **Forms → dany formularz → Emails** — odbiorca, temat, treść (`{{*:table}}`
|
||||
wypisze wszystkie pola tabelką). Maile wysyła form-builder przez
|
||||
`panelSmtpAdapter` — nie pisze się ich w kodzie.
|
||||
|
||||
|
||||
### Blog / archiwum (kolekcja pod stroną-archiwum)
|
||||
|
||||
Pełny opis: content.md. W skrócie:
|
||||
|
||||
1. **Kolekcja** `src/collections/Posts.ts` — tytuł (localized), `buildSlugField`,
|
||||
pola, bloki. Dodaj ją do `collections` w payload.config.
|
||||
|
||||
2. **content.config.ts** obok i18n.config.ts:
|
||||
```ts
|
||||
import type { ContentOption } from '@intecion/ipal-kit'
|
||||
export const contentConfig: ContentOption = {
|
||||
collections: [{ slug: 'posts', label: 'Artykuły', perPage: 10 }],
|
||||
}
|
||||
```
|
||||
|
||||
3. **payload.config** — `content: contentConfig`, plus `posts` w `seo.collections`.
|
||||
|
||||
4. **Front** — `createContentHelpers` w `src/lib/content.ts`, `resolveRoute`
|
||||
w page.tsx (obsługa typów page/archive/entry), blok listy (EntriesList).
|
||||
|
||||
5. **Baza + typy** — nowa kolekcja to nowy schemat:
|
||||
```bash
|
||||
rm -f *.db *.db-shm *.db-wal && pnpm generate:types && pnpm dev
|
||||
```
|
||||
|
||||
6. **W panelu** — utwórz stronę „Artykuły" (w każdym locale!), dodaj do niej blok
|
||||
listy, w System Pages przypisz ją jako archiwum kolekcji posts. Dodaj wpisy.
|
||||
|
||||
Adres wpisów = slug strony-archiwum. Zmiana tytułu strony przenosi sekcję. Kolejny
|
||||
typ treści (realizacje) = kolejna kolekcja + kolejna pozycja w content.config.
|
||||
|
||||
### Sitemapa i robots.txt
|
||||
|
||||
`createContentHelpers` oddaje gotowe handlery — dodaj `i18n` i `baseUrl` do jego
|
||||
argumentów (patrz seo.md), potem dwa pliki po jednej linii:
|
||||
### Blog / archiwum
|
||||
Pełny opis: [content.md](./content.md). Kolekcja + content.config.ts +
|
||||
przypisanie strony-archiwum w System Pages.
|
||||
|
||||
### Sitemapa i robots
|
||||
```ts
|
||||
// app/sitemap.ts
|
||||
export { sitemap as default } from '@/lib/content'
|
||||
@@ -482,44 +487,22 @@ export { sitemap as default } from '@/lib/content'
|
||||
export { robots as default } from '@/lib/content'
|
||||
```
|
||||
|
||||
Sitemapa z hreflangiem per URL, lastmod, wpisami bloga; pomija drafty i noindex.
|
||||
|
||||
### Analytics
|
||||
|
||||
**Site Integrations** → GA4 Measurement ID albo GTM Container ID. Tagi ładują
|
||||
się z Consent Mode: nic nie zapisze ciasteczek, dopóki odwiedzający nie
|
||||
zaakceptuje kategorii Analytics.
|
||||
|
||||
### Przestylowanie pod klienta
|
||||
|
||||
```css
|
||||
/* styles.css */
|
||||
:root {
|
||||
--ipal-primary: #16a34a;
|
||||
--ipal-radius: 1rem;
|
||||
}
|
||||
```
|
||||
|
||||
Pełna lista tokenów: consent.md.
|
||||
|
||||
---
|
||||
|
||||
## Kiedy coś nie działa
|
||||
|
||||
| Objaw | Przyczyna |
|
||||
|---|---|
|
||||
| Pusty tab SEO / brak kolekcji Forms | rozjazd wersji `@payloadcms/*` — sprawdź `pnpm.overrides` |
|
||||
| Pusty tab SEO / brak Forms | rozjazd wersji `@payloadcms/*` — sprawdź `pnpm.overrides` |
|
||||
| `PayloadComponent not found in importMap` | `pnpm payload generate:importmap` |
|
||||
| Banner bez stylów | brak `@source` na `node_modules/@intecion/ipal-kit` albo brak Tailwinda |
|
||||
| `/admin` i `/_next` zwracają 500 | matcher w middleware nie jest inline |
|
||||
| `slug.join is not a function` | katalog `[slug]` zamiast `[[...slug]]` |
|
||||
| `Cannot destructure property 'config'` (custom pole) | dublet `@payloadcms/ui` — peerDependency (playbook D) |
|
||||
| Banner bez stylów | brak `@source` na node_modules albo brak Tailwinda |
|
||||
| `/admin` i `/_next` → 500 | matcher w proxy nie jest inline |
|
||||
| `slug.join is not a function` | `[slug]` zamiast `[[...slug]]` |
|
||||
| `/pl` → 404 | Homepage nieustawiony w System Pages |
|
||||
| `/en/cokolwiek` → 404, `/pl/cokolwiek` działa | pusty tytuł (a więc i slug) w locale EN |
|
||||
| `/en/*` → 404, `/pl/*` działa | pusty tytuł/slug w locale EN |
|
||||
| `Missing <html> and <body>` | root layout usunięty, a `[locale]/layout.tsx` ich nie ma |
|
||||
| `SQLITE_ERROR: index … already exists` | zmiana schematu — usuń `*.db *.db-shm *.db-wal` |
|
||||
| Zmiany w pluginie nie widać | Turbopack cache — `rm -rf .next` |
|
||||
| Maile nie wychodzą | brak `email: panelSmtpAdapter()` w configu albo pusty SMTP w panelu |
|
||||
| GTM ładuje się, brak `_ga` | pusty kontener — GTM sam nie ustawia ciasteczek, potrzebny opublikowany tag GA4 |
|
||||
| `/pl/artykuly` → 404 | strona nieprzypisana jako archiwum w System Pages |
|
||||
| brak pola „archive page" w panelu | brak `content` w configu albo `generate:importmap` po dodaniu |
|
||||
| wpis 404 mimo że istnieje | slug pusty w tym locale — wypełnij tytuł w danym języku |
|
||||
| Zmiany w pluginie nie widać | `rm -rf .next`; sprawdź czy wciągnięto wersję (grep node_modules) |
|
||||
| Maile nie wychodzą | brak `email: mailAdapter()` albo pusty SMTP/Graph |
|
||||
| istnieje `middleware.ts` | USUŃ — Next 16 to `proxy.ts` |
|
||||
| zaszyta mapa `localizedRoutes` | antywzorzec — `getLocalizedSlugs` z bazy |
|
||||
Reference in New Issue
Block a user