updated docs
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# Jak komendy rozmawiają z git.intecion.net
|
||||
|
||||
Ten plik tłumaczy, co robi każda komenda, gdy instalujesz `@intecion/ipal-kit`.
|
||||
Rejestr pakietów jest **publiczny do odczytu** — instalacja nie wymaga tokenu.
|
||||
Token jest potrzebny tylko przy publikowaniu nowych wersji (patrz
|
||||
[publishing.md](./publishing.md)).
|
||||
|
||||
## Rejestr scoped — co to znaczy
|
||||
|
||||
W `.npmrc` masz jedną linię:
|
||||
|
||||
```
|
||||
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||
```
|
||||
|
||||
To reguła: „pakiety zaczynające się od `@intecion/` pobieraj z tego adresu".
|
||||
**Nie zmienia** domyślnego rejestru — wszystko inne (`react`, `next`,
|
||||
`@payloadcms/*`) dalej idzie z publicznego npm. To override dla jednego scope,
|
||||
nie przełączenie całego źródła.
|
||||
|
||||
Dlatego mieszana instalacja działa bez konfliktu:
|
||||
- `@intecion/ipal-kit` → Gitea
|
||||
- `react`, `payload`, `lucide-react` → npm
|
||||
|
||||
## Komenda po komendzie
|
||||
|
||||
### edycja `.npmrc` (linia z registry)
|
||||
|
||||
**Co robi:** zapisuje regułę „scope `@intecion` → rejestr Gitea". Nic nie
|
||||
pobiera — to plik konfiguracyjny, czytany dopiero przy instalacji.
|
||||
|
||||
**Rozmowa z serwerem:** żadna przy samym zapisie.
|
||||
|
||||
Ponieważ rejestr jest publiczny, ta linia **nie zawiera tokenu** — plik jest
|
||||
bezpieczny do zacommitowania i musi trafić do repo, żeby serwer deploymentu też
|
||||
wiedział, skąd brać `@intecion/*`.
|
||||
|
||||
### `pnpm add @intecion/ipal-kit`
|
||||
|
||||
**Co robi:** to komenda, która faktycznie łączy się z rejestrem.
|
||||
|
||||
Krok po kroku:
|
||||
1. pnpm widzi scope `@intecion` → sprawdza `.npmrc` → znajduje regułę „→ Gitea".
|
||||
2. Łączy się z rejestrem Gitea. Rejestr publiczny, więc **bez tokenu**.
|
||||
3. Rejestr odsyła metadane pakietu (wersje, adres `.tgz`).
|
||||
4. pnpm pobiera i rozpakowuje do `node_modules/@intecion/ipal-kit` — **czysta
|
||||
ścieżka**, bez hasha commita.
|
||||
|
||||
Ta czysta ścieżka jest ważna: komponenty klienta pluginu (baner zgód, analytics,
|
||||
Turnstile) rozwiązują się poprawnie tylko z niej. Instalacja z gita dawała
|
||||
pokręconą ścieżkę z hashem, która łamała React Client Manifest.
|
||||
|
||||
**Gdy to zawiedzie:**
|
||||
- `404` — brakuje linii `@intecion:registry` w `.npmrc`, więc pnpm poszedł do
|
||||
publicznego npm, gdzie pakietu nie ma. Sprawdź, czy `.npmrc` istnieje i ma tę
|
||||
linię.
|
||||
|
||||
### `pnpm install`
|
||||
|
||||
**Co robi:** odtwarza wszystkie zależności z `package.json` / lockfile, w tym
|
||||
`@intecion/ipal-kit`. Ta sama rozmowa z Gitea dla części `@intecion`, reszta z
|
||||
npm. Różnica względem `add`: `install` odtwarza to, co już zapisane, `add`
|
||||
dopisuje nowe.
|
||||
|
||||
## Sprawdzenie, czy rejestr odpowiada
|
||||
|
||||
Bez tokenu, publiczny endpoint:
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}\n" \
|
||||
https://git.intecion.net/api/packages/IntecionSoftware/npm/@intecion%2Fipal-kit
|
||||
```
|
||||
|
||||
`200` → rejestr działa, pakiet dostępny. `404` → zła ścieżka/nazwa.
|
||||
|
||||
## Krótkie podsumowanie
|
||||
|
||||
| Komenda | Rozmawia z serwerem? | Token? | Po co |
|
||||
|---|---|---|---|
|
||||
| edycja `.npmrc` (registry) | nie | nie | reguła scope na później |
|
||||
| `pnpm add @intecion/ipal-kit` | tak | nie (publiczny) | pobiera pakiet |
|
||||
| `pnpm install` | tak (dla @intecion) | nie | odtwarza zależności |
|
||||
| `curl .../npm/@intecion%2F...` | tak | nie | test dostępności |
|
||||
|
||||
Publikowanie wersji (osobna rola, **wymaga** tokenu `write:package`):
|
||||
[publishing.md](./publishing.md).
|
||||
@@ -0,0 +1,116 @@
|
||||
# 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` |
|
||||
Reference in New Issue
Block a user