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:

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

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.

4.7 KiB Raw Blame History