# Wydawanie nowej wersji


> **Instalacja jest publiczna** — rejestr Gitea pozwala pobierać pakiety bez
> tokenu. Ten plik dotyczy **publikowania** nowych wersji, co wymaga tokenu
> `write:package`. Instrukcja instalacji: główny [README](../README.md).

Dla osób rozwijających samą wtyczkę. Instalacja (dla użytkowników) jest w głównym
[README](../README.md) — ten plik dotyczy publikowania kolejnych wersji do
rejestru Gitea.

## package.json — co musi się zgadzać

Przed pierwszą publikacją sprawdź, że manifest jest poprawny — te pola były
źródłem większości problemów przy dystrybucji:

```json
{
  "name": "@intecion/ipal-kit",
  "version": "1.0.0",
  "files": ["dist"],
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": { "...": "wszystkie subpath na ./dist/*.js i ./dist/*.d.ts" },
  "publishConfig": {
    "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
  }
}
```

Kontrola przed publikacją:

```bash
grep -c '"exports"' package.json          # 1 — jeden blok, nie dwa
grep -c "git+https.*ipal-kit" package.json # 0 — brak self-reference
grep '"import"' package.json | head -1     # ./dist/ — nie ./src/
node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))" # bez błędu
```

- **`exports` na `dist`, nie `src`** — jeden blok, wszystkie ścieżki na `./dist/`.
- **jeden blok `exports`** — nie zostawiaj drugiego (np. w starym
  `publishConfig.exports`); dwa bloki rozjeżdżają rozwiązywanie modułów.
- **brak self-reference** — pakiet nie może mieć siebie w `dependencies`.
  Wchodzi, gdy odpalisz `pnpm add` w katalogu wtyczki — **nigdy tego nie rób**.
- **peer, nie dependencies** — `payload`, `next`, `react`,
  `@payloadcms/plugin-seo`, `@payloadcms/plugin-form-builder` w
  `peerDependencies`. W `dependencies` inaczej zaciągną drugą kopię Payloada.

## Rejestr — droga zalecana

Rejestr npm w Gitea. Pracownicy pobierają gotowy `dist`, nie budują u siebie.

**Token** z zakresem `write:package` (Gitea → Settings → Applications), w
globalnym `.npmrc` (ścieżka zależna od systemu — patrz tabela w głównym
[README](../README.md#route-a--from-the-registry-recommended); na Windows to
`%USERPROFILE%\.npmrc`):

```
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
```

**Wydanie:**

```bash
pnpm clean && pnpm build
npm version patch          # 1.0.0 → 1.0.1 (minor/major wg zmian)
npm publish
```

Podnoś wersję przy każdym wydaniu — pnpm rozpoznaje pakiet po numerze, więc nowy
numer znosi cały cykl czyszczenia pamięci podręcznej, który męczy przy
zostawaniu na jednej wersji.

## Alternatywa — dystrybucja z repozytorium (bez rejestru)

Jeśli nie publikujesz do rejestru, a instalujesz bezpośrednio z Gitea
(`git+https://...`), obowiązują dodatkowe reguły:

- **`dist/` musi być zacommitowany** w repozytorium — instalacja z git nie
  buduje pakietu. Buduj i commituj `dist` przed każdym wydaniem:
  ```bash
  pnpm build
  git add -f dist/          # -f, jeśli .gitignore normalnie ignoruje dist
  git commit -m "build dist"
  git push
  ```
- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować
  przy instalacji i żąda `onlyBuiltDependencies`.
- **sprawdzaj repozytorium, nie plik lokalny** — pnpm z git bierze stan repo:
  ```bash
  git show origin/main:package.json | grep '"import"' | head -1   # ./dist/
  ```
  Commit z nazwą „fix" nie znaczy, że poprawka jest w commicie.

## Weryfikacja po publikacji

W czystym projekcie testowym:

```bash
pnpm store prune
pnpm add @intecion/ipal-kit          # albo git+https://... dla drogi repo
node -e "console.log(require.resolve('@intecion/ipal-kit/next/middleware'))"
```

Ostatnia komenda ma wypisać ścieżkę do `dist/exports/next-middleware.js` — nie
błąd. Jeśli pokazuje `src/...ts`, główny `exports` wskazuje źródła zamiast builda.

## Diagnostyka

| Objaw | Przyczyna |
|---|---|
| `Cannot find module .../src/...ts` | główny `exports` na `src`; przy instalacji z git `publishConfig` jest ignorowane |
| Turbopack „Module not found" mimo pliku na dysku | dwa bloki `exports`; Node bierze zły |
| `ENOENT ...ipal-kit.tgz` | self-reference w `dependencies` |
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (droga repo) |
| stary kod mimo reinstall | pamięć podręczna; podnieś wersję albo `pnpm store prune` + `rm -rf .next node_modules/@intecion` |