160 lines
4.9 KiB
Markdown
160 lines
4.9 KiB
Markdown
# @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ć):
|
|
|
|
```bash
|
|
# ~/.zshrc
|
|
export GITEA_TOKEN=twój_token_z_gitea
|
|
```
|
|
|
|
Instalacja:
|
|
|
|
```bash
|
|
pnpm add @intecion/ipal-kit
|
|
```
|
|
|
|
### Publikacja (osoba wydająca)
|
|
|
|
W `package.json` pluginu (jest już ustawione):
|
|
```json
|
|
"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:
|
|
```bash
|
|
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):
|
|
```bash
|
|
pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git
|
|
```
|
|
|
|
**HTTPS z tokenem**:
|
|
```bash
|
|
pnpm add git+https://TWÓ[email protected]/IntecionSoftware/ipal-kit.git
|
|
```
|
|
|
|
Konkretny tag (stabilniej niż główny branch):
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
|
nodemailer lucide-react slugify server-only
|
|
```
|
|
|
|
Konfiguracja pluginu, krok po kroku: [docs/getting-started.md](./docs/getting-started.md).
|
|
|
|
---
|
|
|
|
## Dokumentacja
|
|
|
|
Pełna dokumentacja w [docs/](./docs). Start:
|
|
- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu
|
|
- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka
|
|
- [docs/README.md](./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](./docs/install.md). |