Files

T

2026-08-02 21:34:35 +00:00

4.9 KiB

Raw Blame History

@intecion/ipal-kit

Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n (routing per-locale, hreflang, przełącznik języka), SEO (metadane, canonical, sitemapa, robots), formularze (Turnstile, rate limit, walidacja), consent mode, analytics (GA4/GTM), oraz system bloga/archiwów (kolekcje pod stroną-archiwum, listing, paginacja).

Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit (dostęp tylko dla zalogowanych pracowników Intecion).

Instalacja

Serwer jest prywatny. Zarówno kod, jak i pakiet w Gitea są widoczne tylko po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji.

Krok 1 — token dostępu (raz na osobę)

W Gitea: Ustawienia → Aplikacje → Wygeneruj token dostępu. Nadaj zakresy:

read:package — do instalacji (wystarczy pracownikowi)
write:package — dodatkowo, jeśli będziesz publikować wydania

Skopiuj token (pokazuje się raz).

Krok 2 — wybierz drogę instalacji

Dwie drogi. A (rejestr Gitea) jest zalecana dla zespołu — daje wersjonowanie i szybką instalację gotowego builda. B (bezpośrednio z git) nie wymaga publikowania, ale buduje/pobiera z repo.

Droga A — rejestr npm w Gitea (zalecana)

Gitea ma wbudowany rejestr npm. Publikujesz zbudowany pakiet, pracownicy pobierają gotowy dist — bez budowania u siebie.

Konfiguracja u pracownika (instalacja)

.npmrc w projekcie albo globalnie (~/.npmrc):

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

Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — .npmrc można wtedy nawet zacommitować):

# ~/.zshrc
export GITEA_TOKEN=twój_token_z_gitea

Instalacja:

pnpm add @intecion/ipal-kit

Publikacja (osoba wydająca)

W package.json pluginu (jest już ustawione):

"publishConfig": {
  "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
}

~/.npmrc z tokenem write:package:

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

Wydanie:

pnpm clean && pnpm build
npm version patch          # 1.0.0 → 1.0.1
npm publish

Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym czyszczeniem cache. publishConfig działa poprawnie (exports z dist), nie musisz ruszać głównego exports.

Droga B — bezpośrednio z repozytorium git

Bez publikowania. pnpm klonuje repo i bierze zacommitowany dist.

Uwierzytelnienie

Serwer prywatny, więc git musi mieć dostęp. Dwie opcje:

SSH (jeśli masz klucz w Gitea):

pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git

HTTPS z tokenem:

pnpm add git+https://TWÓ[email protected]/IntecionSoftware/ipal-kit.git

Konkretny tag (stabilniej niż główny branch):

pnpm add git+https://TWÓ[email protected]/IntecionSoftware/ipal-kit.git#v1.0.0

Nie ma skrótu gitea: (jak github:). Zawsze pełny URL git+https:// lub git+ssh://.

Wymagania po stronie repo (dla wydającego)

Instalacja z git NIE buduje pakietu, więc:

dist/ musi być zacommitowany — zbuduj i zacommituj przed każdym wydaniem
BRAK prepare: pnpm build w package.json — inaczej pnpm próbuje budować i żąda onlyBuiltDependencies
główny exports wskazuje dist (nie src) — instalacja z git czyta główny exports, publishConfig jest ignorowane przy git

Po instalacji (obie drogi)

Dodaj peer-zależności — plugin ich nie zaciąga:

pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
         nodemailer lucide-react slugify server-only

Konfiguracja pluginu, krok po kroku: docs/getting-started.md.

Dokumentacja

Pełna dokumentacja w docs/. Start:

docs/getting-started.md — od zera do działającego projektu
docs/install.md — szczegóły instalacji i diagnostyka
docs/README.md — spis modułów

Diagnostyka instalacji

Objaw	Przyczyna
`404` / `Unauthorized` przy `pnpm add @intecion/...`	brak/zły token w `.npmrc`, albo brak dostępu do organizacji w Gitea
`404` na `git.intecion.net/.../ipal-kit.git`	nie zalogowany / brak tokenu w URL / brak uprawnień do repo
`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`	`prepare` w package.json (Droga B) — usuń, `dist` jest w repo
`Cannot find module .../src/...ts`	główny `exports` wskazuje src zamiast dist
stary kod mimo reinstall	cache; `pnpm store prune && rm -rf .next node_modules/@intecion`

Więcej: docs/install.md.

4.9 KiB Raw Blame History