updated docs

2026-08-01 00:27:07 +02:00
parent 7ddb8a16f0
commit 411f484b40
5 changed files with 136 additions and 6 deletions
@@ -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/[email protected] @payloadcms/[email protected] \
+            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.