diff --git a/docs/README.md b/docs/README.md index 7803514..8603689 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,8 @@ # IPAL — Dokumentacja modułów -**Stawiasz nowy projekt?** → [getting-started.md](./getting-started.md) +**Stawiasz nowy projekt?** → [install.md](./install.md) — instalacja (github/rejestr/tarball) i diagnostyka + +Konfiguracja: [getting-started.md](./getting-started.md) IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty diff --git a/docs/frontend-setup.md b/docs/frontend-setup.md index 5abd840..84edad7 100644 --- a/docs/frontend-setup.md +++ b/docs/frontend-setup.md @@ -97,6 +97,12 @@ też jedno źródło. ## Middleware +> **Next 16:** konwencja `middleware.ts` jest deprecated na rzecz `proxy.ts` +> (plik `proxy.ts`, funkcja `export function proxy`). Logika pluginu bez zmian — +> `createLocaleMiddleware` działa tak samo, zmienia się tylko nazwa pliku i +> funkcji po stronie projektu. Na razie `middleware.ts` działa z ostrzeżeniem. + + ```ts // src/middleware.ts import { NextResponse } from 'next/server' diff --git a/docs/getting-started.md b/docs/getting-started.md index 4e6d4ec..6579825 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,9 @@ # Nowy projekt — krok po kroku +> **Instalacja:** najszybciej `pnpm add github:rasm-its/ipal-kit`. Pełne drogi +> (github / rejestr / tarball) i diagnostyka błędów — install.md. + + 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). diff --git a/docs/install.md b/docs/install.md index e69de29..d3615ed 100644 --- a/docs/install.md +++ b/docs/install.md @@ -0,0 +1,118 @@ +# Instalacja ipal-kit + +Trzy drogi. Wybierz jedną i trzymaj się jej — mieszanie (raz git, raz rejestr, +raz tarball) to najczęstsze źródło błędów instalacji. + +## Droga A — z GitHuba (zalecana dla zespołu) + +Wymaga, żeby `dist/` był zacommitowany w repo (nie budowany u instalującego). + +```bash +pnpm add github:rasm-its/ipal-kit +# konkretny tag (stabilniej): +pnpm add github:rasm-its/ipal-kit#v1.0.0 +``` + +Wymagania po stronie projektu: + +1. **`onlyBuiltDependencies`** — pnpm blokuje skrypty build z paczek git. + Jeśli pakiet ma jakiekolwiek skrypty postinstall, dodaj w package.json + projektu: + ```json + "pnpm": { "onlyBuiltDependencies": ["@intecion/ipal-kit"] } + ``` + (Jeśli plugin nie ma `prepare`/postinstall — patrz niżej — to niepotrzebne.) + +2. **peer-zależności** — plugin ich nie zaciąga, projekt musi mieć: + ```bash + pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \ + nodemailer lucide-react slugify server-only + ``` + +Wymagania po stronie pluginu (raz, przy wydawaniu): + +- **`dist/` w repo** — bo instalacja z git nie buduje. Zbuduj i zacommituj + `dist` przed każdym wydaniem. +- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować + przy instalacji i żąda `onlyBuiltDependencies`. Skoro `dist` jest w repo, build + jest zbędny. +- **główny `exports` wskazuje `dist`, nie `src`** — instalacja z git czyta + główny `exports` (publishConfig działa TYLKO przy `npm publish`, nie przy git). + Wszystkie ścieżki `./dist/*.js` i `./dist/*.d.ts`. +- **jeden blok `exports`** — nie zostawiaj `publishConfig.exports` obok głównego; + dwa bloki potrafią rozjechać rozwiązywanie modułów. +- **żadnej self-reference** — pakiet nie może mieć siebie w `dependencies` + (`"@intecion/ipal-kit": "git+..."`). Wchodzi, gdy odpalisz `pnpm add` w + katalogu pluginu — NIGDY tego nie rób. + +## Droga B — GitHub Packages (rejestr) + +Publikujesz zbudowany pakiet; instalujący pobiera gotowy `dist`, nie buduje. + +Plugin — `publishConfig.registry` + token z `write:packages`: +```bash +echo "//npm.pkg.github.com/:_authToken=TOKEN" >> ~/.npmrc +npm version patch && npm publish +``` + +Projekt — `.npmrc` ze scope + token z `read:packages`: +``` +@intecion:registry=https://npm.pkg.github.com +//npm.pkg.github.com/:_authToken=TOKEN +``` +```bash +pnpm add @intecion/ipal-kit +``` + +Zaleta nad Drogą A: semver (koniec z ręcznym commitowaniem `dist`), `publishConfig` +działa (nie musisz ruszać głównego `exports`). Wada: token u każdego instalującego. + +## Droga C — lokalny tarball (development, przekazanie pliku) + +```bash +# w pluginie +pnpm build && pnpm pack --out ipal-kit.tgz + +# w PROJEKCIE (nie w pluginie!) +pnpm add ~/sciezka/ipal-kit/ipal-kit.tgz +``` + +`--out ipal-kit.tgz` daje stałą nazwę — bez tego scope zamienia `/` na `-` +(`intecion-ipal-kit-1.0.0.tgz`). + +## Twarde zasady (wyparzone w boju) + +- **NIGDY `pnpm add ...ipal-kit...` w katalogu pluginu.** Tworzy self-reference, + która zatruwa każdą kolejną instalację. Zawsze w katalogu projektu. Sprawdzaj + `pwd` przed każdym `pnpm add`. +- **Sprawdzaj REPO, nie plik lokalny.** pnpm z git bierze stan repo. Po zmianie: + `git show origin/main:package.json | grep '"import"'` — musi pokazać `./dist/`. + Commit z nazwą "fix" nie znaczy, że fix jest w commicie. +- **Nie edytuj package.json `sed`em.** Rozjeżdża strukturę (dwa bloki exports). + Nadpisuj cały plik. +- **Zostajesz na 1.0.0? Czyść cache przy każdym reinstall:** + ```bash + rm -rf node_modules/@intecion node_modules/.pnpm/*ipal-kit* .next + pnpm store prune && pnpm install + ``` + Publikacja z bumpem wersji (Droga B) to znosi. +- **Weryfikuj rozwiązanie modułu, nie tylko instalację:** + ```bash + node -e "console.log(require.resolve('@intecion/ipal-kit/next/middleware'))" + ``` + Ma wypisać ścieżkę do `dist`, nie błąd. Jeśli pokazuje `src/...ts` → główny + `exports` wskazuje src (patrz Droga A). + +## Diagnostyka — objaw → przyczyna + +| Objaw | Przyczyna | +|---|---| +| `ERR_PNPM_FETCH_404` na `@scope/...` | pakiet nieopublikowany; użyto nazwy rejestrowej zamiast `github:` | +| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json + brak `onlyBuiltDependencies` | +| `Cannot find module .../src/exports/X.ts` | główny `exports` wskazuje src; instalacja z git nie widzi publishConfig | +| `ENOENT ...ipal-kit-1.0.0.tgz` przy instalacji | self-reference w dependencies pluginu | +| Turbopack „Module not found" mimo pliku na dysku | dwa bloki exports w package.json; Node bierze zły | +| `pnpm add` przeszło, pakietu brak w node_modules | instalacja do złego katalogu, albo przerwana — sprawdź `pwd` | +| stary kod mimo reinstall (1.0.0) | cache; `pnpm store prune` + `rm -rf .next` | + +Po instalacji — konfiguracja pluginu: getting-started.md. \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 55c4445..6140011 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9,8 +9,8 @@ importers: .: dependencies: '@intecion/ipal-kit': - specifier: file:intecion-ipal-kit-1.0.0.tgz - version: file:intecion-ipal-kit-1.0.0.tgz(@payloadcms/plugin-form-builder@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(@payloadcms/plugin-seo@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react@19.2.6) + specifier: git+https://github.com/rasm-its/ipal-kit.git + version: git+https://github.com/rasm-its/ipal-kit.git#84db3be40cb8d46ca4b85e459e138f868bc5010f(@payloadcms/plugin-form-builder@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(@payloadcms/plugin-seo@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react@19.2.6) lucide-react: specifier: ^0.400.0 version: 0.400.0(react@19.2.6) @@ -1348,8 +1348,8 @@ packages: cpu: [x64] os: [win32] - '@intecion/ipal-kit@file:intecion-ipal-kit-1.0.0.tgz': - resolution: {integrity: sha512-4nKuQXeg6fZ/5fMmf4145sDx006j/KpVIMywGv7CTqqRLrZV1R6oIg+8XwFcodN5RXP+ksMwAW8bdizLc/Cdqg==, tarball: file:intecion-ipal-kit-1.0.0.tgz} + '@intecion/ipal-kit@git+https://github.com/rasm-its/ipal-kit.git#84db3be40cb8d46ca4b85e459e138f868bc5010f': + resolution: {commit: 84db3be40cb8d46ca4b85e459e138f868bc5010f, repo: https://github.com/rasm-its/ipal-kit.git, type: git} version: 1.0.0 engines: {node: ^18.20.2 || >=20.9.0, pnpm: ^9 || ^10 || ^11} peerDependencies: @@ -6617,7 +6617,7 @@ snapshots: '@img/sharp-win32-x64@0.34.5': optional: true - '@intecion/ipal-kit@file:intecion-ipal-kit-1.0.0.tgz(@payloadcms/plugin-form-builder@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(@payloadcms/plugin-seo@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react@19.2.6)': + '@intecion/ipal-kit@git+https://github.com/rasm-its/ipal-kit.git#84db3be40cb8d46ca4b85e459e138f868bc5010f(@payloadcms/plugin-form-builder@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(@payloadcms/plugin-seo@3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3))(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react@19.2.6)': dependencies: '@payloadcms/plugin-form-builder': 3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3) '@payloadcms/plugin-seo': 3.84.1(@types/react@19.2.14)(monaco-editor@0.55.1)(next@16.2.6(@babel/core@7.29.7)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(sass@1.77.4))(payload@3.84.1(graphql@16.14.2)(typescript@5.7.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.7.3)