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