ipal-kit/docs/install.md

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

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:

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

   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:

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

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)

# 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 sedem. Rozjeżdża strukturę (dwa bloki exports). Nadpisuj cały plik.
• Zostajesz na 1.0.0? Czyść cache przy każdym reinstall:

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

  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.